RErecruitwithatlas
Contacts

List company contacts

Changed on

Returns a paginated list of company contacts under the caller's agency, newest first. A contact is the link between a person and a company (company_contacts); each person has at most one live contact.

Filters:

  • relationship — comma-separated relationships (client, prospect, none). Every row is returned by default, including none links.
  • personId — return only the contact for a single person.
  • companyId — return only contacts linked to a single company.
  • createdAfter / createdBefore — only contacts created within the range (inclusive).
  • updatedAfter / updatedBefore — only contacts updated within the range (inclusive). Use updatedAfter as an incremental-sync cursor: persist the maximum updatedAt you receive and pass it back on the next poll to fetch only what changed (upsert by id to stay idempotent).

Deletions (tombstones): Soft-deleted contacts are excluded by default. Pass includeDeleted=true to also receive deleted contacts as tombstones — each carries a populated deletedAt (live rows have deletedAt: null). Combine includeDeleted=true with updatedAfter to incrementally pick up deletions: a soft-delete bumps updatedAt, so the deleted row resurfaces in the next poll with deletedAt set.

get/api/v1/contacts

Request

Query parameters

relationshipstring

Comma-separated contact relationships to filter by (client, prospect, none). These are contact values; companies use client, target, none instead.

Example:client,prospect
personIdstring uuid

Filter to the contact row for a single person

Example:550e8400-e29b-41d4-a716-446655440000
companyIdstring uuid

Filter to contacts linked to a single company

Example:550e8400-e29b-41d4-a716-446655440000
string
OR
string date-time
string
OR
string date-time
string
OR
string date-time
string
OR
string date-time
includeDeleted'true' | 'false'

Include soft-deleted contacts as tombstones (with a populated deletedAt). Defaults to false. Pair with updatedAfter to incrementally sync deletions.

Example:false
order'asc' | 'desc'

Sort order by createdAt (record creation time) — desc (default, newest first) or asc (oldest first). id is used as a stable tie-breaker, applied in the same direction.

Example:desc
pageinteger

Page number (1-indexed)

Example:1
pageSizeinteger

Items per page (max 100)

Example:25
perPageinteger

Alias for pageSize

Response

Paginated list of company contacts

status'ok' required

Example response

{
  "data": [
    {
      "relationship": "client",
      "title": "Head of Talent",
      "person": {
        "firstName": "Michael",
        "lastName": "Scott"
      },
      "company": {
        "name": "Acme Corp"
      },
      "createdBy": {
        "name": "Jane Recruiter",
        "email": "jane@agency.com"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "total": 42,
    "totalPages": 2
  }
}

Changes