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

# Generate KYC Link

> Generates a hosted identity verification link for a related person. Share the link with the person so they can upload their ID and complete a liveness check. Generating a new link invalidates the previous one. Links expire after 72 hours.

Generates a hosted identity verification link for a related person. Share the link with the person — it opens a Rolla-hosted page where they upload an ID document and complete a liveness check. Their verification status is reflected in [Get Requirements](/api-reference/endpoint/accounts/requirements).

<Tip>
  Already verify these people in your own onboarding? [Submit Representative KYC Reliance](/api-reference/endpoint/accounts/related-person-kyc-reliance) lets you upload the passport and liveness capture you collected instead of sending them through this hosted flow. It is enabled per partner, and can be mixed with hosted links across the same account.
</Tip>

## Example Request

```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/accounts/eec3cbed-79d8-4370-87a0-b6be9e287337/related-persons/a3d4f21e-f499-488f-8508-43228dfea485/kyc-link" \
  -H "X-API-Key: your_api_key_here"
```

## Example Response

```json theme={null}
{
  "success": true,
  "message": "KYC link generated successfully",
  "data": {
    "token": "969e35c36f99f9d511863c89cea0d4082bc3bf66b5484d9a70d79a7c39d6fe74",
    "url": "https://app.rolla.xyz/en/kyc/director/969e35c36f99f9d511863c89cea0d4082bc3bf66b5484d9a70d79a7c39d6fe74",
    "status": "active",
    "expiresAt": "2026-06-15T23:32:12.902Z",
    "relatedPersonId": "a3d4f21e-f499-488f-8508-43228dfea485"
  }
}
```

## Key Behaviours

<Info>
  Links expire after **72 hours**. Generating a new link for the same person invalidates the previous one.
</Info>

<Tip>
  The link `status` becomes `completed` once the person passes verification, or `rejected` if it fails — in which case you can generate a fresh link for a retry.
</Tip>


## OpenAPI

````yaml POST /accounts/{accountId}/related-persons/{personId}/kyc-link
openapi: 3.1.0
info:
  title: Rolla Developer API
  description: >-
    API for programmatic transaction management on the Rolla platform. Monetary
    `amount` fields use the smallest unit of the referenced currency unless an
    endpoint says otherwise (e.g. NGN = kobo, USD = cents, where **100 cents =
    USD 1.00**).
  version: 1.0.0
servers:
  - url: https://api.rolla.xyz/api/v1/external
    description: Production server
security:
  - apiKeyAuth: []
paths:
  /accounts/{accountId}/related-persons/{personId}/kyc-link:
    post:
      summary: Generate KYC Link
      description: >-
        Generates a hosted identity verification link for a related person.
        Share the link with the person so they can upload their ID and complete
        a liveness check. Generating a new link invalidates the previous one.
        Links expire after 72 hours.
      operationId: createAccountKycLink
      parameters:
        - name: accountId
          in: path
          required: true
          description: >-
            Identifier of an account owned by the same user as your API key's
            business
          schema:
            type: string
            format: uuid
        - name: personId
          in: path
          required: true
          description: Related person identifier
          schema:
            type: string
            format: uuid
      responses:
        '201':
          description: KYC link generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: KYC link generated successfully
                  data:
                    $ref: '#/components/schemas/KycLink'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Account or related person not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    KycLink:
      type: object
      properties:
        token:
          type: string
        url:
          type: string
          description: >-
            Hosted verification page to share with the person. Links expire
            after 72 hours.
        status:
          type: string
          enum:
            - active
            - completed
            - rejected
            - expired
        expiresAt:
          type: string
          format: date-time
        relatedPersonId:
          type: string
          format: uuid
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Rolla API key

````