RErecruitwithatlas
Companies

Update a company

Changed on

Use this endpoint to update an existing company in your Atlas account — refresh scalar fields, location, identities, and custom attributes (e.g. Tier, Employer Type, Headcount) without a manual CSV import.

Every field is optional — send only what you want to change. An omitted field is left untouched; sending null on a nullable field clears it. At least one updatable field must be present (otherwise 422).

Scalars & location. name, relationship, type, size, summary, overview, industry, employeeCount, ticker and location overwrite the stored value. Changing name re-indexes the company for search and refreshes the cached company name on the people who work there.

Identities are replace-all. When you send identities, the company’s existing identities are removed and the supplied set inserted. Omit the field to leave identities unchanged. URL-like values are normalised (protocol / www. stripped, lower-cased) before storage. An identity value already owned by a different company in your agency fails with 409 Conflict.

Custom attributes are replaced per attribute. For every customAttributeId you send, the company’s existing values for that attribute are removed and the supplied ones written. Attributes you don’t mention are left as-is.

Attribution. ownerEmail is optional and records which Atlas user made the change; when supplied it must match a user in your agency (otherwise 404).

Returns the full updated company — the same shape as GET /api/v1/companies/{id}.

patch/api/v1/companies/{id}

Request

Path parameters

idstring uuid required

Company ID

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

Request body

namestring

Company name (max 500 characters)

relationship'client' | 'target' | 'none'

Company relationship: client — an active client; target — a company you are targeting for new business; none — no commercial relationship (the default, and the value of companies auto-created from a person’s work history). target is a company-only value: a contact’s relationship uses prospect for the same idea. See "Relationship values" in the introduction.

type'educational' | 'government' | 'nonprofit' | 'private' | 'public' | 'null' nullable

Company type. Send null to clear.

size'1-10' | '11-50' | '51-200' | '201-500' | '501-1000' | '1001-5000' | '5001-10000' | '10001+' | 'null' nullable

Company size bucket. Send null to clear.

summarystring nullable

Short company summary. Empty strings are rejected — omit or send null to clear.

overviewstring nullable

Long-form company description. Empty strings are rejected — omit or send null to clear.

industrystring[] nullable

Industry labels (overwrites the existing set). Each label must be a known industry from the Atlas industry dictionary — matched case-insensitively and stored in the dictionary’s canonical casing; unknown labels return 422. Duplicates are silently dropped. Send null (or []) to clear.

employeeCountinteger nullable

Number of employees (precise, integer). Send null to clear.

tickerstring nullable

Stock ticker symbol. Empty strings are rejected — omit or send null to clear.

ownerEmailstring email

Email of the Atlas user the update is attributed to (acting user). Optional — must match a user in the agency when supplied, otherwise 404.

Example request

{
  "name": "Acme Corp",
  "relationship": "client",
  "size": "51-200",
  "summary": "B2B SaaS",
  "industry": [
    "Software"
  ],
  "employeeCount": 150,
  "ticker": "AAPL",
  "location": {
    "name": "London, UK",
    "locality": "London",
    "region": "England",
    "metro": "new york, new york",
    "country": "United Kingdom",
    "streetAddress": "123 Baker Street",
    "addressLine2": "Suite 200",
    "postalCode": "NW1 6XE",
    "raw": "123 Baker Street, London NW1 6XE, United Kingdom",
    "latitude": 51.523767,
    "longitude": -0.158519
  },
  "identities": [
    {
      "type": "linkedin",
      "value": "https://linkedin.com/company/acme",
      "primary": true
    }
  ],
  "customAttributes": [
    {
      "customAttributeId": "550e8400-e29b-41d4-a716-446655440000",
      "value": "Tier 1"
    },
    {
      "customAttributeId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "optionId": "9b2e4d6a-1c3f-4a8b-9e7d-2f1a6c5b4d3e"
    }
  ],
  "ownerEmail": "recruiter@agency.com"
}

Response

Company updated. All changes are applied synchronously.

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"
      }
    ]
  }
}

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

    • info

      added the new undefined enum value to the request property

    • info

      added the new undefined enum value to the request property

  • cd4bc8bbd95eRevision changes
    • info

      added the optional property to the response with the status