Skip to main content
POST
/
api
/
partner
/
v2
/
users
/
{id}
/
kyc
/
verification-link
cURL
curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/users/{id}/kyc/verification-link \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <partner-api-key>' \
  --data '
{
  "country": "MX",
  "partnerRedirectUri": "https://partner.com or myapp://partner.com"
}
'
{
  "success": true,
  "data": {
    "kycLink": "<string>"
  }
}
Generates a direct KYC verification link for an existing user under your partner account.
This allows you to redirect the user to a KYC provider to complete identity verification.

​
🔐 Headers

HeaderDescription
partner-api-keyAPI key associated with your partner account. Required. See API Key Generation Guide.
This endpoint requires authentication using a valid partner-api-key.

​
📥 Request Body

FieldTypeRequiredDescription
countrystring✅The country code where the partner operates. Must be a valid ISO 3166-1 alpha-2 country code. Examples: MX, DO.
partnerRedirectUristring🔘URL to which the user is redirected after completing KYC. Accepts both HTTPS and custom mobile URI schemes (e.g., https://, myapp://).

​
📘 Example Request

curl --request POST \
     --url https://staging-api.capa.fi/api/partner/v2/users/d1baa719-f382-4a4a-9940-81063b6fb0bb/kyc/verification-link \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'partner-api-key: {{API-KEY}}' \
     --data '
{
  "country": "MX",
  "partnerRedirectUri": "https://capa.fi"
}
'

​
📤 Response Body

FieldTypeDescription
kycLinkstringThe direct link to the KYC provider for the user.

​
📘 Example Response

{
  "kycLink": "https://kyc-provider.com/session/abcd-1234"
}

​
⚠️ Important Notes & Requirements

  • Partner API Key is mandatory: All requests must include a valid PartnerApiKey in the header. Get your API key.
  • User must exist: You must create the user first using the Create User endpoint before generating a verification link.
  • Supported Countries: Only supported countries for KYC include MX (Mexico) and DO (Dominican Republic).
  • KYC Provider Sessions: Each kycLink is unique and tied to a single verification session. If expired, a new link must be generated.
  • Redirection: If partnerRedirectUri is not provided, the user may not be redirected after completing the KYC process.

​
✅ Use Cases

  • Initiate KYC Flow
    Trigger a KYC process for a user immediately after account creation by generating a verification link and directing the user to it.
  • Email or App Link
    Embed the kycLink in an onboarding email or app screen so the user can complete verification with one click.
  • Custom App Redirect
    Use partnerRedirectUri to bring the user back to your app (web or mobile) after finishing KYC verification with the provider.

​
Error Codes

​
Common Errors

HTTP StatusCodeMessage
401UNAUTHORIZED”API Key is missing”
401UNAUTHORIZED”Invalid API Key format”
401UNAUTHORIZED”Invalid API Key”
403INVALID_PARTNER_FLOW”The partner has an invalid flow.”

​
User Ownership Errors

HTTP StatusCodeMessage
401UNAUTHORIZED”Partner information is required for this operation”
401UNAUTHORIZED”User is not associated with the partner”

​
Endpoint-Specific Errors

HTTP StatusCodeMessage
400INVALID_USER_INPUT_ERROR”Invalid User Input”
400INVALID_VERIFICATION_TYPE_FOR_USER” users can only request verification”
400KYC_TEMPLATE_NOT_CONFIGURED_ERROR”KYC template not configured for “
404NOT_FOUND_ERROR”Requested User was not found”
500INTERNAL_SERVER_ERROR”Failed to create verification link”

Headers

​
partner-api-key
string
required

Api key for the affiliated partner that is performing the request

Path Parameters

​
id
string
required

The id of the entity

Body

application/json
​
country
enum<string>
required

The country code for the partner

@description The country must be a valid ISO 3166-1 alpha-2 country code, see: @link https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

Available options:
MX,
DO,
US,
AT,
BE,
BG,
HR,
CY,
CZ,
DK,
EE,
FI,
FR,
DE,
GR,
HU,
IE,
IT,
LV,
LT,
LU,
MT,
NL,
PL,
PT,
RO,
SK,
SI,
ES,
SE,
IS,
LI,
NO,
CH,
GB,
MC,
SM,
AD,
VA
Example:

"MX"

​
partnerRedirectUri
string

The redirect URI for the partner to redirect the user after the KYC process is completed

Example:

"https://partner.com or myapp://partner.com"

Response

201 - application/json
​
success
boolean
Example:

true

​
data
object