Bridge KYC Links API

openapi: 3.2.0
info:
  title: Bridge API Keys KYC Links 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: KYC Links
paths:
  /kyc_links:
    post:
      summary: Generate the Links needs to complete KYC for an individual or business
      tags:
      - KYC Links
      parameters:
      - $ref: '#/components/parameters/IdempotencyKeyParameter'
      requestBody:
        description: Information about the customer to create KYC Links for
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKycLinks'
      responses:
        '200':
          description: KYC Links generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndividualKycLinkResponse'
              examples:
                SuccessfulLiquidationAddressCreateResponse:
                  summary: KYC Links generated
                  $ref: '#/components/examples/SuccessfulKycLinkCreateResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
    get:
      summary: Get all KYC links.
      description: Retrieve the full list of kyc links.
      tags:
      - KYC Links
      parameters:
      - $ref: '#/components/parameters/KycLinksCustomerIDParameter'
      - $ref: '#/components/parameters/KycLinksEmailParameter'
      - $ref: '#/components/parameters/CustomerStartingAfterParameter'
      - $ref: '#/components/parameters/CustomerEndingBeforeParameter'
      - $ref: '#/components/parameters/LimitParameter'
      responses:
        '200':
          description: Successful KYC links status response
          content:
            application/json:
              schema:
                title: Kyc Links
                type: object
                required:
                - count
                - data
                properties:
                  count:
                    description: total number of items in data
                    type: integer
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/IndividualKycLinkResponse'
              examples:
                KycLinksGetResponse:
                  summary: KYC link status for multiple customers
                  $ref: '#/components/examples/KycLinksGetResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /kyc_links/{kycLinkID}:
    parameters:
    - $ref: '#/components/parameters/KycLinkIDParameter'
    get:
      summary: Check the status of a KYC link
      description: Retrieve the status of a KYC request from the passed in KYC link id
      tags:
      - KYC Links
      responses:
        '200':
          description: Successful KYC link status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndividualKycLinkResponse'
              examples:
                ApprovedKYCLinkGetResponse:
                  summary: KYC link status for an approved customer
                  $ref: '#/components/examples/ApprovedKycLinkGetResponse'
                RejectedKYCLinkGetResponse:
                  summary: KYC link status for a rejected customer
                  $ref: '#/components/examples/RejectedKycLinkGetResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
components:
  schemas:
    EndorsementType:
      description: 'The type of endorsement. Note: `pix_onramp` (BRL deposits via PIX) and `pix_offramp` (BRL withdrawals via PIX) can be requested individually for granular access. Requesting `pix` grants both directional endorsements. `pix_onramp` is not supported for non-BR individuals; if requested (or requested via `pix`) it will remain in an `endorsement_not_available_in_customers_region` state and no action is required.

        '
      type: string
      enum:
      - base
      - cards
      - cop
      - faster_payments
      - pix
      - pix_onramp
      - pix_offramp
      - sepa
      - spei
    Id:
      description: A UUID that uniquely identifies a resource
      type: string
      pattern: '[a-z0-9]*'
      minLength: 1
      maxLength: 42
    RejectionReason:
      description: Reason why the kyc_status was rejected
      properties:
        developer_reason:
          type: string
          description: Developer information for why a customer was rejected. Not to be shared with the customer.
        reason:
          type: string
          description: Reason for why a customer was rejected. To be shared with the customer.
        created_at:
          deprecated: true
          type:
          - string
          - 'null'
          description: Time of creation of the rejection reason
    CreateKycLinks:
      required:
      - email
      - type
      properties:
        full_name:
          description: Full name of the customer, for a business, this would be the business entity's legal name
          type: string
          minLength: 1
        email:
          description: Email of the customer
          type: string
          minLength: 1
        type:
          description: Type of the customer (individual vs. business)
          type: string
          minLength: 1
          enum:
          - individual
          - business
        endorsements:
          description: 'List of endorsements to request for the generated KYC link.

            For example, `sepa` endorsement could be requested to allow an `individual` customer to submit `proof-of-address` documents in the KYC flow.'
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/EndorsementType'
        redirect_uri:
          description: The location where the customer should be redirected after completing the KYC flow. Must be in the form of http:// or https://.
          type: string
        transliterated_first_name:
          type: string
          description: 'Required when the `full_name` of an individual includes any non Latin-1 characters. Acceptable characters - Latin-1 Unicode Character Range: À-ÖØ-ßà-öø-ÿ; Standard Unicode Character Range:  -~'
          minLength: 1
          maxLength: 256
        transliterated_middle_name:
          type: string
          description: 'Required when the `full_name` of an individual includes any non Latin-1 characters and the individual has a middle name. Acceptable characters - Latin-1 Unicode Character Range: À-ÖØ-ßà-öø-ÿ; Standard Unicode Character Range:  -~'
          minLength: 1
          maxLength: 256
        transliterated_last_name:
          type: string
          description: 'Required when the `full_name` of an individual includes any non Latin-1 characters. Acceptable characters - Latin-1 Unicode Character Range: À-ÖØ-ßà-öø-ÿ; Standard Unicode Character Range:  -~'
          minLength: 1
          maxLength: 256
        transliterated_business_legal_name:
          type: string
          description: 'Required if the `full_name` of a business includes any non Latin-1 characters. Acceptable characters - Latin-1 Unicode Character Range: À-ÖØ-ßà-öø-ÿ; Standard Unicode Character Range:  -~'
          minLength: 1
          maxLength: 1024
    IndividualKycLinkResponse:
      properties:
        id:
          type: string
          description: ID of the KYC link
        type:
          type: string
          description: Type of the KYC link
          enum:
          - individual
          - business
        customer_id:
          type: string
          description: ID of the customer.
        full_name:
          type: string
          description: Full name of the customer, for a business, this would be the business entity's legal name
        email:
          type: string
          description: Email of the customer
        kyc_link:
          type: string
          description: Link to the KYC flow
        kyc_status:
          type: string
          $ref: '#/components/schemas/KycStatus'
        rejection_reasons:
          deprecated: true
          readOnly: true
          description: Reasons why a customer KYC was rejected
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/RejectionReason'
        tos_link:
          type: string
          description: Link to the TOS flow
        tos_status:
          type: string
          $ref: '#/components/schemas/TosStatus'
        created_at:
          type: string
          description: Time of creation of the KYC link
          format: date-time
    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
    KycStatus:
      type: string
      description: Status of the KYC flow.
      enum:
      - not_started
      - incomplete
      - awaiting_questionnaire
      - awaiting_ubo
      - under_review
      - approved
      - rejected
      - paused
      - offboarded
    TosStatus:
      type: string
      description: Status of the TOS flow
      enum:
      - pending
      - approved
  examples:
    ApprovedKycLinkGetResponse:
      summary: Approved KYC link
      value:
        id: kyc_link_123
        full_name: John Doe
        email: johndoe@johndoe.com
        type: individual
        kyc_link: www.kyclink.com/blah
        tos_link: www.toslink.com/blah
        kyc_status: approved
        rejection_reasons: []
        tos_status: approved
        customer_id: cust_123
    KycLinksGetResponse:
      summary: A list of KYC links
      value:
        count: 2
        data:
        - id: kyc_link_123
          full_name: John Doe
          email: johndoe@johndoe.com
          type: individual
          kyc_link: www.kyclink.com/blah
          tos_link: www.toslink.com/blah
          kyc_status: approved
          rejection_reasons: []
          tos_status: approved
          customer_id: cust_123
        - id: kyc_link_456
          full_name: Jane Doe
          email: janedoe@janedoe.com
          type: individual
          kyc_link: www.kyclink.com/blah
          tos_link: www.toslink.com/blah
          kyc_status: rejected
          rejection_reasons:
          - developer_reason: Missing required ID details.
            reason: Cannot validate ID -- upload a clear photo of the full ID
            created_at: '2020-01-02T00:00:00.000Z'
          - developer_reason: Blurry face portrait.
            reason: Cannot validate ID -- upload a clear photo of the full ID
            created_at: '2020-01-02T00:00:00.000Z'
          tos_status: approved
          customer_id: cust_456
    RejectedKycLinkGetResponse:
      summary: Rejected KYC link
      value:
        id: kyc_link_123
        full_name: John Doe
        email: johndoe@johndoe.com
        type: individual
        kyc_link: www.kyclink.com/blah
        tos_link: www.toslink.com/blah
        kyc_status: rejected
        rejection_reasons:
        - developer_reason: Missing required ID details.
          reason: Cannot validate ID -- upload a clear photo of the full ID
          created_at: '2020-01-02T00:00:00.000Z'
        - developer_reason: Blurry face portrait.
          reason: Cannot validate ID -- upload a clear photo of the full ID
          created_at: '2020-01-02T00:00:00.000Z'
        tos_status: approved
        customer_id: cust_123
    SuccessfulKycLinkCreateResponse:
      summary: Successful KYC link creation
      value:
        id: kyc_link_123
        full_name: John Doe
        email: johndoe@johndoe.com
        type: individual
        kyc_link: www.kyclink.com/blah
        tos_link: www.toslink.com/blah
        kyc_status: not_started
        tos_status: pending
        customer_id: cust_123
  parameters:
    CustomerEndingBeforeParameter:
      in: query
      name: ending_before
      schema:
        type: string
      description: This is a customer id. If this is specified, the previous page that ends with a customer right BEFORE the specified customer id on the customer timeline, which is always ordered from the newest to the oldest by creation time, will be returned. This also implies that customers newer than the specified customer id will be returned (shouldn't be set if starting_after is set)
    KycLinksEmailParameter:
      name: email
      in: query
      required: false
      schema:
        type: string
      description: If included, filters to KYC links for the customer with the given email
    IdempotencyKeyParameter:
      in: header
      name: Idempotency-Key
      required: true
      schema:
        type: string
    CustomerStartingAfterParameter:
      in: query
      name: starting_after
      schema:
        type: string
      description: This is a customer id. If this is specified, the next page that starts with a customer right AFTER the specified customer id on the customer timeline, which is always ordered from the newest to the oldest by creation time, will be returned. This also implies that customers older than the specified customer id will be returned (shouldn't be set if ending_before is set)
    KycLinksCustomerIDParameter:
      name: customer_id
      in: query
      required: false
      schema:
        type: string
      description: If included, filters to KYC links for the customer with the given id
    LimitParameter:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
      description: The number of items to return (min 1, default 10, max 100)
    KycLinkIDParameter:
      name: kycLinkID
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Id'
  responses:
    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
    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
    BadRequestError:
      description: Request containing missing or invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            BadCustomerRequestErrorExample:
              summary: Bad customer request
              value:
                code: bad_customer_request
                message: fields missing from customer body.
                name: first_name,ssn
  securitySchemes:
    ApiKey:
      type: apiKey
      name: Api-Key
      in: header