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

# 👤 User Creation and Verification

> Create users and complete identity verification through KYC links, direct KYC submission, or KYB for business users.

***

# Integration Flow

<Steps>
  <Step title="Create the user">
    [Create User](/reference/userpartnercontrollerv2_createuser) with `externalUserId`, `email`, and `identifier`
  </Step>

  <Step title="Verify the user (KYC or KYB)">
    **Option A**: [Generate KYC Link](/reference/userpartnercontrollerv2_createverificationlink) to redirect the user to our provider

    **Option B**: [Submit KYC Data](/reference/userpartnercontrollerv2_createuserkyc) directly via API

    **Option C**: [Generate KYB Link](/reference/userpartnercontrollerv2_generatekybverificationlink) for business users
  </Step>

  <Step title="Get verification status">
    Poll via [Get KYC Details](/reference/kycpartnercontrollerv2_getuserverificationdetails) or [Get KYB Details](/reference/kybpartnercontrollerv2_getuserkybdetails), or receive results through [Webhooks](/docs/how-our-webhooks-work)
  </Step>
</Steps>

# 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:

1. **Send a Request to Create a User**
   * Make a **POST** request to the [User Endpoint](/reference/userpartnercontrollerv2_createuser) 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`.

2. **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.

3. **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

<Note>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**.</Note>

## 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

1. **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

2. **Send a Request to Generate the KYC Link**
   * Make a **POST** request to the [Generate KYC Link Endpoint](/reference/userpartnercontrollerv2_createverificationlink) endpoint with the required parameters (`userId`, `country`, and `partnerRedirectUri` if necessary).

3. **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.

4. **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

1. **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:
   ```html theme={null}
   <button onclick="window.location.href='https://example.com/kyc-link';">
     Complete Your KYC Verification
   </button>
   ```

2. **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](/reference/kycpartnercontrollerv2_getuserverificationdetails) 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](/docs/how-our-webhooks-work) for more information**

1. **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.

2. **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).

3. **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](/reference/userpartnercontrollerv2_createuserkyc) 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                          |

<Note>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](/reference/userpartnercontrollerv2_createverificationlink)), the accepted document types are `NATIONAL_ID`, `VOTER_ID`, `PASSPORT`, and `TAX_ID` for all countries including Mexico.</Note>

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](/reference/userpartnercontrollerv2_createuserkyc) 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

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

| 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 sandbox environment, KYC verification does not perform real identity checks. You can submit random or test data — documents do not need to be real.

### Example

```json theme={null}
{
  "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](/docs/how-our-webhooks-work))
* **Polling**: Use [Get KYC Details](/reference/kycpartnercontrollerv2_getuserverificationdetails) to check the current status

# KYB Verification for Business Users

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

For business users, generate a KYB (Know Your Business) verification link using the [Generate KYB Link](/reference/userpartnercontrollerv2_generatekybverificationlink) 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:

```json theme={null}
{
  "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](/reference/kybpartnercontrollerv2_getuserkybdetails) endpoint to check the verification status, or listen for webhook events.

***

## What's Next

* [Create User](/reference/userpartnercontrollerv2_createuser)
* [Generate KYC Link](/reference/userpartnercontrollerv2_createverificationlink)
* [Submit KYC Data](/reference/userpartnercontrollerv2_createuserkyc)
* [Generate KYB Link](/reference/userpartnercontrollerv2_generatekybverificationlink)
* [Get KYC Details](/reference/kycpartnercontrollerv2_getuserverificationdetails)
* [Get KYB Details](/reference/kybpartnercontrollerv2_getuserkybdetails)