> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dollarpe.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate KYC Link

> Generates a hosted KYC link for a customer. US customers complete KYC only through this link.

## Error Codes and Messages

| API Status Code | Response | Reason |
| - | - | - |
| 400 | Customer not found or access denied | Customer not found |
| 400 | Customer not found or access denied | Customer does not belong to the organization |
| 400 | Bad Request | Request validation failed (e.g. invalid `customer_id` format) |
| 400 | Bad Request | Customer is not eligible to generate a KYC link in their current state |
| 500 | Internal Server Error | Internal Server Error |


## OpenAPI

````yaml POST /kyc/generate-link
openapi: 3.1.0
info:
  title: Zapyd API
  description: API for Zapyd - Customer, Payout, and Webhook services
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://sandbox.zapyd.com/pos/api/v1
    description: Payout API Base URL
    variables:
      base_url:
        default: https://sandbox.zapyd.com
  - url: https://sandbox.zapyd.com/cms/api/v1
    description: Customer API Base URL
    variables:
      base_url:
        default: https://sandbox.zapyd.com
security:
  - ApiKeyAuth: []
    TimestampAuth: []
    SignatureAuth: []
tags:
  - name: Customer
    description: Customer related operations
    x-displayName: Customer
    x-traitTag: true
  - name: Payout
    description: Payout related operations
  - name: Webhooks
    description: Webhook related operations
  - name: Widget
    description: Hosted buy/sell widget session initialization
paths:
  /kyc/generate-link:
    post:
      tags:
        - KYC
      description: >-
        Creates a one-time URL for Zapyd's hosted KYC flow. Send the customer to
        data.url. Fails if the customer is already VERIFIED or a KYC is in
        review.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customer_id
              properties:
                customer_id:
                  type: string
                  format: uuid
                  example: 075986f3-282b-4555-bfcd-fad973e32596
                  description: Zapyd customer ID (UUID) returned by Create Customer.
                redirect_url:
                  type: string
                  format: uri
                  example: https://yourapp.com/kyc/return
                  description: >-
                    Optional. Where to send the customer after the KYC flow.
                    Defaults to the redirect URL set for your organization.
      responses:
        '200':
          description: Hosted KYC URL generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        format: uri
                        example: >-
                          https://app.zapyd.com/kyc?kyc_id=977c8923-3818-4880-bfbf-65436635ea91
                      is_mocked:
                        type: boolean
                        description: Returned as true only when the link is a sandbox mock.
                        example: true
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Internal Server Error
                  data:
                    type: 'null'
                  err_code:
                    type: string
                    example: SYS_INTERNAL_ERROR
                  errors:
                    type: string
                    example: Unexpected error occurred. Please try again later.
      servers:
        - url: https://sandbox.zapyd.com/cms/api/v1
          description: KYC API Base URL
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API Key for authentication
    TimestampAuth:
      type: apiKey
      in: header
      name: X-TIMESTAMP
      description: Current timestamp in seconds since epoch
    SignatureAuth:
      type: apiKey
      in: header
      name: X-SIGNATURE
      description: HMAC SHA256 signature of the request encoded in Base64

````