jid-com Verify API

openapi: 3.2.0
info:
  title: Jid Verify 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: Verify
  description: Decisions, files and receipts
paths:
  /v1/entities/{id}/verify:
    get:
      tags:
      - Verify
      operationId: verifyBusiness
      summary: Verify a business before acting; with an activity, get a decision and a signed…
      description: 'One check. Without activity, jurisdiction or amount: status, flags and every current fact with its receipts (unchanged since 1.0). With any of them: also `decision` (proceed | review | stop | insufficient_data) with reasons, and `receipt` (stored 13 months, Ed25519-signed). Act only on proceed; requirements Jid cannot check are unknown and lead to review.'
      parameters:
      - name: id
        in: path
        required: true
        description: Jid file id, as returned by search (e.g. gland-pharma-limited-j9nehi).
        schema:
          type: string
      - name: activity
        in: query
        required: false
        description: 'What the business is about to do for you. Default general_commerce when jurisdiction or amount is given. Rules: https://jid.com/decision-rules'
        schema:
          type: string
          enum:
          - general_commerce
          - sell_prescription_drugs
          - manufacture_drugs
          - sell_medical_devices
          - haul_freight
          - broker_freight
          - sell_alcohol
          - produce_spirits
          - provide_investment_advice
          - accept_deposits
          - lend
          - bill_medicare_medicaid
          - healthcare_supplier
          - federal_contracting
          - charitable_solicitation
          - construction
          - operate_psilocybin_healing_center
      - name: jurisdiction
        in: query
        required: false
        description: US state as US-XX (e.g. US-CO) or ISO 3166-1 alpha-2 country code.
        schema:
          type: string
          pattern: ^(US-[A-Z]{2}|[A-Z]{2})$
      - name: amount
        in: query
        required: false
        description: 'Transaction amount. Context only: recorded on the receipt, never changes the rules.'
        schema:
          type: number
          minimum: 0
      - name: currency
        in: query
        required: false
        description: ISO 4217 code for amount. Default USD.
        schema:
          type: string
          pattern: ^[A-Z]{3}$
      responses:
        '200':
          description: The file, and the decision when requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
        '400':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
  /v1/entities/{id}:
    get:
      tags:
      - Verify
      operationId: getBusinessFile
      summary: 'The full file: verify plus location, owner statements, possible matches and the…'
      parameters:
      - name: id
        in: path
        required: true
        description: Jid file id, as returned by search (e.g. gland-pharma-limited-j9nehi).
        schema:
          type: string
      responses:
        '200':
          description: File
          content:
            application/json:
              schema:
                type: object
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
  /v1/receipts/{receipt_id}:
    get:
      tags:
      - Verify
      operationId: getReceipt
      summary: Retrieve a signed verification receipt
      description: Free; not a check. Readable by anyone holding the receipt id, so it can be shown to an auditor or counterparty. Verify `signature.sig` over the canonical statement with the key at /.well-known/jid-keys.json.
      parameters:
      - name: receipt_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^rcpt_[A-Za-z0-9]{22}$
      responses:
        '200':
          description: Receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
  /v1/activities:
    get:
      tags:
      - Verify
      operationId: listActivities
      summary: 'The published decision rules: activities, requirements, legal basis'
      responses:
        '200':
          description: Rules
          content:
            application/json:
              schema:
                type: object
components:
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Receipt:
      type: object
      properties:
        receipt_id:
          type: string
        url:
          type: string
        statement:
          type: object
          description: 'Exactly what was signed: type, version, receipt_id, issued_at, issuer, entity, inputs, decision, rules_version, reasons (code, met, effect, fact_ids, source, verified_at, fresh_until), facts (id, predicate, source, value_sha256, verified_at), terms.'
        signature:
          type: object
          properties:
            alg:
              const: Ed25519
            kid:
              type: string
            canonicalization:
              const: sorted-keys-json
            sig:
              type: string
              description: base64url
        verify:
          type: string
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
          - code
          - message
    Fact:
      type: object
      properties:
        predicate:
          type: string
        label:
          type: string
        value: {}
        source:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            agency:
              type:
              - string
              - 'null'
        source_url:
          type:
          - string
          - 'null'
        observed_at:
          type:
          - string
          - 'null'
        verified_at:
          type: string
          format: date-time
        next_check_at:
          type: string
          format: date-time
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
        snapshot_sha256:
          type:
          - string
          - 'null'
    Decision:
      type: object
      properties:
        decision:
          type: string
          enum:
          - proceed
          - review
          - stop
          - insufficient_data
        activity:
          type: string
          enum:
          - general_commerce
          - sell_prescription_drugs
          - manufacture_drugs
          - sell_medical_devices
          - haul_freight
          - broker_freight
          - sell_alcohol
          - produce_spirits
          - provide_investment_advice
          - accept_deposits
          - lend
          - bill_medicare_medicaid
          - healthcare_supplier
          - federal_contracting
          - charitable_solicitation
          - construction
          - operate_psilocybin_healing_center
        jurisdiction:
          type:
          - string
          - 'null'
        amount:
          type:
          - number
          - 'null'
        currency:
          type:
          - string
          - 'null'
        reasons:
          type: array
          items:
            $ref: '#/components/schemas/Reason'
        notes:
          type: array
          items:
            type: string
        rules_version:
          type: string
        rules_url:
          type: string
        not_legal_advice:
          type: string
        receipt_id:
          type: string
    VerifyResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        url:
          type: string
        file_checked_at:
          type: string
        owner_status:
          type: string
        status:
          type: object
          properties:
            status:
              type: string
              enum:
              - active
              - attention
              - inactive
              - unknown
            summary:
              type: string
            flags:
              type: array
              items:
                type: object
            rules_version:
              type: string
        identifiers:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              value:
                type: string
              source:
                type: string
        facts:
          type: array
          items:
            $ref: '#/components/schemas/Fact'
        not_in_sources:
          type: array
          items:
            type: string
        terms:
          type: string
        decision:
          $ref: '#/components/schemas/Decision'
        receipt:
          $ref: '#/components/schemas/Receipt'
    Reason:
      type: object
      required:
      - code
      - requirement
      - met
      - fact_ids
      properties:
        code:
          type: string
        requirement:
          type: string
        kind:
          type: string
          enum:
          - registration
          - flag
          - unheld
        met:
          oneOf:
          - type: boolean
          - type: string
            const: unknown
        effect:
          type:
          - string
          - 'null'
          enum:
          - stop
          - review
          - null
        detail:
          type: string
        fact_ids:
          type: array
          items:
            type: string
        source:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
            name:
              type: string
            agency:
              type: string
        source_url:
          type:
          - string
          - 'null'
        verified_at:
          type:
          - string
          - 'null'
          format: date-time
        fresh_until:
          type:
          - string
          - 'null'
          format: date-time
        authority:
          type: string
  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