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

# Users Creation

> Full onboarding lifecycle — create users, capture documentation, trigger KYC/KYB, and track verification status.

The **Users Creation** module lets you manage the **complete onboarding lifecycle of users** through your API integration with Vita. This covers creating users (natural persons or businesses), capturing required documentation, triggering identity verification (KYC for individuals, KYB for businesses), and tracking the verification status throughout its lifecycle.

The module is designed to support secure, standardized, regulation-compliant onboarding directly from your application, with full control over when verification is initiated and full visibility into its outcome.

## What you can do

> [card] Create users
>
> Natural persons or businesses, in a single call or progressively.

> [card] Capture data progressively
>
> Initial registration, documentation uploads, identity verification, regulatory compliance.

> [card] Patch existing users
>
> Complete missing fields before submitting for verification.

> [card] Trigger verification on demand
>
> Submit for verification via the `submit_for_verification` field.

> [card] Query verification status
>
> Check any user's status at any time.

> [card] Receive webhooks
>
> Automatic notifications when verification status changes.

## User types

Vita Business supports two user categories, each with its own verification flow:

| Category | Description | Verification flow |
| - | - | - |
| `natural` | A natural person registering as an individual. | KYC (Know Your Customer) |
| `business` | A legal entity registering as an organization or company. | KYB (Know Your Business) |

Both types must complete their respective verification flow before being authorized to operate on the platform.

## User lifecycle

A user created via the API moves through the following statuses, tracked in the `profile_verification` field:

| Status | Description |
| - | - |
| `initial` | The user has been created, but not all required information has been provided. Verification has **not yet been triggered**. |
| `started` | All required information has been submitted, and the verification process is **in progress**. |
| `verification_required` | Additional information was requested for the account to be accepted. |
| `accepted` | Verification was **approved**. The user is authorized to operate. |
| `rejected` | Verification was **rejected**. The user is not authorized to operate. |

### Lifecycle flow

```mermaid theme={null}
flowchart TD
  C[Create user] --> I[initial]
  I -->|data incomplete| P[PATCH user to add missing fields]
  P --> I
  I -->|submit_for_verification: true| S[started]
  P -->|submit_for_verification: true| S
  S --> A[accepted]
  S --> VR[verification_required]
  S --> R[rejected]
```

**1. Creation**

A new user is created with `category` set to `natural` or `business`.

**2. Initial state**

If required information is missing, the user enters the `initial` status. They can be updated via `PATCH` to add the missing fields.

**3. Submission**

When all required fields are present, your integration triggers verification by sending `submit_for_verification: true`. This moves the user to `started`.

**4. Resolution**

Once Vita's team reviews the user, the status moves to `accepted`, `verification_required`, or `rejected`.

At any point in the lifecycle, your integration can query the user's status to determine whether they're approved, rejected, or pending information.

## How `submit_for_verification` works

* Set `submit_for_verification: true` in the user creation (`POST`) or update (`PATCH`) request to instruct the API to **initiate verification** once all required fields are present.
* If the field is omitted or set to `false`, the user is created (or updated) **without starting verification**, so you can build the profile progressively across multiple requests.
* Once verification has been triggered and the user is in `started`, `accepted`, or `rejected`, this flag has no further effect.

### When to use it

| Scenario | Recommended approach |
| - | - |
| You have **all required information** at creation time | Set `submit_for_verification: true` in the `POST` request to create and submit in a single call. |
| You collect user data **progressively** across multiple steps | Create the user without `submit_for_verification`, then `PATCH` the user as new data arrives. When the final required field is captured, send `submit_for_verification: true` in the same `PATCH` to trigger verification. |

## Progressive onboarding (PATCH flow)

For integrations that collect user information across multiple steps (e.g., a multi-screen onboarding flow), Vita supports **progressive updates** via `PATCH`. You can build the user's profile incrementally without triggering verification until you're ready.

**1. Create the user with initial data**

```http theme={null}
POST /businesses/users
{ "category": "natural", "email": "user@example.com", "first_name": "John", ... }
```

**2. Patch as additional fields arrive**

```http theme={null}
PATCH /businesses/users/:id
{ "address": "...", "document_number": "...", "facial_image": {...} }
```

**3. Trigger verification when complete**

```http theme={null}
PATCH /businesses/users/:id
{ "submit_for_verification": true }
```

This flow gives you full flexibility to design the onboarding experience while ensuring verification only runs when the user's data is complete.

## Data model

> [accordion] Natural user structure
>
> | Field | Description |
> | - | - |
> | `email` | User's email address. |
> | `first_name` | User's first name. |
> | `last_name` | User's last name. |
> | `category` | User type (`natural`). |
> | `birthdate` | Date of birth (`YYYY-MM-DD`). |
> | `gender` | User's gender. |
> | `document_type` | Type of identity document (`dni`, `passport`, etc.). |
> | `document_number` | Primary document number. |
> | `secondary_document_number` | Secondary document number, if applicable. |
> | `document_expedition_date` | Issuance date of the primary document. |
> | `address` | Full address. |
> | `zipcode` | Postal code. |
> | `civil_status` | Civil status (`single`, `married`, …). |
> | `phone` | Phone number including country code. |
> | `profile_verification` | Current verification status. |
> | `accept_pep` | Accepts PEP verification (`true`/`false`). |
> | `accept_real_info` | Accepts real-information validation. |
> | `accept_funds` | Accepts receiving funds. |
> | `ocupation` | Profession or occupation. |
> | `natural_interests` | Platform usage interests (`use_interests`, `other_usability`). |
> | `url_notify_kyc` | Webhook URL for KYC notifications. |
> | `disable_email_notifications` | Disables email notifications. |
> | `country` | Country of residence. |
> | `state` | State or province. |
> | `city` | City. |
> | `birth_country` | Country of birth. |
> | `document_issuing_country` | Country that issued the identity document. |
> | `facial_image` | Facial image file (`filename`, `content_type`). |
> | `document_front` | Front of the document image. |
> | `document_back` | Back of the document image. |
> | `business_external_id` | Custom ID assigned by the client for tracking. |

> [accordion] Business user — main fields
>
> | Field | Description |
> | - | - |
> | `email` | User's email address. |
> | `first_name` | User's or business account name. |
> | `category` | `business`. |
> | `document_type` | Document type for the main user. |
> | `document_number` | Primary document number. |
> | `address` | Main user's address. |
> | `zipcode` | Postal code. |
> | `profile_verification` | Current verification status. |
> | `accept_pep` | Accepts PEP verification. |
> | `accept_real_info` | Accepts real-information validation. |
> | `accept_funds` | Accepts receiving funds. |
> | `business_external_id` | Custom ID for tracking. |
> | `is_business_api` | Has Business API credentials. |
> | `x_login` | API login key. |
> | `x_trans_key` | API transaction key. |
> | `secret` | API secret key. |
> | `url_notify_kyc` | Webhook URL for KYC notifications. |
> | `disable_email_notifications` | Disables email notifications. |
> | `country` | Country of residence. |
> | `state` | State/province. |
> | `city` | City. |
> | `facial_image` | Facial image file. |
> | `document_front` | Front of the document image. |
> | `document_back` | Back of the document image. |

> [accordion] Business object (company)
>
> Represents the legal and commercial information of the company linked to the user — general company data, activity, physical address, legal documentation, and legal representative details.
>
> | Field | Description |
> | - | - |
> | `operation_countries` | Countries where the company operates. |
> | `website_url` | Company website. |
> | `uuid` | Internal company identifier. |
> | `trade_name` | Trade name. |
> | `is_financial_company` | Is a financial entity. |
> | `has_license` | Holds a license. |
> | `same_to_legal_location` | Physical location matches legal address. |
> | `physical_country` | Country of the physical location. |
> | `physical_state` | State/province of the physical location. |
> | `physical_city` | City of the physical location. |
> | `physical_zipcode` | Postal code of the physical location. |
> | `physical_address` | Physical address. |
> | `lr_first_name` | Legal representative — first name. |
> | `lr_last_name` | Legal representative — last name. |
> | `lr_phone_number` | Legal representative — phone. |
> | `lr_document_number` | Legal representative — document number. |
> | `lr_document_issuing_country` | Legal representative — document issuing country. |
> | `lr_document_expedition_date` | Legal representative — document issuance date. |
> | `lr_secondary_document_number` | Legal representative — secondary document number. |
> | `lr_civil_status` | Legal representative — civil status. |
> | `lr_occupation` | Legal representative — occupation. |
> | `lr_gender` | Legal representative — gender. |
> | `lr_document_type` | Legal representative — document type. |
> | `lr_birthdate` | Legal representative — birthdate. |
> | `expected_monthly_payments_usd` | Expected monthly payments range. |
> | `business_interests` | Company usage interests. |
> | `company_statute` | Company statute (PDF). |
> | `tax_identity_document` | Tax identity document (image). |
> | `statement_of_funds_document` | Statement of funds (PDF). |
> | `extra_document` | Additional document (image). |
> | `legal_representative_proof_document` | Legal representative proof document (PDF). |

> [accordion] Business owner (UBO)
>
> Ultimate Beneficial Owners — natural persons who own or control a significant percentage of the company.
>
> | Field | Description |
> | - | - |
> | `ubo_first_name` | UBO first name. |
> | `ubo_last_name` | UBO last name. |
> | `ubo_residence_country` | Country of residence. |
> | `ubo_residence_state` | State or province of residence. |
> | `ubo_residence_city` | City of residence. |
> | `ubo_address` | Address. |
> | `ubo_is_direct` | Is a direct owner. |
> | `ubo_ownership_percentage` | Ownership percentage. |
> | `ubo_document_type` | Document type. |
> | `ubo_document_number` | Document number. |
> | `ubo_country` | Country of birth. |
> | `ubo_start_date` | Date became owner. |
> | `ubo_document_expedition_date` | Document issuance date. |
> | `ubo_has_control` | Has control over the company. |
> | `ubo_is_signer` | Is an authorized signatory. |
> | `ubo_title_position` | Title or position in the company. |
> | `ubo_birthdate` | Date of birth. |
> | `ubo_phone` | Phone number. |
> | `ubo_email` | Email address. |
> | `ubo_zipcode` | Postal code. |
> | `ubo_document_image` | Document image. |
> | `ubo_back_document_image` | Document back image. |

> [accordion] Politically Exposed Person (PEP)
>
> Include this object only if `accept_pep` is `true`. It identifies the person and their relation to relevant public activities.
>
> | Field | Description |
> | - | - |
> | `first_name` | First name of the PEP. |
> | `last_name` | Last name of the PEP. |
> | `document_number` | Identification document. |
> | `job_title` | Public job title or position. |

## Permitted values for specific fields

Use the exact values below when creating or updating users.

| Field | Permitted values |
| - | - |
| `gender` | `male`, `female`, `other` |
| `document_type` | `dni`, `company_id`, `passport`, `dni_foreigner`, `company_ruc`, `special_type` |
| `secondary_document_type` | `s_dni`, `s_company_id`, `s_passport`, `s_dni_foreigner`, `s_company_ruc`, `s_special_type` |
| `civil_status` | `single`, `married`, `divorced`, `separated`, `widowed` |
| `category` | `natural`, `business` |
| `lr_document_type` | `dni`, `company_id`, `passport`, `dni_foreigner`, `company_ruc`, `special_type` |
| `lr_gender` | `male`, `female`, `other` |
| `lr_civil_status` | `single`, `married`, `divorced`, `separated`, `widowed` |
| `expected_monthly_payments_usd` | `usd_0_to_40000`, `usd_40000_to_500000`, `usd_500000_plus` |
| `ubo_document_type` | `dni`, `company_id`, `passport`, `dni_foreigner`, `company_ruc`, `special_type` |

## Verification status notification

Whenever a user changes their `profile_verification` status, Vita Wallet sends an HTTP `POST` notification to the `url_notify_kyc` URL you provided.

| Field | Description |
| - | - |
| `business_external_id` | Custom ID assigned by the client. |
| `email` | User's email address. |
| `profile_verification` | Current verification status. |

The merchant must validate the notification by calculating the signature from the request body and headers (`Authorization`, `X-Date`, `X-Login`, `X-Trans-Key`).

```js theme={null}
hash = { business_external_id: "ext-v7", email: "example@email.com", profile_verification: "started" }
// -> "business_external_idext-v7emailexample@email.comprofile_verificationstarted"
```

Vita Business sends the notification every 10 minutes for up to 3 days, until it receives a `200` response from the merchant's server.

## Security (important)

Requests to the Users module are signed using **HMAC-SHA256**, the same algorithm used by the rest of the Vita API — but with one critical difference.

> [!WARNING]
>
> **Do not sort or concatenate the request body keys.** For the Users module, the request body **must be used exactly as a JSON string** when generating the HMAC signature.

All other aspects of the signature process remain the same (`x-login`, `x-date`, API keys, `Authorization` header format).

```javascript theme={null}
const payload = JSON.stringify({
  first_name: "John",
  category: "natural",
  document_number: "123456789",
  // ...
});
const signature = CryptoJS
  .HmacSHA256(xLogin + xDate + payload, secretKey)
  .toString(CryptoJS.enc.Hex);
```

> [!NOTE]
>
> Use the request body exactly as shown above (as a JSON string) when generating the signature. This requirement applies **only** to the Users module — it's the only part of the API that must be signed this way.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.