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

# Create a KYC profile

> Creates a KYC profile and starts the identity-verification flow.

Use a stable `external_reference` from your system and persist the returned
`profile_id`. The external reference acts as the idempotency key for profile creation:
retrying with the same external reference and email returns the existing profile ID
without restarting onboarding. Reusing the external reference with a different email
returns a conflict.

Next, collect the current terms, retrieve the profile's verification checks,
and collect source-of-funds answers when required.



## OpenAPI

````yaml https://core.sandbox.gnosispay.in/partner-api/openapi.json post /v1/kyc/profiles
openapi: 3.1.0
info:
  title: Gnosis Pay Partner API
  version: 1.0.0
  description: >-
    Server-to-server API for onboarding users, creating accounts and cards,
    moving

    funds, and managing the card lifecycle. Call this API only from a trusted

    backend. Every request requires a partner access token, and every resource
    is

    scoped to the authenticated partner.
servers:
  - url: https://core.prod.gnosispay.com/partner-api
    description: Production
    variables: {}
  - url: https://core.sandbox.gnosispay.in/core
    description: Sandbox
    variables: {}
security:
  - BearerAuth: []
tags:
  - name: Accounts
  - name: Cards
  - name: Card transactions
  - name: KYC
  - name: Deposits
  - name: Withdrawals
  - name: PCI
  - name: 3DS
  - name: Webhooks
paths:
  /v1/kyc/profiles:
    post:
      tags:
        - KYC
      summary: Create a KYC profile
      description: >-
        Creates a KYC profile and starts the identity-verification flow.


        Use a stable `external_reference` from your system and persist the
        returned

        `profile_id`. The external reference acts as the idempotency key for
        profile creation:

        retrying with the same external reference and email returns the existing
        profile ID

        without restarting onboarding. Reusing the external reference with a
        different email

        returns a conflict.


        Next, collect the current terms, retrieve the profile's verification
        checks,

        and collect source-of-funds answers when required.
      operationId: kyc_profiles.create.v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProfileParams'
        description: Identity and optional reusable-verification data for the new profile.
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProfileResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreateProfileParams:
      type: object
      required:
        - email
      properties:
        external_reference:
          $ref: '#/components/schemas/ExternalReference'
          description: >-
            Stable identifier from your system. Used for reconciliation and
            idempotent creation retries.
        email:
          type: string
          format: email
          description: Email address of the person being onboarded.
        reuse_kyc:
          $ref: '#/components/schemas/ProfileKYC'
          description: >-
            Optional data for reusing a supported identity verification. This
            feature

            must be enabled for the partner. When omitted, the user completes
            the

            standard identity-verification flow.
        safe_owner_address:
          type: string
          description: >-
            Optional Ethereum address that will own the user's funding wallet.
            Must be

            a valid `0x`-prefixed, 40-hex-character address controlled by the
            user.
    CreateProfileResponse:
      type: object
      required:
        - profile_id
      properties:
        profile_id:
          $ref: '#/components/schemas/uuid'
          description: >-
            ID of the created profile, or the existing profile when the request
            is retried.
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: HTTP status code.
        message:
          type: string
          description: Generic human-readable text for the status code. Do not parse it.
        reason:
          type: string
          description: >-
            Stable machine-readable code identifying the specific cause, present
            only

            for errors that expose one (e.g. `CREATE_CARD_LIMIT_EXCEEDED`).
            Branch on

            this rather than on `message`.
    ExternalReference:
      type: string
      minLength: 1
      maxLength: 128
      pattern: ^[A-Za-z0-9_-]+$
      description: >-
        Your identifier for reconciliation. 1 to 128 letters, digits,
        underscores or hyphens.
    ProfileKYC:
      type: object
      oneOf:
        - $ref: '#/components/schemas/ProfileKYCSumsub'
      discriminator:
        propertyName: provider
        mapping:
          sumsub: '#/components/schemas/ProfileKYCSumsub'
      description: >-
        Data for reusing a supported identity verification. `provider` selects
        the

        matching `data` shape. Unsupported providers or mismatched data are
        rejected.
    uuid:
      type: string
      format: uuid
    ProfileKYCSumsub:
      type: object
      required:
        - provider
        - data
      properties:
        provider:
          type: string
          enum:
            - sumsub
        data:
          $ref: '#/components/schemas/SumsubProfileKYC'
    SumsubProfileKYC:
      type: object
      required:
        - share_token
      properties:
        share_token:
          type: string
          minLength: 1
          description: Share token issued for the existing identity verification.
      description: Data required to reuse an existing identity verification.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.