RErecruitwithatlas
Companies

Find a single company by identifier

Changed on

Finds a single company in your agency matching one of the provided identifiers. At least one of name, linkedin_url, website, or identity must be provided. If multiple are provided they are evaluated as OR in this precedence order — linkedin_url → website → identity → name — and the first match wins. The name lookup matches case-insensitively with fuzzy tolerance: exact matches win, then case-insensitive substring, then typo-tolerant (trigram) similarity, and the single best-scoring company is returned. linkedin_url and website accept either a full https://… URL or the scheme-less value returned in a company’s identities / linkedinUrl / websiteUrl (e.g. acme.com), so a value read from GET /companies/{id} can be passed straight back. Returns full company details including location, identities, custom attributes, and owners.

get/api/v1/companies/find-one

Request

Query parameters

namestring

Company name. Matched case-insensitively with typo-tolerant full-text ranking — the single best-scoring company in the caller's agency is returned.

Note: name matching uses an asynchronous search index that is eventually consistent with the primary store. A company created via POST /companies may take a short interval (typically sub-second, occasionally longer under load) to become discoverable via ?name=. Clients that need read-your-writes semantics should look the company up by linkedin_url, website, or the id returned from POST /companies instead.

Example:Acme Corp
linkedin_urlstring

LinkedIn company URL. Bare hostnames / scheme-less slugs are accepted and normalised (linkedin.com/company/acme → https://linkedin.com/company/acme), so the value returned in a company’s linkedin identity can be passed back verbatim.

Example:https://linkedin.com/company/acme
websitestring

Company website URL. Bare hostnames are accepted and normalised (acme.com → https://acme.com), so the value returned in a company’s website identity can be passed back verbatim.

Example:https://acme.com
identitystring

Any identity value — searches across all company identity types

Example:https://github.com/acme

Response

Lookup succeeded. data is the matched company, or null when no company matched the supplied identifiers.

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

  • cd4bc8bbd95eRevision changes
    • info

      added the optional property to the response with the status