> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fin.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Onboarding Individual Customers
> Complete guide to onboarding individual customers with personal details, financial profiles, and identity verification
Onboard individual customers to enable cross-border payments and payouts through Fin.com's platform. This guide walks you through creating individual customer profiles, uploading verification documents, and managing the compliance workflow.
## Prerequisites
Before you begin, ensure you have:
* **API credentials**: Client ID and secret from the [API Keys](https://orchestration.fin.com/api-keys) section
* **Access token**: Generated via [POST /v1/oauth/token](/api-reference/authentication/issue-a-token)
* **Catalogue data**: Familiarity with [/v1/occupations](/api-reference/catalogue/list-occupations), [/v1/purposes](/api-reference/catalogue/list-account-purposes), and [/v1/source-of-funds](/api-reference/catalogue/list-source-of-funds) endpoints
## Onboarding Steps
| Step | Endpoint | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| 1. Fetch Catalogue Data | [GET /v1/occupations](/api-reference/catalogue/list-occupations), [GET /v1/purposes?type=INDIVIDUAL](/api-reference/catalogue/list-account-purposes), [GET /v1/source-of-funds?type=INDIVIDUAL](/api-reference/catalogue/list-source-of-funds) | Retrieve valid IDs for occupations, purposes, and fund sources |
| 2. Create Customer | [POST /v1/customers/individual](/api-reference/customers/create-individual-customer) | Submit personal details, address, and financial profile |
| 3. Upload Documents | [POST /v1/customers/upload](/api-reference/customers/upload-document) | Upload identity and address proof files |
| 4. Attach Documents | [POST /v1/customers/individual/attach](/api-reference/customers/attach-documents-to-individual-customer) | Link uploaded documents to customer with TOS acceptance |
| 5. Monitor Status | Webhooks: `customer.status` | Track verification progress (INCOMPLETE → REVIEWING → APPROVED) |
***
## Request Body Structure
#### Verification Type (Optional)
> **Verification type** determines how customer identity is validated. **STANDARD** uses traditional document verification (default). **RELIANCE** leverages third-party KYC data when enabled for your client.
```json theme={null}
{
"verification_type": "STANDARD"
}
```
The `verification_type` field is optional and defaults to `STANDARD` if omitted.
**RELIANCE verification** must be explicitly enabled for your client. If not available, you'll receive a 423 error with message: `"RELIANCE is not available for your client"`
#### Basic Information (Required)
> Personal details exactly as shown on identity documents. **All fields must use only English (Latin) characters**.
**Fields:**
| Field | Type | Description | Example |
| ---------------------- | -------------- | -------------------------------------------------- | ------------------------ |
| `first_name` | string | Legal first name as shown on ID | `"John"` |
| `last_name` | string | Legal last name as shown on ID | `"Doe"` |
| `dob` | string (date) | Date of birth in YYYY-MM-DD format | `"1990-01-15"` |
| `email` | string (email) | Personal email address — **must be all lowercase** | `"john.doe@example.com"` |
| `phone` | string | Phone number in E.164 format | `"+14155552671"` |
| `country_of_residence` | string | ISO Alpha-3 country code where person resides | `"USA"` |
| `nationality` | string | ISO Alpha-3 country code of citizenship | `"USA"` |
| `tin` | string | Tax Identification Number | `"123-45-6789"` |
Email must be **all lowercase** or validation will fail. Convert to lowercase before sending: `john.doe@example.com` ✓ not `John.Doe@Example.com` ✗
**TIN Format by Country:**
* **USA**: Social Security Number in format `xxx-xx-xxxx` (e.g., `123-45-6789`)
* **Other countries**: Must use the country's official Tax Identification Number format
**Example:**
```json theme={null}
{
"basic_info": {
"first_name": "John",
"last_name": "Doe",
"dob": "1990-01-15",
"email": "john.doe@example.com",
"phone": "+14155552671",
"country_of_residence": "USA",
"nationality": "USA",
"tin": "123-45-6789"
}
}
```
#### Address (Required)
> Current residential address of the customer. This must match the address on proof of address documents.
**Fields:**
| Field | Type | Description | Example |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| `street` | string | Full street address including apartment/unit number | `"123 Main Street Apt 4B"` |
| `city` | string | City name | `"San Francisco"` |
| `state` | string | State/province code from [/v1/countries/{country_code}/subdivisions](/api-reference/catalogue/list-subdivision-codes-—-iso-3166-1-alpha-2) | `"US-CA"` |
| `postal_code` | string | Postal or ZIP code | `"94103"` |
| `country` | string | ISO Alpha-3 country code | `"USA"` |
**State Code Format**: Use subdivision codes from the catalogue API, not abbreviations. For example, use `US-CA` instead of `CA` for California, or `GB-ENG` instead of `England`.
**Example:**
```json theme={null}
{
"address": {
"street": "123 Main Street Apt 4B",
"city": "San Francisco",
"state": "US-CA",
"postal_code": "94103",
"country": "USA"
}
}
```
#### Financial Profile (Required)
> Describes occupation, transaction purpose, volume, and fund sources. Use catalogue endpoints to fetch valid IDs.
**Fields:**
| Field | Type | Description | How to Get Value |
| -------------------- | ------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `occupation_id` | integer | Customer's occupation | [GET /v1/occupations](/api-reference/catalogue/list-occupations) |
| `source_of_fund_id` | integer | Source of funds | [GET /v1/source-of-funds?type=INDIVIDUAL](/api-reference/catalogue/list-source-of-funds) |
| `purpose_id` | integer | Purpose of using the service | [GET /v1/purposes?type=INDIVIDUAL](/api-reference/catalogue/list-account-purposes) |
| `monthly_volume_usd` | integer | Expected monthly transaction volume in **USD** (not cents). Accepts `0`. | User estimate: `5000` |
When fetching catalogue data for individual customers, use the `?type=INDIVIDUAL` query parameter to get the correct options for `source_of_fund_id` and `purpose_id`.
**Example:**
```json theme={null}
{
"financial_profile": {
"occupation_id": 1,
"source_of_fund_id": 1,
"purpose_id": 1,
"monthly_volume_usd": 5000
}
}
```
In this example: `occupation_id: 1` = Software Engineer, `source_of_fund_id: 1` = Employment income, `purpose_id: 1` = Personal remittance, `monthly_volume_usd: 5000` = \$5,000 USD per month.
#### Metadata (Optional)
Custom key-value pairs for internal tracking:
```json theme={null}
{
"meta_data": {
"customer_reference": "REF-20250123-JOHN",
"internal_notes": "Premium tier customer",
"referral_code": "FRIEND2025"
}
}
```
### Document Upload & Attachment
After creating the individual customer, you must upload and attach verification documents.
#### Step 1: Upload Documents
Upload files using multipart/form-data:
```bash theme={null}
curl --request POST \
--url https://sandbox.api.fin.com/v1/customers/upload \
--header 'Authorization: Bearer ' \
--header 'Content-Type: multipart/form-data' \
--form 'customer_id=55bd6b4e-c20a-4cc8-9535-91d5557a67d9' \
--form 'file1=@/path/to/passport_front.pdf' \
--form 'file2=@/path/to/utility_bill.pdf'
```
**Allowed file types**: PDF, JPG, JPEG, PNG
**Response:**
```json theme={null}
{
"data": {
"files": [
{"file1": "/AbAcQ4hn_0652746727637.pdf"},
{"file2": "/XyZ123mn_0652746727638.pdf"}
]
}
}
```
Save these URIs—you'll use them in the attachment request.
#### Step 2: Attach Documents
Link identity and address proof documents to the customer:
```bash theme={null}
curl --request POST \
--url https://sandbox.api.fin.com/v1/customers/individual/attach \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"customer_id": "55bd6b4e-c20a-4cc8-9535-91d5557a67d9",
"proof_of_identity": {
"type": "PASSPORT",
"number": "A12345678",
"country": "USA",
"issue_date": "2020-01-15",
"expiry_date": "2030-01-15",
"files": [
{"uri": "/AbAcQ4hn_0652746727637.pdf"}
]
},
"proof_of_address": {
"type": "UTILITY_BILL",
"country": "USA",
"files": [
{"uri": "/XyZ123mn_0652746727638.pdf"}
]
},
"tos_policies_value": "e9414388-fbdf-4407-b5c2-bc39eae3645b"
}'
```
The `tos_policies_value` should be parsed from the `tos_policies_url` query parameter returned when creating the customer. Providing this value signifies that the customer was shown the terms and accepted them.
For `NATIONAL_ID` and `DRIVERS_LICENSE`, you **must** provide both `FRONT` and `BACK` images using the `side` field. For `PASSPORT`, the `side` field is optional.
**Example with National ID (requires front and back):**
```json theme={null}
{
"proof_of_identity": {
"type": "NATIONAL_ID",
"number": "A12345678",
"country": "USA",
"issue_date": "2020-01-15",
"expiry_date": "2030-01-15",
"files": [
{"side": "FRONT", "uri": "/id_front_0652746727640.pdf"},
{"side": "BACK", "uri": "/id_back_0652746727641.pdf"}
]
}
}
```
**Identity Document Types:**
| Type | Description | Side Required |
| ----------------- | ---------------- | ------------------ |
| `PASSPORT` | Passport | No (optional) |
| `NATIONAL_ID` | National ID card | Yes (FRONT + BACK) |
| `DRIVERS_LICENSE` | Driver's license | Yes (FRONT + BACK) |
**Address Proof Types:**
| Type | Description |
| ------------------- | ------------------------------------------ |
| `UTILITY_BILL` | Recent utility bill (gas, electric, water) |
| `BANK_STATEMENT` | Bank statement (within last 3 months) |
| `GOVERNMENT_LETTER` | Official government correspondence |
| `RESIDENCE_PERMIT` | Residence permit document |
| `PASSPORT` | Passport showing address |
| `NATIONAL_ID` | National ID showing address |
| `DRIVERS_LICENSE` | Driver's license showing address |
| `COMPANY_DOC` | Company document showing address |
**Proof of Address Requirements:**
* Document must show the customer's **full name** and **complete address**
* Address must match the `address` provided in the customer creation request
* Document should be issued within the **last 90 days** (for utility bills, bank statements, and government letters)
### Customer Status & Webhooks
After document submission, customers go through a verification workflow:
**Status Lifecycle:**
```
INCOMPLETE → REVIEWING → APPROVED
↓
ON_HOLD / REJECTED
```
| Status | Description |
| ------------ | ----------------------------------------------- |
| `INCOMPLETE` | Customer created but documents not yet attached |
| `REVIEWING` | Documents submitted and under compliance review |
| `APPROVED` | Verification complete, customer can transact |
| `ON_HOLD` | Additional information or documents required |
| `REJECTED` | Verification failed, see rejection reason |
**Webhook Events:**
* `customer.created` — Fired when customer is created
* `customer.status` — Fired when status changes
Subscribe to webhooks to automate your onboarding flow. See [Verifying Webhooks](/guides/webhooks/verifying-webhooks) for setup.
### Error Response Examples
**Email validation error (not lowercase):**
```json theme={null}
{
"message": "Validation failed",
"errors": {
"basic_info.email": ["Email must be all lowercase"]
}
}
```
**RELIANCE not enabled:**
```json theme={null}
{
"message": "RELIANCE is not available for your client"
}
```
**TIN format validation (USA):**
```json theme={null}
{
"message": "Validation failed",
"errors": {
"basic_info.tin": ["TIN must be in SSN format (xxx-xx-xxxx) for USA customers"]
}
}
```
**Missing required field:**
```json theme={null}
{
"message": "Validation failed",
"errors": {
"financial_profile.occupation_id": ["occupation_id is required"]
}
}
```
***
## What's Next?
You've successfully created an individual customer. Here's what to do next:
### 1. Monitor Verification Status
Listen for webhook events to track verification progress:
* Subscribe to `customer.created` and `customer.status` webhooks
* Handle status transitions: `INCOMPLETE` → `REVIEWING` → `APPROVED`
* For `ON_HOLD` statuses, respond to RFIs (Requests for Information) via email or Slack with additional documents
* See [Webhook Verification](/guides/webhooks/verifying-webhooks) for implementation details
### 2. Test Edge Cases
Validate your integration handles common errors:
* ✓ Email with uppercase characters
* ✓ TIN in wrong format for country
* ✓ Non-Latin characters in text fields
* ✓ Missing required fields
* ✓ RELIANCE verification when not enabled
* ✓ Invalid state codes
### 3. Production Checklist
Before going live, ensure you have:
* [ ] Implemented webhook handling for status updates
* [ ] Added proper error handling for all failure scenarios
* [ ] Client-side validation for email lowercase and TIN format
* [ ] Fetched and cached catalogue data (occupations, purposes, source-of-funds)
* [ ] Implemented document upload UI/flow
* [ ] Set up monitoring for failed verifications
* [ ] Tested the complete workflow end-to-end
### 4. Create Beneficiaries
Once your individual customer is approved, you can create beneficiaries for payouts:
* See [Beneficiary Account Validation](/api-reference/beneficiaries/account-info-validation)
* Review [Beneficiary Relationships](/api-reference/beneficiaries/relationships)
***
## Common Pitfalls & Solutions
| Pitfall | Solution |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Email validation fails** | Ensure email is **all lowercase** before sending: `john.doe@example.com` ✓ not `John.Doe@Example.com` ✗ |
| **RELIANCE 423 error** | RELIANCE verification must be enabled for your client. Contact support or use `STANDARD` verification type. |
| **TIN format rejected** | TIN must follow the country's official format. For USA, use SSN format `xxx-xx-xxxx`. |
| **Non-Latin character rejection** | All text fields accept only English (Latin) characters. Transliterate or romanize names (e.g., `Jose` not `Jose`). |
| **State code validation fails** | Use state codes from [/v1/countries/{country_code}/subdivisions](/api-reference/catalogue/list-subdivision-codes-—-iso-3166-1-alpha-2). Format: `US-CA`, not `CA`. |
| **Phone format rejected** | Use E.164 format with country code: `+14155552671`, not `(415) 555-2671`. |
| **Monthly volume rejected** | Provide amount in USD as integer (not cents): `5000` for \$5,000, not `500000`. |
| **Document side missing** | For `NATIONAL_ID` and `DRIVERS_LICENSE`, include `side: "FRONT"` and `side: "BACK"` in the files array. |
| **Address mismatch** | Ensure proof of address document shows the same address provided in the `address` object. |