Onboarding Individual Customers

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 section
Access token: Generated via POST /v1/oauth/token
Catalogue data: Familiarity with /v1/occupations, /v1/purposes, and /v1/source-of-funds endpoints

Onboarding Steps

Step	Endpoint	Description
1. Fetch Catalogue Data	GET /v1/occupations, GET /v1/purposes?type=INDIVIDUAL, GET /v1/source-of-funds?type=INDIVIDUAL	Retrieve valid IDs for occupations, purposes, and fund sources
2. Create Customer	POST /v1/customers/individual	Submit personal details, address, and financial profile
3. Upload Documents	POST /v1/customers/upload	Upload identity and address proof files
4. Attach Documents	POST /v1/customers/individual/attach	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.

{
  "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	`"[email protected]"`
`phone`	string	Phone number in E.164 format — country/area code must match `country_of_residence`	`"+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: [email protected] ✓ not [email protected] ✗

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:

{
  "basic_info": {
    "first_name": "John",
    "last_name": "Doe",
    "dob": "1990-01-15",
    "email": "[email protected]",
    "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//subdivisions	`"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:

{
  "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
`source_of_fund_id`	integer	Source of funds	GET /v1/source-of-funds?type=INDIVIDUAL
`purpose_id`	integer	Purpose of using the service	GET /v1/purposes?type=INDIVIDUAL
`monthly_volume_usd`	integer	Expected monthly transaction volume in USD (not cents)	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:

{
  "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:

{
  "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:

curl --request POST \
  --url https://sandbox.api.fin.com/v1/customers/upload \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --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:

{
  "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:

curl --request POST \
  --url https://sandbox.api.fin.com/v1/customers/individual/attach \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --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):

{
  "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 for setup.

Error Response Examples

Email validation error (not lowercase):

{
  "message": "Validation failed",
  "errors": {
    "basic_info.email": ["Email must be all lowercase"]
  }
}

RELIANCE not enabled:

{
  "message": "RELIANCE is not available for your client"
}

TIN format validation (USA):

{
  "message": "Validation failed",
  "errors": {
    "basic_info.tin": ["TIN must be in SSN format (xxx-xx-xxxx) for USA customers"]
  }
}

Missing required field:

{
  "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 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
Review Beneficiary Relationships

Common Pitfalls & Solutions

Pitfall	Solution
Email validation fails	Ensure email is all lowercase before sending: `[email protected]` ✓ not `[email protected]` ✗
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//subdivisions. Format: `US-CA`, not `CA`.
Phone format rejected	Use E.164 format with country code: `+14155552671`, not `(415) 555-2671`.
Phone country mismatch	Phone number country/area code must match `country_of_residence`. A USA resident cannot have a UK phone number.
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.

Customers

Funding & Balances

Compliance & Regulatory

Additional Information

Webhooks

Prerequisites

Onboarding Steps

Request Body Structure

Verification Type (Optional)

Basic Information (Required)

Address (Required)

Financial Profile (Required)

Metadata (Optional)

Document Upload & Attachment

Step 1: Upload Documents

Step 2: Attach Documents

Customer Status & Webhooks

Error Response Examples

What’s Next?

1. Monitor Verification Status

2. Test Edge Cases

3. Production Checklist

4. Create Beneficiaries

Common Pitfalls & Solutions

Customers

Funding & Balances

Compliance & Regulatory

Additional Information

Webhooks

​Prerequisites

​Onboarding Steps

​Request Body Structure

​Verification Type (Optional)

​Basic Information (Required)

​Address (Required)

​Financial Profile (Required)

​Metadata (Optional)

​Document Upload & Attachment

​Step 1: Upload Documents

​Step 2: Attach Documents

​Customer Status & Webhooks

​Error Response Examples

​What’s Next?

​1. Monitor Verification Status

​2. Test Edge Cases

​3. Production Checklist

​4. Create Beneficiaries

​Common Pitfalls & Solutions

Prerequisites

Onboarding Steps

Request Body Structure

Verification Type (Optional)

Basic Information (Required)

Address (Required)

Financial Profile (Required)

Metadata (Optional)

Document Upload & Attachment

Step 1: Upload Documents

Step 2: Attach Documents

Customer Status & Webhooks

Error Response Examples

What’s Next?

1. Monitor Verification Status

2. Test Edge Cases

3. Production Checklist

4. Create Beneficiaries

Common Pitfalls & Solutions