> ## Documentation Index > Fetch the complete documentation index at: https://developer.tazapay.com/llms.txt > Use this file to discover all available pages before exploring further. # Generate KYC Link > Generate a hosted verification link for an individual entity. The response returns the complete KYC link object, the same as Retrieve a KYC Link. If an unexpired link already exists, it is returned unchanged with a response message, and a different `expiry_seconds` value does not extend it. KYC links are not renewed automatically. Once a link expires, you must call this endpoint again to generate a new link and share it with the individual. Concurrent requests for the same entity return the same link. ## OpenAPI ````yaml post /v3/entity/{entity_id}/kyc_link openapi: 3.1.0 info: title: sandbox version: '3' servers: - url: https://service-sandbox.tazapay.com security: - sec0: [] paths: /v3/entity/{entity_id}/kyc_link: post: tags: - Entity KYC Links summary: Generate a KYC Link description: >- Generate a hosted verification link for an individual entity. The response returns the complete KYC link object, the same as Retrieve a KYC Link. If an unexpired link already exists, it is returned unchanged with a response message, and a different `expiry_seconds` value does not extend it. KYC links are not renewed automatically. Once a link expires, you must call this endpoint again to generate a new link and share it with the individual. Concurrent requests for the same entity return the same link. operationId: generate-kyc-link parameters: - name: entity_id in: path description: Tazapay unique ID of the entity schema: type: string required: true requestBody: required: false content: application/json: schema: type: object properties: expiry_seconds: type: integer minimum: 1800 maximum: 2592000 default: 2592000 description: >- Link validity in seconds, from 30 minutes (1800) to 30 days (2592000). Defaults to 30 days. example: expiry_seconds: 86400 responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/KYCLinkResponse' examples: new_link: summary: New link generated value: status: success message: '' data: entity_id: ent_aaaaaaaaaaaaaaaaaaaa kyc_link: url: https://verify.example.com/kyc/demo-link-001 status: pending created_at: '2026-09-25T10:00:00Z' expires_at: '2026-09-26T10:00:00Z' completed_at: null verification_result: null metadata: null existing_link: summary: Unexpired link returned value: status: success message: >- A KYC link has already been generated and has not expired. Returning the existing link. To generate a new link, expire the current link first. data: entity_id: ent_aaaaaaaaaaaaaaaaaaaa kyc_link: url: https://verify.example.com/kyc/demo-link-001 status: pending created_at: '2026-09-25T10:00:00Z' expires_at: '2026-09-26T10:00:00Z' completed_at: null verification_result: null metadata: customer_reference: customer_demo_001 '400': description: >- Bad Request. See [error codes](/api-reference/appendix/generate-kyc-link). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: KYC Links are not enabled for this account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Entity not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: >- Too many requests. KYC link generation is rate limited per account. Retry after a short wait. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: >- The verification session could not be reactivated. Retry the request. See [error codes](/api-reference/appendix/generate-kyc-link). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Another request for the same entity is still generating the link. Retry the request to receive that link. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - sec0: [] components: schemas: KYCLinkResponse: type: object properties: status: type: string description: Response status. enum: - success message: type: string description: >- Response message. Set when an unexpired KYC link is returned unchanged. example: '' data: type: object properties: entity_id: type: string description: Tazapay unique ID of the entity. pattern: ^ent_.{20}$ minLength: 24 maxLength: 24 example: ent_aaaaaaaaaaaaaaaaaaaa kyc_link: $ref: '#/components/schemas/KYCLink' required: - entity_id - kyc_link required: - status - message - data ErrorResponse: type: object description: Standard error response structure properties: status: type: string enum: - error description: Always 'error' for error responses message: type: string description: High-level error message errors: type: array description: Array of detailed error objects items: type: object properties: code: type: integer description: Specific error code message: type: string description: Detailed error message remarks: type: string description: Additional context or suggestions for resolution KYCLink: type: object properties: url: type: string description: Hosted verification URL to share with the individual. format: uri status: type: string description: Current link status. enum: - pending - requires_action - approved - rejected - expired created_at: type: string description: Creation timestamp (RFC 3339, with optional fractional seconds). format: date-time expires_at: type: string description: >- Timestamp when the link expires. When the link is expired early with Expire a KYC Link or Submit Entity, it is set to the time of the expiry. format: date-time completed_at: type: string nullable: true description: >- Recorded when the link becomes approved, rejected, or expired. `null` until the link reaches one of these statuses. format: date-time verification_result: $ref: '#/components/schemas/KYCLinkVerificationResult' nullable: true description: Verification outcome. `null` until the link is approved or rejected. metadata: type: object nullable: true additionalProperties: true description: >- Custom key-value metadata attached to the KYC link. `null` when no metadata has been set, and an empty object after it is cleared. required: - url - status - created_at - expires_at KYCLinkVerificationResult: type: object properties: outcome: type: string description: >- Verification outcome. The current workflow builds results for terminal approved/rejected outcomes. enum: - approved - rejected - requires_action rejection_type: type: string nullable: true description: >- Provider rejection classification, for example FINAL or RETRY. Preserve the received value. `null` when the verification is not rejected. rejection_reasons: type: array description: Available rejection reasons; an empty array when there are none. items: type: object properties: code: type: string description: >- Rejection reason code from Sumsub, for example SELFIE_MISMATCH. See [Sumsub rejection labels](https://docs.sumsub.com/docs/rejection-explanatory-buttons) for the full list of codes and their meanings. description: type: string description: Description supplied with the review. user_message: type: string description: Explanation or instructions supplied for the individual. checks: type: object nullable: true properties: identity: $ref: '#/components/schemas/KYCLinkIdentityCheck' nullable: true address: $ref: '#/components/schemas/KYCLinkAddressCheck' nullable: true selfie: $ref: '#/components/schemas/KYCLinkIdentityCheck' nullable: true description: >- Available checks. A check that was not performed for the review is `null`, for example `selfie` when the verification level has no liveness check. extracted_data: type: object nullable: true properties: first_name: type: string nullable: true description: Extracted first name. last_name: type: string nullable: true description: Extracted last name. date_of_birth: type: string nullable: true description: Date of birth in YYYY-MM-DD format. format: date nationality: type: string nullable: true description: Country code returned by verification, for example IND. address: type: object nullable: true properties: line1: type: string nullable: true description: First address line (building number and street). line2: type: string nullable: true description: Second address line (flat, building name or sub-street). city: type: string nullable: true description: City. state: type: string nullable: true description: State, province or region. postal_code: type: string nullable: true description: Postal code. country: type: string nullable: true description: Country code returned by verification. description: >- Available extracted identity details, including on some rejected outcomes. Fields that were not extracted are `null`. required: - outcome KYCLinkIdentityCheck: type: object properties: status: type: string description: Result of the check. enum: - passed - failed document_type: type: string nullable: true description: Document type returned by the provider. `null` when not returned. document_country: type: string nullable: true description: >- Document country code returned by verification, for example IND. `null` when not returned. document_number: type: string nullable: true description: >- Document number, returned unmasked in API responses (masked in webhooks). `null` when not returned. document_expiry: type: string nullable: true description: Document expiry in YYYY-MM-DD format. `null` when not returned. format: date required: - status KYCLinkAddressCheck: type: object properties: status: type: string description: Result of the check. enum: - passed - failed document_type: type: string nullable: true description: Document type returned by the provider. `null` when not returned. required: - status securitySchemes: sec0: type: http scheme: basic ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.