Checkout.com Applicants API

openapi: 3.2.0
info:
  title: Checkout.com API Reference Applicants API
  description: '## Get started

    Checkout.com provides a collection of APIs that enable you to integrate with our various products and services.

    Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using any HTTP or REST library.

    Sign up for a test account to gain access to the sandbox environment, where you can test API calls without affecting live data.

    For more information, see:


    - API endpoints

    - API rate limits

    - API changes

    - Idempotency

    - Private connections


    ## Base URLs

    The base URLs you must use for your API calls to the sandbox and production environments are unique to you.


    - `https://{prefix}.api.sandbox.checkout.com/{path}`

    - `https://{prefix}.api.checkout.com/{path}`

    - `https://{prefix}.access.sandbox.checkout.com/{path}`

    - `https://{prefix}.access.checkout.com/{path}`


    The unique API endpoint host names resolve to Checkout.com''s IP addresses. Do not allowlist these IP addresses.

    The `{prefix}` value in each base URL is a string containing the first eight characters of each of your environments'' unique `client_id`, excluding the `cli_` prefix.

    To find your unique base URL:

    1. Sign in to the Dashboard environment you want to retrieve the base URL for:


    - Sandbox

    - Production


    2. Go to _Developers_ > _Overview_.

    Your unique base URL is displayed on the _Developer overview_ page. For example, `https://vkuhvk4v.api.checkout.com`.


    3. Alternatively, go to _Settings_ > _Account details_.

    Your unique base URL is displayed under _Connection settings_.


    If you are unsure of your client ID or base URL for either environment, contact your account manager or request support.

    For more information, see API endpoints.

    ## Authentication

    When you sign up for an account, you can authenticate with either Access keys (OAuth 2.0), or Secret API keys.

    Unless explicitly stated, all endpoints require authentication using either your Access or Secret API Keys. Public keys should only be used in JavaScript or native applications.


    - **Client-side authentication**. Use your public key for client-side authentication. It only has access to a limited set of our APIs – mostly those called as part of your payment environment.


    - **Server-to-server authentication**. Use your secret key or OAuth for server-to-server communication. Support for API keys depends on the endpoint.


    Never share your OAuth credentials, API keys, or access tokens. Keep them guarded and secure.'
  termsOfService: https://www.checkout.com/legal/terms-and-policies
  contact:
    name: Checkout.com Support
    url: https://dashboard.checkout.com/support
  version: v1.0.0
servers:
- url: https://{prefix}.api.sandbox.checkout.com
  description: Sandbox environment
  variables:
    prefix:
      default: '{prefix}'
      description: Your unique <a href="https://www.checkout.com/docs/developer-resources/api/api-endpoints" target="_blank">base URL</a>. There is no default value.
- url: https://{prefix}.api.checkout.com
  description: Production environment
  variables:
    prefix:
      default: '{prefix}'
      description: Your unique <a href="https://www.checkout.com/docs/developer-resources/api/api-endpoints" target="_blank">base URL</a>. There is no default value.
tags:
- name: Applicants
paths:
  /applicants:
    servers:
    - url: https://identity-verification.checkout.com
      description: Production environment
    - url: https://identity-verification.sandbox.checkout.com
      description: Sandbox environment
    post:
      tags:
      - Applicants
      summary: Create an applicant
      description: Create a profile for an Identities applicant.
      operationId: create_applicant
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdvApplicant'
            examples:
              All possible data:
                $ref: '#/components/examples/idv_applicant_creation_request_body'
      responses:
        '201':
          description: Applicant created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdvApplicant'
              examples:
                Always replies:
                  $ref: '#/components/examples/idv_applicant_response_body'
          links:
            RetrieveApplicantById:
              operationId: retrieve_applicant
              parameters:
                applicant_id: $response.body#/id
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Invalid phone number:
                  value:
                    error_type: request_invalid
                    error_codes:
                    - phone_number__invalid_format
      security:
      - OAuth:
        - identity-verification
      - ApiSecretKey: []
  /applicants/{applicant_id}:
    servers:
    - url: https://identity-verification.checkout.com
      description: Production environment
    - url: https://identity-verification.sandbox.checkout.com
      description: Sandbox environment
    get:
      tags:
      - Applicants
      summary: Get an applicant
      description: Get the details of an applicant profile.
      operationId: retrieve_applicant
      parameters:
      - name: applicant_id
        in: path
        description: The applicant profile's unique identifier.
        required: true
        schema:
          $ref: '#/components/schemas/ApplicantId'
      responses:
        '200':
          description: Applicant profile retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdvApplicant'
              examples:
                Always replies:
                  $ref: '#/components/examples/idv_applicant_response_body'
        '404':
          description: Not Found
      security:
      - OAuth:
        - identity-verification
      - ApiSecretKey: []
    patch:
      tags:
      - Applicants
      summary: Update an applicant
      description: Update the details of an applicant profile.
      operationId: update_applicant
      parameters:
      - name: applicant_id
        in: path
        description: The applicant profile's unique identifier.
        required: true
        schema:
          $ref: '#/components/schemas/ApplicantId'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/IdvApplicant'
            examples:
              All possible data:
                $ref: '#/components/examples/idv_applicant_update_request_body'
      responses:
        '200':
          description: Applicant profile updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdvApplicant'
              examples:
                Always replies:
                  $ref: '#/components/examples/idv_applicant_response_body'
        '400':
          description: Bad Request
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      security:
      - OAuth:
        - identity-verification
      - ApiSecretKey: []
  /applicants/{applicant_id}/anonymize:
    servers:
    - url: https://identity-verification.checkout.com
      description: Production environment
    - url: https://identity-verification.sandbox.checkout.com
      description: Sandbox environment
    post:
      tags:
      - Applicants
      summary: Anonymize an applicant
      description: Remove the personal data in an applicant profile.
      operationId: anonymize_applicant
      parameters:
      - name: applicant_id
        in: path
        description: The applicant profile's unique identifier.
        required: true
        schema:
          $ref: '#/components/schemas/ApplicantId'
      responses:
        '200':
          description: Personal data removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdvApplicant'
              examples:
                Always replies:
                  $ref: '#/components/examples/idv_applicant_response_body_anonymized'
        '400':
          description: Bad Request
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      security:
      - OAuth:
        - identity-verification
      - ApiSecretKey: []
components:
  schemas:
    ApplicantId:
      pattern: ^aplt_\w+$
      type: string
      description: The applicant's unique identifier.
      readOnly: true
      example: aplt_tkoi5db4hryu5cei5vwoabr7we
    IdvApplicant:
      required:
      - id
      allOf:
      - $ref: '#/components/schemas/DatedObject'
      - $ref: '#/components/schemas/IdvBaseApplicant'
      - $ref: '#/components/schemas/IdvApplicantLinks'
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/ApplicantId'
          readOnly: true
    IdvBaseApplicant:
      type: object
      properties:
        external_applicant_id:
          pattern: ^ext_\w+$
          type: string
          description: Your reference for the applicant.
          example: ext_osdfdfdb4hryu5cei5vwoabrk5k
        email:
          type: string
          description: The applicant's email address.
          format: email
          example: hannah.bret@example.com
        external_applicant_name:
          maxLength: 255
          type: string
          description: The applicant's full name.
          example: Hannah Bret
    IdvHalLink:
      required:
      - href
      type: object
      properties:
        href:
          type: string
          format: uri
      description: The URL to the applicant profile resource.
    IdvApplicantLinks:
      required:
      - _links
      type: object
      properties:
        _links:
          allOf:
          - $ref: '#/components/schemas/IdvSelfLink'
          readOnly: true
    IdvSelfLink:
      required:
      - self
      type: object
      properties:
        self:
          allOf:
          - $ref: '#/components/schemas/IdvHalLink'
          description: The URL to the resource.
      description: The details of links related to the resource.
      readOnly: true
    DatedObject:
      required:
      - created_on
      - modified_on
      type: object
      properties:
        created_on:
          type: string
          description: The date and time when the resource was created, in UTC. <br/>Format – `yyyy-mm-ddThh:mm:ss.sss`
          format: date-time
          readOnly: true
          example: '2025-07-21T17:32:28.0000000+00:00'
        modified_on:
          type: string
          description: The date and time when the resource was modified, in UTC. <br/>Format – `yyyy-mm-ddThh:mm:ss.sss`
          format: date-time
          readOnly: true
          example: '2025-07-21T17:40:32.0000000+00:00'
  examples:
    idv_applicant_response_body_anonymized:
      value:
        id: aplt_tkoi5db4hryu5cei5vwoabr7we
        created_on: '2025-07-21T17:32:28Z'
        modified_on: '2025-07-21T17:40:32Z'
        external_applicant_id: ext_osdfdfdb4hryu5cei5vwoabrk5k
        _links:
          self:
            href: https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we
    idv_applicant_creation_request_body:
      value:
        external_applicant_id: ext_osdfdfdb4hryu5cei5vwoabrk5k
        email: hannah.bret@example.com
        external_applicant_name: Hannah Bret
    idv_applicant_response_body:
      value:
        id: aplt_tkoi5db4hryu5cei5vwoabr7we
        created_on: '2025-07-21T17:32:28Z'
        modified_on: '2025-07-21T17:40:32Z'
        external_applicant_id: ext_osdfdfdb4hryu5cei5vwoabrk5k
        email: hannah.bret@example.com
        external_applicant_name: Hannah Bret
        _links:
          self:
            href: https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we
    idv_applicant_update_request_body:
      value:
        email: hannah.bret@example.com
        external_applicant_name: Hannah Bret
  securitySchemes:
    ApiPublicKey:
      type: apiKey
      description: "Public keys are for client-side authentication and supported only in JavaScript or native applications.\n  \n#### Format\n\n- Sandbox – `pk_sbox_xxxxxxxxxxxxxxxxxxxxxxxxxx`\n\n- Production – `pk_xxxxxxxxxxxxxxxxxxxxxxxxxx`\n\nWhen specifying your public key, use the format `Bearer {{PublicApiKey}}`.\n"
      name: Authorization
      in: header
      x-cko-type: publicKey
    ApiSecretKey:
      type: apiKey
      description: 'You can pass your secret API key in the `Authorization` header of your requests for supported endpoints.


        #### Format


        - Sandbox – `sk_sbox_xxxxxxxxxxxxxxxxxxxxxxxxxx`


        - Production – `sk_xxxxxxxxxxxxxxxxxxxxxxxxxx`


        When specifying your secret key, use the format `Bearer {{SecretApiKey}}`.


        ```

        curl --location --request POST ''https://{prefix}.api.checkout.com/{{path}}'' \

        --header ''Content-Type: application/json'' \

        --header ''Accept: application/json'' \

        --header ''Authorization: Bearer {{SecretApiKey}}'' \

        --data-raw ''{

        "amount": 10000,

        "currency": "USD",

        "reference": "Visa-USD-Test",

        ...

        }''

        ```

        '
      name: Authorization
      in: header
      x-cko-type: secretKey
    OAuth:
      type: oauth2
      description: "Your OAuth credentials include an access key ID and an access key secret. They correspond to an OAuth 2.0 client ID and a client secret respectively. \n\nTo exchange these credentials for an access token, call the [Request an access token](/tag/access/POST/connect/token) endpoint. Authenticate using basic authentication, with your access key ID as the username and your access key secret as the password.\n\n| Environment   |      Authorization server                            |\n|---------------|------------------------------------------------------|\n| Sandbox       |  https://{prefix}.access.sandbox.checkout.com/connect/token   |\n| Production    |  https://{prefix}.access.checkout.com/connect/token           |\n\n```\ncurl --location 'https://{prefix}.access.checkout.com/connect/token' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--data-urlencode 'grant_type=client_credentials' \\\n--data-urlencode 'client_id=ack_...' \\\n--data-urlencode 'client_secret=...' \n```\n\nThe token server returns a Bearer `access_token` in JSON Web Token (JWT) format. Use this token in the `Authorization` header of your API requests.\n\n```\ncurl --location --request POST 'https://{prefix}.api.checkout.com/{{path}}' \\\n--header 'Content-Type: application/json' \\\n--header 'Accept: application/json' \\\n--header 'Authorization: Bearer {{AccessToken}}' \\\n--data-raw '{\n  \"amount\": 10000,\n  \"currency\": \"USD\",\n  \"reference\": \"Visa-USD-Test\",\n  ...\n}'\n```\n\nThe `expires_in` field in the response indicates the validity period of your access token in seconds. When your token expires, you must request a new one.\n\nDepending on the Environment against which you're making your requests against you'll need to request the token from a different Authorization Server.\n\n| Environment   |      Authorization Server                            |\n|---------------|------------------------------------------------------|\n| Sandbox       |  https://{prefix}.access.sandbox.checkout.com/connect/token   |\n| Production    |  https://{prefix}.access.checkout.com/connect/token           |\n\nYour base URL `{prefix}` is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints).\n"
      flows:
        clientCredentials:
          tokenUrl: string
          scopes:
            vault: Access to all Vault resources
            vault:apme-enrollment: Manage Apple Pay Domain Enrollment
            vault:customers: Manage customers
            vault:card-metadata: Read card metadata
            vault:instruments: Create instruments
            vault:network-tokens: Manage network tokens
            vault:tokenization: Tokenize payment instruments
            vault:real-time-account-updater: Access to real-time account updater
            gateway: Access to all Gateway resources
            gateway:payment: Request payments
            gateway:payment-details: Get payment details
            gateway:payment-authorizations: Increment authorizations
            gateway:payment-voids: Void payments
            gateway:payment-captures: Capture payments
            gateway:payment-contexts: Manage payment contexts
            gateway:payment-cancellations: Manage payment cancellations
            gateway:payment-refunds: Refund payments
            fx: Foreign exchange services
            payouts:bank-details: Get bank details
            sessions:app: App-based authentication
            sessions:browser: Browser-based authentication
            disputes: Access to all Disputes resources
            disputes:view: View disputes
            disputes:provide-evidence: Provide dispute evidence
            disputes:accept: Accept disputes
            disputes:scheme-files: Read dispute scheme files
            accounts: Manage sub-entities
            flow: Access to all Flow resources
            flow:workflows: Manage workflows
            flow:events: Retrieve events
            flow:reflow: Manage workflows
            files: Access to all Files resources
            files:retrieve: Retrieve files
            files:upload: Upload files
            files:download: Download files
            forward: Access to Forward api
            forward:secrets: Manage secrets in Forward api
            balances: Access to all Balances resources
            balances:view: View balances
            balances:top-up-instructions: Get top-up instructions
            transfers: Access to all Transfers resources
            transfers:view: View transfers
            transfers:create: Create transfers
            middleware: Access to all Middleware resources
            middleware:merchants-secret: Allows merchant identity and Middleware token exchange from a secure execution environment
            middleware:merchants-public: Allows merchant identity and Middleware token exchange from an insecure execution environment
            payment-sessions: Access to all Payment Sessions resources
            payments:search: Search payments
            reports: Access to all Reports resources
            reports:view: View reports
            financial-actions: Access to all Financial actions resources
            financial-actions:view: View financial actions
            card-management: Access to all Card management resources
            issuing:card-management-read: Gives access to card management endpoints with GET operations
            issuing:card-management-write: Gives access to card management endpoints with POST/ PUT / DELETE operations
            issuing:controls-read: Gives access to card control endpoints with GET operations
            issuing:controls-write: Gives access to card control endpoints with POST/ PUT / DELETE operations
            transactions: Access to all transactions resources
            issuing:transactions-read: Gives access to get and search transactions
            issuing:transactions-write: Gives access to simulate transactions for testing purposes
            issuing-disputes: Access to Issuing disputes resources
            issuing:disputes-read: Gives access to get disputes
            issuing:disputes-write: Gives access to create and submit Issuing disputes
            identity-verification: Access to all Identities endpoints
            Payment Context: Read payment context
            agentic:inventory: Manage agentic commerce inventory and reservations
    SessionSecret:
      type: apiKey
      description: 'A base64 encoded value prefixed with `sek_` that gives access to client-side operations for a single authentication within the Sessions API. This value is returned as the `session_secret` when requesting a session.

        '
      name: Authorization
      in: header
x-tagGroups:
- name: Set up
  tags:
  - Access
- name: Handle payments and payouts
  tags:
  - Payments
  - Flow
  - Payment Setups
  - Payment Links
  - Hosted Payments Page
  - Forex
  - Apple Pay
  - Bacs Direct Debit
  - Google Pay
  - Transfers
  - Balances
- name: Payment Context
  tags:
  - Payment Context
- name: Payment Methods
  tags:
  - Payment Methods
- name: Store and forward payment credentials
  tags:
  - Tokens
  - Instruments
  - Customers
  - Forward
- name: Authentication
  tags:
  - Standalone
- name: Risk management
  tags:
  - Disputes
- name: Notifications
  tags:
  - Workflows
- name: Platforms
  tags:
  - Platforms
  - Business details
  - Payment instruments
  - Payout schedules
  - Reserve rules
  - Onboarding Simulator
- name: Card issuing
  tags:
  - Cardholders
  - Cards
  - Controls
  - Control profiles
  - Control groups
  - Cardholder access tokens
  - Transactions
  - Issuing disputes
  - Card testing
- name: Identities
  tags:
  - Applicants
  - Identity Verification
  - AML Screening
  - Face Authentication
  - ID Document Verification
  - Address Document Verification
- name: Reporting
  tags:
  - Reports
  - Financial actions
- name: Metadata
  tags:
  - Card metadata
- name: Network Tokens
  tags:
  - Network Tokens
- name: Standalone Account Updater
  tags:
  - Standalone Account Updater
- name: Compliance requests
  tags:
  - Compliance requests
- name: Agentic Commerce
  tags:
  - Agentic Commerce Protocol
  - Inventory