> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datalayer.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a company

> Retrieve one full company profile by exactly one returned company ID or website domain. A new successful profile uses one allowance unit; canonical repeats within 24 hours of the paid retrieval are included for the same account.

Supply exactly one returned `company_id` or bare website `domain`, such as
`example.com`. Do not include a URL scheme or path in a domain.

If a domain matches more than one company, search first and use a returned ID.
A successful new lookup uses one profile; eligible repeats are included.
Send `Idempotency-Key` to make [retries safe](/api-reference/usage).


## OpenAPI

````yaml POST /v1/companies/lookup
openapi: 3.1.0
info:
  title: Datalayer API
  version: 0.2.0
  description: >-
    Four account-scoped company and people operations. Private preview: account
    access is restricted and paid checkout is not enabled. An active profile
    allowance is required. Searches are included; successful new lookups use one
    profile unless covered by an eligible 24-hour repeat or idempotent replay.
    REST and MCP share the same allowance. Work-email checks are opt-in;
    delivery and ownership are not guaranteed.
servers:
  - url: https://api.datalayer.so
    description: Production API (private preview)
security:
  - bearerAuth: []
paths:
  /v1/companies/lookup:
    post:
      summary: Get company
      description: >-
        Retrieve one full company profile by exactly one returned company ID or
        website domain. A new successful profile uses one allowance unit;
        canonical repeats within 24 hours of the paid retrieval are included for
        the same account.
      operationId: get_company
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              properties:
                company_id:
                  type: string
                  pattern: ^[1-9][0-9]{0,19}$
                domain:
                  type: string
                  pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$
                  description: >-
                    Website domain, without scheme/path. Input is trimmed and
                    normalized to lowercase.
              additionalProperties: false
              oneOf:
                - required:
                    - company_id
                  not:
                    required:
                      - domain
                - required:
                    - domain
                  not:
                    required:
                      - company_id
            example:
              company_id: '123'
      responses:
        '200':
          description: Normalized data with current shared account usage metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataResponse'
              examples:
                synthetic:
                  summary: Synthetic example; not a real profile or live request
                  value:
                    data:
                      company_id: '123'
                      name: Example Company
                      website: https://example.com/
                      profile_url: null
                      description: null
                      logo_url: null
                      founded_year: null
                      company_type: null
                      employee_count: null
                      employee_size: null
                      headquarters:
                        city: null
                        region: null
                        country: null
                      locations: []
                      industries: []
                      specialties: []
                      industry_codes:
                        sic: []
                        naics: []
                      source_updated_at: null
                      coverage_note: >-
                        Employee counts and size bands are separate provider
                        observations and may disagree. Current staffing is not
                        independently verified.
                    meta:
                      request_id: example-request-001
                      retrieved_at: '2026-09-21T12:00:00Z'
                      upstream_requests: 1
                      billing_status: profile_deducted
                      profiles_used: 1
        '400':
          description: Invalid JSON, input, or Idempotency-Key. No profile deducted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or revoked account API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: >-
            No active profile grant, or no allowance available at settlement. No
            profile returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No matching company or person identity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Data operations require POST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            Idempotency conflict; company domain lookup may also require
            disambiguation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body exceeds 16 KiB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: >-
            Account data-operation limit (60 requests per fixed minute) or
            provider rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: >-
            Provider failure, timeout, invalid/unidentifiable profile, or
            unsupported response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            Temporary application/database failure or a cancelled/over-budget
            request. The API checks a 40-second elapsed budget before
            settlement, but transport failure after commit starts can leave a
            completed deduction. Retry with the same Idempotency-Key; a timeout
            alone does not prove zero usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Recommended for lookup retries. A key is scoped to this account and
        bound to the normalized operation/input. Reuse it only for the same
        request within 24 hours; changed input, an expired key, or a different
        resolved profile returns 409. A replay refetches data but deducts no
        additional profile. If omitted, the server creates a request ID. A
        network failure after database commit starts can leave a completed
        deduction; a timeout alone does not imply zero usage.
      schema:
        type: string
        minLength: 1
        maxLength: 128
        pattern: ^[A-Za-z0-9_-]{1,128}$
  schemas:
    DataResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: object
          description: >-
            Normalized search results or profile. Search results are previews.
            Full profile fields may be null when unavailable.
          properties:
            work_email:
              $ref: '#/components/schemas/WorkEmail'
          additionalProperties: true
        meta:
          $ref: '#/components/schemas/UsageMetadata'
      additionalProperties: false
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
          additionalProperties: false
      additionalProperties: false
    WorkEmail:
      type: object
      required:
        - status
        - emails
      properties:
        status:
          type: string
          enum:
            - not_requested
            - available
            - no_current_employer_match
        emails:
          type: array
          maxItems: 5
          items:
            type: object
            required:
              - email
              - classification
              - employer_domain_match
              - verification_status
              - checked_at
              - is_catch_all
            properties:
              email:
                type: string
                format: email
              classification:
                type: string
                const: provider_tagged_business
              employer_domain_match:
                type: boolean
                const: true
              verification_status:
                type: string
                enum:
                  - valid
                  - invalid
                  - uncertain
                  - not_checked
                description: >-
                  Bounded provider validation. Catch-all is uncertain; failed,
                  stale or unsupported checks are not_checked.
              checked_at:
                type:
                  - string
                  - 'null'
                format: date-time
              is_catch_all:
                type:
                  - boolean
                  - 'null'
            additionalProperties: false
        note:
          type: string
      additionalProperties: false
      description: >-
        Only explicitly requested provider-tagged business addresses matching
        the observed employer website domain are included. Verification does not
        prove ownership or guarantee delivery.
    UsageMetadata:
      type: object
      required:
        - request_id
        - retrieved_at
        - upstream_requests
        - billing_status
        - profiles_used
      properties:
        request_id:
          type: string
          description: Account-scoped request/idempotency identifier.
        retrieved_at:
          type: string
          format: date-time
          description: >-
            UTC time of this retrieval, including a replay that refetches
            provider data.
        upstream_requests:
          type: integer
          minimum: 0
          description: >-
            Number of MixRank requests made for this operation, including
            requested email checks.
        billing_status:
          type: string
          enum:
            - search_included
            - profile_deducted
            - repeat_included
            - idempotent_replay
          description: >-
            Whether this response created a new profile deduction or was
            included.
        profiles_used:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Actual profile deduction caused by this request. Included searches,
            qualifying repeats and idempotent replays are 0.
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Datalayer API key
      description: >-
        Send Authorization: Bearer dl_live_<64 lowercase hexadecimal
        characters>. Approved users can create account-scoped, revocable keys in
        the Datalayer dashboard. A key does not grant a profile allowance.
        Dashboard session cookies are not API credentials.

````