Bridge Sandbox API

openapi: 3.2.0
info:
  title: Bridge API Keys Sandbox API
  description: APIs to move into, out of, and between any form of a dollar
  version: '1'
servers:
- url: https://api.bridge.xyz/v0
  description: The base path for all resources
security:
- ApiKey: []
tags:
- name: Sandbox
paths:
  /customers/{customerID}/simulate_kyc_approval:
    parameters:
    - $ref: '#/components/parameters/CustomerIDParameter'
    post:
      summary: Simulate KYC approval (sandbox only)
      tags:
      - Sandbox
      parameters:
      - $ref: '#/components/parameters/IdempotencyKeyParameter'
      description: 'Simulates a KYC/KYB approval for a customer in the sandbox environment. This endpoint is not available in production.


        Mimics what happens when a customer completes identity verification through the KYC provider in production:

        - Sets the customer''s KYC status to `approved`

        - Populates required entity data (name, address, date of birth) using any data already on the customer, falling back to sandbox defaults

        - Approves any pending endorsements, enabling the customer to initiate transfers


        Useful for testing the full customer lifecycle without integrating with a real KYC provider.

        '
      responses:
        '200':
          description: KYC approval simulated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulateKycApprovalResponse'
              examples:
                SimulateKycApprovalResponse:
                  $ref: '#/components/examples/SimulateKycApprovalResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
components:
  schemas:
    SimulateKycApprovalResponse:
      type: object
      description: Response from the simulate KYC approval endpoint
      required:
      - success
      - customer_id
      - kyc_status
      - message
      properties:
        success:
          type: boolean
          description: Whether the simulation succeeded
        customer_id:
          type: string
          description: The ID of the customer whose KYC was simulated
        kyc_status:
          $ref: '#/components/schemas/KycStatus'
        message:
          type: string
          description: Human-readable description of what was processed
    KycStatus:
      type: string
      description: Status of the KYC flow.
      enum:
      - not_started
      - incomplete
      - awaiting_questionnaire
      - awaiting_ubo
      - under_review
      - approved
      - rejected
      - paused
      - offboarded
    Id:
      description: A UUID that uniquely identifies a resource
      type: string
      pattern: '[a-z0-9]*'
      minLength: 1
      maxLength: 42
    Error:
      required:
      - code
      - message
      properties:
        code:
          type: string
          minLength: 1
          maxLength: 256
        message:
          type: string
          minLength: 1
          maxLength: 512
        source:
          title: ErrorSource
          required:
          - location
          - key
          properties:
            location:
              type: string
              enum:
              - path
              - query
              - body
              - header
            key:
              type: string
              description: Comma separated names of the properties or parameters causing the error
  responses:
    UnexpectedError:
      description: Unexpected error. User may try and send the request again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            UnexpectedError:
              summary: An unexpected error
              value:
                errors:
                - code: unexpected
                  message: An expected error occurred, you may try again later
    NotFoundError:
      description: No resource found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            NotFoundErrorExample:
              summary: Invalid customer id
              value:
                code: Invalid
                message: Unknown customer id
    AuthenticationError:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            MissingTokenError:
              summary: No Api-Key header
              description: The header may be missing or misspelled.
              value:
                code: required
                location: header
                name: Api-Key
                message: Missing Api-Key header
            InvalidTokenError:
              summary: Invalid key in Api-Key header
              value:
                code: invalid
                location: header
                name: Api-Key
                message: Invalid Api-Key header
  parameters:
    CustomerIDParameter:
      name: customerID
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Id'
    IdempotencyKeyParameter:
      in: header
      name: Idempotency-Key
      required: true
      schema:
        type: string
  examples:
    SimulateKycApprovalResponse:
      summary: Successful KYC simulation response
      value:
        success: true
        customer_id: 00000000-0000-0000-0000-000000000000
        kyc_status: approved
        message: Simulated KYC approval processed. Customer endorsements will be evaluated.
  securitySchemes:
    ApiKey:
      type: apiKey
      name: Api-Key
      in: header