> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qash.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Start KYC
> Initiate identity verification for a user via Persona.
Requires `X-Api-Key` and `X-Api-Secret` headers. See [Authentication](/api-reference/users/introduction#authentication) for details.
Redirect the user to the returned `verificationUrl` to complete their identity check through Persona. Once completed, Persona notifies Qash automatically and the user's `status` transitions to `active` — no polling or webhook required on your end.
Calling this again while a verification is already in progress does **not** error — it returns `200` with `isExisting: true` and the same `verificationUrl`/`inquiryId` as before, so it's safe to call defensively.
Returns `422` with `KYC already finalized with status: ` only if the user's most recent KYC has already reached a terminal state (`approved`, `declined`, `rejected`, `failed`, or `expired`). Call [KYC status](/api-reference/users/kyc-status) to check current status before retrying.
## OpenAPI
````yaml api-reference/openapi.json POST /api/v1/partner/kyc
openapi: 3.1.0
info:
title: QASH API
description: >-
QASH endpoints for exchange rates, cards, and partner-facing financial
workflows.
version: 1.0.0
servers:
- url: https://api.qash.ai
description: Partner API (Production)
- url: https://staging.qash.ai
description: Staging
- url: https://app.qash.ai
description: Production
security: []
tags:
- name: Exchange rates
description: Public endpoints for supported assets and TRM-based quotes.
- name: Cards
description: >-
Authenticated partner endpoints for card state, controls, limits, and
balances.
- name: Users
description: Admin endpoints for user provisioning and account management.
paths:
/api/v1/partner/kyc:
post:
tags:
- Users
summary: Start KYC
description: >-
Initiates identity verification for a user via Persona. Returns a
`verificationUrl` to redirect the user to. Once the user completes
verification, Persona notifies Qash automatically and the user's
`status` transitions to `active`.
operationId: partnerStartKyc
requestBody:
description: KYC initiation payload.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PartnerStartKycRequest'
examples:
full:
summary: All fields
value:
userId: 03384ada-a9c5-4c2e-a1bd-a13629ba060c
firstName: Juan
lastName: Pérez
email: usuario@empresa.com
phone: '+573001234567'
birthDate: '1990-04-15'
minimal:
summary: Required fields only
value:
userId: 03384ada-a9c5-4c2e-a1bd-a13629ba060c
firstName: Juan
lastName: Pérez
email: usuario@empresa.com
responses:
'200':
description: KYC initiated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PartnerStartKycResponse'
examples:
default:
summary: KYC initiated
value:
success: true
verificationUrl: >-
https://inquiry.withpersona.com/verify?inquiry-id=inq_A3VPwfoLJtprzJxREEeq3kmz6MyYyw
inquiryId: inq_A3VPwfoLJtprzJxREEeq3kmz6MyYyw
'400':
description: Missing required fields or invalid `birthDate` format.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
default:
value:
success: false
error: Invalid birthDate format. Use YYYY-MM-DD
'401':
description: Invalid partner credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
default:
value:
success: false
error: Invalid partner credentials
'404':
description: User not found or belongs to a different partner.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
default:
value:
success: false
error: User not found
'409':
description: KYC has already been initiated for this user.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
default:
value:
success: false
error: KYC already in progress for this user
'500':
description: Failed to create the Persona inquiry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
default:
value:
success: false
error: Failed to create Persona inquiry
security:
- partnerApiKey: []
partnerApiSecret: []
components:
schemas:
PartnerStartKycRequest:
type: object
required:
- userId
properties:
userId:
type: string
format: uuid
description: ID of the user to verify, obtained from `POST /users`.
example: 03384ada-a9c5-4c2e-a1bd-a13629ba060c
firstName:
type: string
description: User's first name. Optional — improves Persona pre-fill if provided.
example: Juan
lastName:
type: string
description: User's last name. Optional — improves Persona pre-fill if provided.
example: Pérez
email:
type: string
format: email
description: >-
User's email address. Optional — improves Persona pre-fill if
provided.
example: usuario@empresa.com
phone:
type: string
description: Phone number in international format.
example: '+573001234567'
birthDate:
type: string
format: date
description: Date of birth in `YYYY-MM-DD` format.
example: '1990-04-15'
PartnerStartKycResponse:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
inquiryId:
type: string
description: Persona inquiry ID for tracking the verification.
example: inq_A3VPwfoLJtprzJxREEeq3kmz6MyYyw
verificationUrl:
type: string
format: uri
nullable: true
description: >-
URL to redirect the user to for completing identity verification
via Persona.
example: >-
https://inquiry.withpersona.com/verify?inquiry-id=inq_A3VPwfoLJtprzJxREEeq3kmz6MyYyw
isExisting:
type: boolean
description: >-
True if this returns an already in-progress verification instead
of creating a new one.
example: false
message:
type: string
description: Human-readable status message.
example: >-
KYC verification started. Please complete the verification
process.
required:
- inquiryId
- verificationUrl
- isExisting
- message
required:
- success
- data
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
description: Human-readable error message.
example: Email is required
required:
- success
- error
securitySchemes:
partnerApiKey:
type: apiKey
in: header
name: X-Api-Key
description: Partner API key. Generated from Qash Dashboard → Settings → API Keys.
partnerApiSecret:
type: apiKey
in: header
name: X-Api-Secret
description: Partner API secret. Shown once at creation — store it securely.
````