> ## 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.

# Search companies

> Find brief company previews by keyword with bounded pagination. An empty search succeeds with an empty results array. Included with an active profile grant; no profile deduction.

Find compact company previews by keyword. Country and company-size filters are
not supported. Use a returned company ID for [company lookup](/api-reference/get-company).

Searches use zero profiles but require an active allowance and count toward the
account request limit.


## OpenAPI

````yaml POST /v1/companies/search
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/search:
    post:
      summary: Search companies
      description: >-
        Find brief company previews by keyword with bounded pagination. An empty
        search succeeds with an empty results array. Included with an active
        profile grant; no profile deduction.
      operationId: search_companies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 200
                limit:
                  default: 10
                  type: integer
                  minimum: 1
                  maximum: 25
                offset:
                  default: 0
                  type: integer
                  minimum: 0
                  maximum: 1000
              required:
                - query
              additionalProperties: false
            example:
              query: Example
              limit: 10
              offset: 0
      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:
                      results:
                        - company_id: '123'
                          name: Example Company
                          website: https://example.com/
                          industries: []
                          headquarters:
                            city: null
                            region: null
                            country: null
                          employee_size: null
                          description: null
                          source_updated_at: null
                      offset: 0
                      limit: 10
                      total: 1
                    meta:
                      request_id: example-request-001
                      retrieved_at: '2026-09-21T12:00:00Z'
                      upstream_requests: 1
                      billing_status: search_included
                      profiles_used: 0
        '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'
        '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:
  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.

````