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

# Get KYC Widget URL

> Generates a hosted widget URL that you redirect your user to (or embed as an iframe) to complete KYC or share an existing verified identity.

**Flows**
- `kyc_input` *(default)* — The user verifies their identity from scratch in the Sardine
  hosted widget (passport, driver's license, liveness check, etc.). Use this for new users
  or when you need specific additional verification steps.

- `kyc_sharing` — The user consents to share an identity already verified by another Sardine
  partner. This produces near-instant approval for returning Sardine users.


**Scopes**
Control which data the widget will collect or share:
- `profile` — Basic personal information (name, DOB, address, email, phone) - `doc_kyc` — Government ID document scan + liveness check - `liveness` — Liveness check only - `ssn` — Social Security Number (US users)

**After the Widget**
When the user completes the flow the widget redirects to `successUrl`. Call `GET /identity/entities/{customerId}` to retrieve the verified data.




## OpenAPI

````yaml /api_reference/identity.yaml post /identity/consents/widget
openapi: 3.0.3
info:
  version: '1.0'
  title: Identity API
  description: Reference for Sardine Universal Identity API (identity.sardine.ai)
  contact:
    email: support@sardine.io
    name: Sardine
    url: docs.sardine.io
servers:
  - url: https://api.sandbox.sardine.ai/v1
    description: Sandbox
  - url: https://api.sardine.ai/v1
    description: Production
security:
  - ClientSecret: []
paths:
  /identity/consents/widget:
    post:
      tags:
        - Consent Widget
      summary: Get KYC Widget URL
      description: >
        Generates a hosted widget URL that you redirect your user to (or embed
        as an iframe) to complete KYC or share an existing verified identity.


        **Flows**

        - `kyc_input` *(default)* — The user verifies their identity from
        scratch in the Sardine
          hosted widget (passport, driver's license, liveness check, etc.). Use this for new users
          or when you need specific additional verification steps.

        - `kyc_sharing` — The user consents to share an identity already
        verified by another Sardine
          partner. This produces near-instant approval for returning Sardine users.


        **Scopes**

        Control which data the widget will collect or share:

        - `profile` — Basic personal information (name, DOB, address, email,
        phone) - `doc_kyc` — Government ID document scan + liveness check -
        `liveness` — Liveness check only - `ssn` — Social Security Number (US
        users)


        **After the Widget**

        When the user completes the flow the widget redirects to `successUrl`.
        Call `GET /identity/entities/{customerId}` to retrieve the verified
        data.
      operationId: post-identity-consents-widget
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customerId
              properties:
                customerId:
                  type: string
                  description: Sardine customer UUID
                  example: 3f8c1a22-1234-4abc-9def-000000000001
                successUrl:
                  type: string
                  format: uri
                  description: URL to redirect the user to after successful completion
                  example: https://yourapp.com/kyc/success
                manualKycUrl:
                  type: string
                  format: uri
                  description: >-
                    Fallback URL if automated verification fails and manual
                    review is needed
                  example: https://yourapp.com/kyc/manual
                scope:
                  type: array
                  description: >
                    Verification scopes to request. Defaults to `["profile"]`.
                    Use `["profile", "doc_kyc"]` for a full document
                    verification flow.
                  items:
                    type: string
                    enum:
                      - profile
                      - doc_kyc
                      - liveness
                      - ssn
                  default:
                    - profile
                  example:
                    - profile
                    - doc_kyc
                flow:
                  type: string
                  description: Verification flow type. Defaults to `kyc_input`.
                  enum:
                    - kyc_input
                    - kyc_sharing
                  default: kyc_input
                  example: kyc_input
                autoRedirect:
                  type: boolean
                  description: >
                    If true, the widget automatically redirects to `successUrl`
                    upon completion without showing a confirmation screen.
                  default: false
                  example: false
            example:
              customerId: 3f8c1a22-1234-4abc-9def-000000000001
              successUrl: https://yourapp.com/kyc/success
              scope:
                - profile
                - doc_kyc
              flow: kyc_input
      responses:
        '200':
          description: Widget URL generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  widgetUrl:
                    type: string
                    format: uri
                    description: >
                      Fully-formed URL to the Sardine hosted KYC widget.
                      Redirect the user here or embed it in an iframe.
                    example: >-
                      https://identity.sardine.ai/?client_token=abc123&consent_id=xyz789&success_url=...
              example:
                widgetUrl: >-
                  https://identity.sardine.ai/?client_token=abc123&consent_id=xyz789&success_url=https%3A%2F%2Fyourapp.com%2Fkyc%2Fsuccess
        '400':
          description: >-
            Customer ID missing or not found, invalid scope or flow, or user
            already consented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid client credentials
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Customer not found for customer ID
        status:
          type: integer
          example: 400
  securitySchemes:
    ClientSecret:
      type: http
      scheme: basic
      description: >
        HTTP Basic Auth. Use your `clientId` as the username and `clientSecret`
        as the password.

````