RErecruitwithatlas
Companies

Create a company

Changed on

Creates a new company under the caller's agency. The endpoint:

  • Requires at least one of websiteUrl or linkedinUrl — companies created without any identity become unreachable via GET /companies lookup. Submitting both is allowed; both are stored as separate identities.
  • Stores websiteUrl and linkedinUrl as CompanyIdentity rows of type website / linkedin (the identities array is read-only output).
  • Returns 409 Conflict when an existing company in the same agency already owns the supplied websiteUrl, linkedinUrl, or LinkedIn id — the underlying create service silently dedups, REST surfaces the conflict.
  • Does not accept a caller-supplied logo URL — any logo field in the body is silently stripped. The logo is populated downstream by automated enrichment (the create endpoint does not dereference caller URLs to avoid SSRF risk). Triggers enrichment / geolocation jobs in the background; PDL-derived fields (industry, ticker, location subfields) may continue to populate after the response is returned.

relationship and list visibility. An omitted relationship defaults to none, and GET /api/v1/companies excludes none companies by default — so a company created without an explicit relationship is not returned by the default list, even though the create returned 201. Send relationship: "client" or "target" on create to have the company appear in the default list, or query it with ?relationship=none (or ?relationship=client,target,none). GET /api/v1/companies/{id} always returns it regardless of relationship.

Response shape matches GET /api/v1/companies/{id} minus logo. Read logo via GET /companies/{id} once enrichment finishes.

post/api/v1/companies

Request

Request body

namestring required

Company name (max 500 characters)

websiteUrlstring nullable

Company website URL. Stored as a CompanyIdentity of type website. Bare hostnames are normalised (acme.com → https://acme.com). At least one of websiteUrl or linkedinUrl is required.

linkedinUrlstring nullable

LinkedIn company URL. Stored as a CompanyIdentity of type linkedin. At least one of websiteUrl or linkedinUrl is required.

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.

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

Company size bucket

industrystring[] nullable

Industry labels. A label that matches the Atlas industry dictionary (matched case-insensitively on the whole label) is stored in the dictionary’s canonical casing so the industry filter matches it; any other label is stored exactly as sent. Duplicate entries are silently dropped (["Tech","Tech"] → ["Tech"]). Note PATCH /companies/{id} is stricter — it rejects labels outside the dictionary.

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.

Defaults to none when omitted, and none companies are excluded from the default GET /api/v1/companies — a company created without this field is not returned by the list endpoint unless you ask for it explicitly (?relationship=none or ?relationship=client,target,none). Send client or target on create to have the company appear in the default list.

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

Company type

employeeCountinteger nullable

Number of employees (precise, integer)

tickerstring nullable

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

Example request

{
  "name": "Acme Corp",
  "websiteUrl": "https://acme.com",
  "linkedinUrl": "https://linkedin.com/company/acme",
  "summary": "B2B SaaS",
  "size": "51-200",
  "industry": [
    "Information Technology & Services"
  ],
  "relationship": "client",
  "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
  }
}

Response

Company created

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