---
title: "Find a single company by identifier"
method: GET
path: "/api/v1/companies/find-one"
tags: ["Companies"]
---

# Find a single company by identifier

`GET /api/v1/companies/find-one`

## Request

- Base URL: `https://api.recruitwithatlas.com`
- URL: `https://api.recruitwithatlas.com/api/v1/companies/find-one`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/recruitwithatlas/apis/atlas-api/docs/api/v1/companies/find-one/get.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Query parameters

- `name` string: 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.
- `linkedin_url` string: 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.
- `website` string: 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.
- `identity` string: Any identity value — searches across all company identity types

## Response `200`

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

- object
  - `status` 'ok', required
  - `data` object, nullable, required
    - `id` string, uuid, required
    - `name` string, required: Company name
    - `websiteUrl` string, nullable, required: The company's primary website as a canonical `https://…` URL, derived from the primary `website` identity (or the first one if none is flagged primary). `null` when the company has no website identity. Accepted verbatim by `GET /companies/find-one?website=`.
    - `linkedinUrl` string, nullable, required: The company's primary LinkedIn page as a canonical `https://…` URL, derived from the primary `linkedin` identity (or the first one if none is flagged primary). `null` when the company has no linkedin identity. Accepted verbatim by `GET /companies/find-one?linkedin_url=`.
    - `relationship` 'client' | 'target' | 'none', required: 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, required: Company type
    - `size` '1-10' | '11-50' | '51-200' | '201-500' | '501-1000' | '1001-5000' | '5001-10000' | '10001+' | 'null', nullable, required: Company size
    - `industry` string[], nullable, required: Array of industry labels
    - `summary` string, nullable, required: Short company summary
    - `overview` string, nullable, required: Long-form company description
    - `logo` string, nullable, required: Logo image URL
    - `employeeCount` integer, nullable, required: Number of employees
    - `ticker` string, nullable, required: Stock ticker symbol
    - `location` object, nullable, required: Company primary location, or `null` when no usable location data is on file
      - `formattedAddress` string, nullable, required: Provider-normalized "city, region, country" string
      - `city` string, nullable, required: City
      - `region` string, nullable, required: State / province
      - `country` string, nullable, required: Country
      - `metro` string, nullable, required: Metro area
      - `streetAddress` string, nullable, required: Street address line 1
      - `addressLine2` string, nullable, required: Street address line 2
      - `postalCode` string, nullable, required: Postal / zip code
      - `raw` string, nullable, required: Unstructured location string (e.g. provider-normalized address text)
      - `latitude` number, nullable, required: Latitude in decimal degrees
      - `longitude` number, nullable, required: Longitude in decimal degrees
    - `identities` object[], required: Company identities (linkedin, website, etc.)
      - `type` string, required: Identity type
      - `value` string, required: Normalised identity value, stored scheme-less (protocol and `www.` stripped) so duplicates collapse to one company. Use the top-level `websiteUrl` / `linkedinUrl` fields for ready-to-use `https://…` URLs.
      - `primary` boolean, required: Whether this is the primary identity of its type
    - `customAttributes` object[], required: Custom attribute values
      - `attributeId` string, uuid, required: Custom attribute definition ID
      - `attributeName` string, nullable, required: Attribute name
      - `attributeType` 'options' | 'text_block' | 'text_line' | 'number_input' | 'integer' | 'date' | 'null', nullable, required: Attribute type — drives the shape of each entry in `values`.
      - `values` union[], required: All values recorded for this attribute. For single-value attributes the array has one entry; for multi-select `options` attributes it may have several.
        - union: A single value entry. Shape depends on `attributeType`: - `text_line` / `text_block` → string - `integer` / `number_input` → number - `date` → ISO `YYYY-MM-DD` string - `options` → `{ optionId, optionValue }` object
          - string
          - number
          - object
            - `optionId` string, uuid, required: Selected option ID
            - `optionValue` string, nullable, required: Display value of the option
    - `owners` object[], required: Atlas users who own this company relationship (its relationship managers). A company can have several owners; the array is empty when none are assigned. Read-only — owners are managed in the Atlas app.
      - `id` string, uuid, required: Atlas user id of the owner
      - `name` string, required: Owner's full name
      - `email` string, required: Owner's email address
    - `createdAt` string, required: ISO 8601 creation timestamp
    - `updatedAt` string, required: ISO 8601 last modification timestamp
    - `deletedAt` string, nullable, required: ISO 8601 soft-delete timestamp. `null` for live companies; populated for tombstones (only returned when `includeDeleted=true` on the list endpoint)

## Other responses

- `401`: Unauthorized - missing or invalid API key
- `422`: Validation error - the request failed schema validation (`errors.fieldErrors`) or a business rule (`errors.formErrors`)
- `429`: Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the "Rate limits" section of the introduction for details.
- `500`: Internal server error

## Changes

- **2026-11-03** `158ee454751c`: 3 warning
  - added the new `undefined` enum value to the `data/customAttributes/items/attributeType` response property for the response status `200`
  - added the new `undefined` enum value to the `data/size` response property for the response status `200`
  - added the new `undefined` enum value to the `data/type` response property for the response status `200`
- **2026-10-03** `cd4bc8bbd95e`: 1 info
  - added the optional property `error` to the response with the `422` status

[Operation history](https://skmtc.dev/recruitwithatlas/apis/atlas-api/changes/api/v1/companies/find-one/get.md)

---

[API](https://skmtc.dev/recruitwithatlas/apis/atlas-api.md) - [All operations](https://skmtc.dev/recruitwithatlas/apis/atlas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/recruitwithatlas/apis/atlas-api/revisions/158ee454751c?raw)