jid-com Search API

openapi: 3.2.0
info:
  title: Jid Search API
  version: 1.3.0
  summary: The trust API for AI agents.
  description: 'Before an agent pays, signs, books, hires or buys, Jid checks the business it is dealing with: real, active, licensed for this activity, not sanctioned, with the receipts. Every fact is cited to the registry that issued it. Decisions apply the published rules (https://jid.com/decision-rules, version 2026-10-15.1) and are not legal advice. No key: 10 requests a minute and 100 a day per IP. A free key (no card) includes 1,000 checks a month. Business information only; not a consumer report and not for FCRA purposes.'
  termsOfService: https://jid.com/api-terms
  contact:
    name: Jid
    email: hello@jid.com
    url: https://jid.com
servers:
- url: https://jid.com
security:
- {}
- bearer: []
tags:
- name: Search
paths:
  /v1/search:
    get:
      tags:
      - Search
      operationId: searchBusinesses
      summary: Resolve a name or registry number to candidate files
      description: 'Free (not a check). Identifiers first (FEI, LEI, CIK, DUNS, NDC labeler, USDOT, NPI, EIN, UEI, state numbers, French SIREN/SIRET), then name: exact, begins with, contains, similar. A SIREN or SIRET no file holds is looked up live on SIRENE (France) and becomes a file; with country=FR a name is also searched on SIRENE (up to 5 business units, filed on demand, listed first).'
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 200
      - name: country
        in: query
        required: false
        description: ISO 3166-1 alpha-2. FR also searches the French SIRENE register live.
        schema:
          type: string
          pattern: ^[A-Za-z]{2}$
      responses:
        '200':
          description: Candidates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
components:
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
          - code
          - message
    WebsiteDeclared:
      type: object
      description: 'What a company''s own website states about itself (provenance tier website_declared): identity context only, never a registry result. Present only when no Jid file holds or is associated with the domain.'
      properties:
        tier:
          type: string
          enum:
          - website_declared
        domain:
          type: string
        legal_name:
          type: string
          description: As printed, with its legal form
        trade_name:
          type:
          - string
          - 'null'
        address:
          type:
          - string
          - 'null'
          description: As printed; null when the site prints addresses in several states
        state:
          type:
          - string
          - 'null'
        postal_code:
          type:
          - string
          - 'null'
        source_url:
          type: string
        read_at:
          type: string
          format: date-time
        how:
          type: string
        note:
          type: string
    SearchResponse:
      type: object
      properties:
        query:
          type: string
        results:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              kind:
                type: string
              status:
                type: string
              status_summary:
                type:
                - string
                - 'null'
              matched_on:
                type: string
              url:
                type: string
              verify_url:
                type: string
        website_declared:
          type: array
          description: Businesses with no Jid file whose own website names them (tier website_declared). Not files and not confirmed by an official register.
          items:
            $ref: '#/components/schemas/WebsiteDeclared'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: 'jid_live_... key from https://jid.com/pricing (free key: no card).'
externalDocs:
  description: API reference
  url: https://jid.com/api-docs