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

# Create Customer via Link

> Create a customer via the hosted onboarding link flow. Returns a KYC link and its expiry.

Use this endpoint to create a customer and generate a hosted KYC link in a single request. Instead of creating the customer first and then requesting a link separately, you provide the customer's type, email, phone, and address here, and the response returns the new customer's ID along with a time-limited hosted verification URL. Redirect the customer to this URL to complete their identity checks with the verification provider.

<Warning>
  Customers created via this onboarding link flow can only be managed with the onboarding link endpoints — they are not compatible with the direct API onboarding flows. Likewise, customers onboarded through the other API flows cannot be used with the onboarding link endpoints.
</Warning>

<Info>
  The returned URL expires at the time indicated by `expiresAt` — by default, 4 weeks (28 days) after creation. This default may change without notice, so always rely on `expiresAt` rather than assuming a fixed duration. If the link expires before the customer completes verification, generate a fresh one with [Regenerate KYC Link](/api-reference/customer/kyc) using the `customerId` from this response.
</Info>


## OpenAPI

````yaml openapi/spherepay.yaml POST /v2/customer/kyc-link
openapi: 3.0.0
info:
  title: ''
  description: ''
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.spherepay.co
    description: Production
security:
  - bearer: []
tags: []
paths:
  /v2/customer/kyc-link:
    post:
      summary: Create Customer via Link
      description: >-
        Create a customer via the hosted onboarding link flow. Returns a KYC
        link and its expiry.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerKycLinkDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateKycUrlResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
              examples:
                Bad Request:
                  summary: Bad Request
                  value:
                    status: 400
                    detail: Invalid request parameters
                    code: address/invalid
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
              examples:
                Not Found:
                  summary: Not Found
                  value:
                    status: 404
                    detail: Resource not found
                    code: resource/not-found
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
        '422':
          description: Unprocessable Entity - Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
              examples:
                Validation Error:
                  summary: Validation Error
                  value:
                    status: 422
                    detail: Validation failed
                    code: validation/failed
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    errors:
                      - detail: Invalid email format
                        pointer: /email
                      - detail: Name is required
                        pointer: /name
components:
  schemas:
    CreateCustomerKycLinkDto:
      type: object
      properties:
        type:
          description: The type of customer to onboard.
          example: individual
          type: string
          enum:
            - individual
            - business
        email:
          description: The customer email address.
          example: jane.smith@example.com
          type: string
          format: email
          maxLength: 254
        phone:
          description: The customer phone number in E.164 format.
          example: '+14155550123'
          type: string
          pattern: ^\+(?:[0-9]){6,14}[0-9]$
        address:
          description: >-
            The customer's address. For individual customers this is the
            residential address; for business customers this is the registered
            business address.
          type: object
          properties:
            line1:
              description: The first line of the street address
              example: 233 South Wacker Drive
              type: string
              minLength: 1
              maxLength: 255
            line2:
              description: The second line of the street address (apartment, suite, etc.)
              example: Suite 4700
              type: string
              maxLength: 255
            city:
              description: The city name
              example: Chicago
              type: string
              minLength: 1
              maxLength: 255
            state:
              description: >-
                The state or province code (ISO3166-2 subdivision code).
                Required for countries that have states/provinces. See State
                Codes.
              example: IL
              type: string
            postalCode:
              description: >-
                The postal or ZIP code. Required for countries that use postal
                codes
              example: '60606'
              type: string
            country:
              description: >-
                The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See
                [Country Codes](/concepts/reference/supported-countries).
              example: USA
              type: string
          required:
            - line1
            - city
            - country
      required:
        - type
        - email
        - phone
        - address
    GenerateKycUrlResponseDto:
      type: object
      properties:
        customerId:
          description: The ID of the customer the KYC link belongs to
          example: customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7
          type: string
        url:
          description: Hosted KYC URL
          example: https://in.sumsub.com/websdk/p/sbx_uq30ag1ov7oHZhmx
          type: string
        expiresAt:
          description: >-
            ISO 8601 formatted date and time of the KYC URL expiration. By
            default, links expire 4 weeks (28 days) after creation, but this
            default may change without notice — always rely on this field rather
            than assuming a fixed duration.
          example: '2026-03-09T20:46:31.305Z'
          type: string
      required:
        - customerId
        - url
        - expiresAt
    ProblemDetailsDto:
      type: object
      properties:
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              detail:
                type: string
              pointer:
                type: string
              parameter:
                type: string
              header:
                type: string
            required:
              - detail
        correlationId:
          type: string
      required:
        - status
        - detail
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````