> ## 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.

# Criar Cliente via Link

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

Use este endpoint para criar um cliente e gerar um link KYC hospedado em uma única solicitação. Em vez de criar o cliente primeiro e depois solicitar um link separadamente, você fornece aqui o tipo, email, telefone e endereço do cliente, e a resposta retorna o ID do novo cliente junto com uma URL de verificação hospedada com tempo limitado. Redirecione o cliente para esta URL para concluir as verificações de identidade com o provedor de verificação.

<Warning>
  Clientes criados através deste fluxo de link de onboarding só podem ser gerenciados com os endpoints de links de onboarding — eles não são compatíveis com os fluxos diretos de onboarding da API. Da mesma forma, clientes integrados através dos outros fluxos da API não podem ser usados com os endpoints de links de onboarding.
</Warning>

<Info>
  A URL retornada expira no momento indicado por `expiresAt` — por padrão, 4 semanas (28 dias) após a criação. Este padrão pode mudar sem aviso prévio, então confie sempre em `expiresAt` em vez de assumir uma duração fixa. Se o link expirar antes de o cliente concluir a verificação, gere um novo com [Regenerar Link KYC](/pt-BR/api-reference/customer/kyc) usando o `customerId` desta resposta.
</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

````