RErecruitwithatlas
Companies

List companies

Changed on

Returns a paginated list of companies under the caller's agency, newest first.

Filters:

  • relationship — comma-separated relationships (client, target, none). Defaults to client,target — none companies are excluded unless you request them explicitly (e.g. ?relationship=none or ?relationship=client,target,none). none is the relationship of every company auto-created from a person’s experience, enrichment, or import — and the default for a company created via POST /api/v1/companies without an explicit relationship — so they are omitted from the sync surface by default.
  • name — case-insensitive partial match on the company name.
  • createdAfter / createdBefore — only companies created within the range (inclusive).
  • updatedAfter / updatedBefore — only companies 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 companies are excluded by default. Pass includeDeleted=true to also receive deleted companies 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.

Pagination: By default the list is offset-paginated (page / pageSize) and the response's pagination object carries page, pageSize, total, and totalPages.

  • For large agencies, full crawls, or incremental syncs, prefer keyset (cursor) pagination: set paginate=cursor. In this mode page is ignored, the expensive total COUNT is skipped, and paging stays stable while the list changes underneath a long sync. For the default newest-first crawl (live rows) it also stays fast at any depth; combining cursor mode with includeDeleted=true or a narrow updatedAfter/updatedBefore window can still be slow on very large agencies (those paths are not yet index-optimized). The response pagination object then carries pageSize, hasMore, and nextCursor (total/totalPages are omitted). Request page 1 with just paginate=cursor (no cursor), then replay pagination.nextCursor.cursorDate + cursorId on each subsequent request until nextCursor is null (equivalently hasMore is false). Both cursor halves must be sent together — a half-cursor is a 422. When paginate is omitted, a cursorDate + cursorId pair activates cursor mode on its own; combining a cursor pair with an explicit paginate=offset is contradictory and is rejected with 422.

Each item has the same shape as GET /api/v1/companies/{id}, including location, identities, custom attributes, and owners.

get/api/v1/companies

Request

Query parameters

relationshipstring

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

Default (when omitted): client,target — none companies are excluded. none is the relationship of every company auto-created from a person’s work experience, enrichment, or import (the large majority of companies), so the sync surface excludes them by default. To include them, request none explicitly — e.g. ?relationship=none or ?relationship=client,target,none.

Example:client,target
namestring

Filter by company name (case-insensitive partial match)

Example:Acme
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 companies 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

paginate'offset' | 'cursor'

Pagination strategy. offset (the default when omitted) uses page/pageSize and returns total/totalPages. cursor uses keyset pagination (cursorDate + cursorId) and skips the expensive total COUNT — recommended for full crawls and incremental syncs; it stays fast at any depth for the default newest-first crawl, though includeDeleted=true or a narrow updatedAfter/updatedBefore window can still be slow on very large agencies. When paginate is omitted, passing cursorDate/cursorId infers cursor; combining an explicit paginate=offset with a cursor pair is rejected with 422.

Example:offset
cursorDatestring date-time

Keyset pagination cursor (used with paginate=cursor): pass back the pagination.nextCursor.cursorDate from the previous response. Must be sent together with cursorId. Omit for the first page. When cursor mode is active page is ignored and total/totalPages are omitted from the response — walk pages until nextCursor is null.

Example:2026-01-05T12:00:00.123456Z
cursorIdstring uuid

Keyset pagination cursor id (used with paginate=cursor): pass back the pagination.nextCursor.cursorId from the previous response. Must be sent together with cursorDate.

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

Response

Paginated list of companies

status'ok' required

Example response

{
  "data": [
    {
      "name": "Acme Corp",
      "websiteUrl": "https://acme.com",
      "linkedinUrl": "https://linkedin.com/company/acme",
      "relationship": "client",
      "industry": [
        "Technology"
      ],
      "employeeCount": 150,
      "ticker": "AAPL",
      "location": {
        "formattedAddress": "San Francisco, California, United States",
        "city": "San Francisco",
        "region": "California",
        "country": "United States",
        "metro": "San Francisco Bay Area",
        "raw": "London, England, United Kingdom",
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "identities": [
        {
          "type": "linkedin",
          "value": "linkedin.com/company/acme"
        }
      ],
      "owners": [
        {
          "name": "Jane Smith",
          "email": "jane@agency.com"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "total": 42,
    "totalPages": 2
  }
}

Changes

  • 158ee454751cRevision changes
    • warning

      added the new undefined enum value to the //// response property for the response status

    • warning

      added the new undefined enum value to the // response property for the response status

    • warning

      added the new undefined enum value to the // response property for the response status

  • cd4bc8bbd95eRevision changes
    • info

      added the optional property to the response with the status