Integration Flow

Create the user

Create User with externalUserId, email, and identifier

Verify the user (KYC or KYB)

Option A: Generate KYC Link to redirect the user to our providerOption B: Submit KYC Data directly via APIOption C: Generate KYB Link for business users

Get verification status

Poll via Get KYC Details or Get KYB Details, or receive results through Webhooks

Create the User

To onboard a new user into your system, you first need to register them with the Capa API. Here’s how the process works:

Send a Request to Create a User
- Make a POST request to the User Endpoint with the necessary user information, such as externalUserId, email, and identifier.
- The externalUserId is your own unique identifier for this user, ensuring we make your user as unique as possible.
- The type defines the type of user between the following options: INDIVIDUAL, BUSINESS.
Receive the User ID
- Upon successful creation, Capa will return a unique userId for the newly created user. This userId is required for generating the KYC verification link in the next step.
Store the User ID
- Save the returned userId in your system, linking it to your own externalUserId. This userId will be used whenever you need to perform actions related to this user, such as KYC verification.

Complete User KYC

For individual users you have two verification options: Generate KYC Verification Link (redirect the user to our provider) or Send KYC Information Directly (submit identity data via API). For business users, use the KYB Verification Link.

Generate KYC Verification Link with our Provider

Once you have successfully created a user, the next step is to generate a KYC verification link. This link allows the user to complete the Know Your Customer (KYC) process, which is required for regulatory compliance.

1. Generate Link

Prepare the KYC Verification Request
- Use the userId obtained from the user creation step.
- Determine the country in which the user resides or where the verification is needed. Ensure the country code is compliant with the supported countries in the Capa API.
- Use the partnerRedirectUri to determine the redirection after the KYC completion
Send a Request to Generate the KYC Link
- Make a POST request to the Generate KYC Link Endpoint endpoint with the required parameters (userId, country, and partnerRedirectUri if necessary).
Receive the KYC Link
- Upon successful submission, Capa will return a direct kycLink for the user. This link directs the user to a secure Metamap webpage where they can complete the KYC process.
Distribute the KYC Link to the User
- Share the kycLink with the user via email, SMS, or within your app. Provide clear instructions on how to use the link to complete the KYC verification.

2. Implement the KYC Link on Your Platform

Embed the KYC Link in Your User Interface
- Use the kycLink in your website or application to create a button or hyperlink that users can click to start their KYC verification.
- Example:
```
<button onclick="window.location.href='https://example.com/kyc-link';">
  Complete Your KYC Verification
</button>
```
Guide the User Through the KYC Process
- Ensure the user knows they will be redirected to a third-party webpage (Metamap) for KYC verification. Provide any necessary guidance to help them complete the process smoothly.

3. Get KYC Information

To get the KYC Information on demand use the Get KYC Details endpoint to obtain all of the information from the user’s KYC including the status. This is an optional step since you will be able to get the information through the webhook too.

4. Handle the Webhook Verification Response

Follow the 📣 Webhooks for more information

Receive the Webhook Notification
- After the user completes the KYC process, Capa will send a verification response to your system via a webhook. This response will contain the result of the KYC process.
Process the Webhook Data
- Set up your system to handle incoming webhook notifications. Verify the authenticity of the webhook by checking the signature included in the header and process the KYC status accordingly (e.g., update the user’s verification status in your database).
Act on the Verification Result
- Based on the result from the webhook, take appropriate action:
  - If Verified: Grant access to features or services that require a verified status.
  - If Rejected: Notify the user and provide instructions on how to retry the verification process.
  - If Further Review is Needed: Follow up as required to assist the user through any manual review processes.

Send KYC Information Directly

For partners who already collect identity documents on their own platform, you can submit KYC data directly to Capa without redirecting the user. This avoids requiring users to go through the verification process a second time. Use the Submit KYC Data endpoint:

POST /api/partner/v2/users/{userId}/kyc

Required Fields

Field	Description
`country`	ISO 3166-1 alpha-2 country code (e.g., `MX`, `DO`, `US`, or supported EU countries)
`profession`	User’s profession (e.g., `EMPLOYEE`, `ENTREPRENEUR`, `ENGINEER`, `STUDENT`)
`countryOfBirth`	Country of birth (ISO 3166-1 alpha-2 code, e.g., `MX`, `DO`, `US`)
`selfieUrl`	Pre-signed URL to the user’s selfie image
`identity`	Object containing `type`, `frontIdUrl`, and `backIdUrl` (see identity types below)

Identity Document Types

The identity.type field accepts the following values:

Type	Description
`GOVERNMENT_ID`	Government-issued photo ID (e.g., INE/IFE in Mexico)
`RESIDENT_CARD`	Resident or immigration card
`TAX_ID`	Tax identification document

For the direct KYC API (this endpoint), the identity.type values above (GOVERNMENT_ID, RESIDENT_CARD, TAX_ID) are accepted for all countries. For Mexico, use GOVERNMENT_ID — Capa maps it internally to INE/IFE (Voter ID). For the KYC link flow (provider-hosted verification via Generate KYC Link), the accepted document types are NATIONAL_ID, VOTER_ID, PASSPORT, and TAX_ID for all countries including Mexico.

The identity object requires both frontIdUrl and backIdUrl — front and back must be uploaded as separate images, not merged into a single file.

Additional Required Fields for Mexico (MX)

When country is MX, the following fields are also required:

Field	Description
`taxId`	RFC tax identification number (format: `^[A-Z]{4}\d{6}[A-Z0-9]{3}$`, e.g., `LOZG7802117B9`). CURP is not accepted.
`economicActivity`	User’s economic activity (see the API reference for the full list of accepted values)
`documents`	Array of documents with `ADDRESS_PROOF` (`{ type: "ADDRESS_PROOF", fileUrl: "..." }`). Required only if the ID used is not an INE — if the user’s INE address matches their current address, this can be omitted.
`address`	Object with `street`, `city`, `state`, `zipCode`, `country`

Optional Fields

Field	Description	Availability
`phoneNumber`	User’s phone number	All countries
`taxId`	Tax identification number	Optional for non-MX (required for MX)
`economicActivity`	User’s economic activity	Optional for non-MX (required for MX)
`documents`	Array of additional documents	Optional for non-MX (conditionally required for MX — see above)
`address`	Object with `street`, `city`, `state`, `zipCode`, `country`	Optional for non-MX (required for MX)
`pep`	Politically Exposed Person information (`relation`, `position`, `period`)	MX only
`beneficiaryOwner`	Beneficial owner details (if different from the user)	MX only
`resourceProvider`	Resource provider details (if different from the user)	MX only
`realOwner`	Real owner details (if different from the user)	MX only

File URL Requirements

All document URLs (frontIdUrl, backIdUrl, selfieUrl, and any fileUrl in documents) must be accessible pre-signed URLs that Capa can download.

File	Max Size	Allowed Formats
Selfie	3 MB	JPEG, JPG, PNG
Front ID / Back ID	5 MB each	JPEG, JPG, PNG, PDF
Additional documents (ADDRESS_PROOF)	10 MB	JPEG, JPG, PNG, PDF

URLs must remain accessible for at least several minutes after submission. Short-lived signed URLs (e.g., GCS URLs with a few seconds TTL) will cause FAILED_TO_DOWNLOAD_FILE_FROM_PRESIGNED_URL errors. We recommend a minimum TTL of 30 minutes.

Sandbox Behavior

In the staging environment, KYC verification does not perform real identity checks. You can submit random or test data — documents do not need to be real.

Example

{
  "country": "MX",
  "profession": "ENGINEER",
  "countryOfBirth": "MX",
  "selfieUrl": "https://storage.example.com/selfie.jpg?token=abc123",
  "identity": {
    "type": "GOVERNMENT_ID",
    "frontIdUrl": "https://storage.example.com/id-front.jpg?token=abc123",
    "backIdUrl": "https://storage.example.com/id-back.jpg?token=abc123"
  },
  "phoneNumber": "+524401234567",
  "taxId": "LOZG7802117B9",
  "economicActivity": "DESARROLLO DE SOFTWARE",
  "documents": [
    { "type": "ADDRESS_PROOF", "fileUrl": "https://storage.example.com/proof.jpg?token=abc123" }
  ],
  "address": {
    "street": "Av. Reforma 123",
    "city": "Mexico City",
    "state": "CDMX",
    "zipCode": "06600",
    "country": "MX"
  }
}

Verification Flow

Verification is asynchronous. After submitting, results are delivered through:

Webhooks: Receive a VERIFIED_USER, REJECTED_KYC, or REVIEW_NEEDED_KYC event (see 📣 Webhooks)
Polling: Use Get KYC Details to check the current status

KYB Verification for Business Users

KYB verification is only available for users created with type: "BUSINESS". Individual users must use KYC verification (link or direct submission).

For business users, generate a KYB (Know Your Business) verification link using the Generate KYB Link endpoint:

POST /api/partner/v2/users/{userId}/kyb/verification-link

Required Fields

country: ISO 3166-1 alpha-2 country code

Optional Fields

partnerRedirectUri: URL to redirect the user after KYB completion (supports HTTPS and custom mobile URI schemes like myapp://)

Response

The endpoint returns a kybLink that you can redirect the business user to for completing verification:

{
  "success": true,
  "data": {
    "kybLink": "https://kyb-provider.example.com/verify/..."
  }
}

Each link is tied to a unique session. If expired, generate a new one.

Checking Results

Use the Get KYB Details endpoint to check the verification status, or listen for webhook events.

Documentation

👤 User Creation and Verification

Integration Flow

Create the User

Complete User KYC

Generate KYC Verification Link with our Provider

1. Generate Link

2. Implement the KYC Link on Your Platform

3. Get KYC Information

4. Handle the Webhook Verification Response

Send KYC Information Directly

Required Fields

Identity Document Types

Additional Required Fields for Mexico (MX)

Optional Fields

File URL Requirements

Sandbox Behavior

Example

Verification Flow

KYB Verification for Business Users

Required Fields

Optional Fields

Response

Checking Results

What’s Next

Documentation

​Integration Flow

​Create the User

​Complete User KYC

​Generate KYC Verification Link with our Provider

​1. Generate Link

​2. Implement the KYC Link on Your Platform

​3. Get KYC Information

​4. Handle the Webhook Verification Response

​Send KYC Information Directly

​Required Fields

​Identity Document Types

​Additional Required Fields for Mexico (MX)

​Optional Fields

​File URL Requirements

​Sandbox Behavior

​Example

​Verification Flow

​KYB Verification for Business Users

​Required Fields

​Optional Fields

​Response

​Checking Results

​What’s Next

Integration Flow

Create the User

Complete User KYC

Generate KYC Verification Link with our Provider

1. Generate Link

2. Implement the KYC Link on Your Platform

3. Get KYC Information

4. Handle the Webhook Verification Response

Send KYC Information Directly

Required Fields

Identity Document Types

Additional Required Fields for Mexico (MX)

Optional Fields

File URL Requirements

Sandbox Behavior

Example

Verification Flow

KYB Verification for Business Users

Required Fields

Optional Fields

Response

Checking Results

What’s Next