> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equalsmoney.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a personal account
> This guide walks you through creating a personal account with Equals using the Onboarding API.
# Create a personal account
This guide walks you through creating a **personal account** with Equals using the Onboarding API.
For complete API specifications, field definitions, and request/response schemas, refer to the [API Reference documentation](/api-reference/onboarding/create-a-new-onboarding-application).
**Looking for Business accounts?** If you're onboarding a Sole Trader, Private company, or other business entity, see the [Create a business account](/pages/accounts/tutorial/create-a-business-account) guide instead.
***
## Prerequisites
Before using the Onboarding API, ensure you have:
* A valid API key for authentication
* Information about the person you want to onboard
* Confirmation of which KYC model applies to your integration from your implementation contact
***
## Workflow overview
1. **Create Application** — Submit the individual's details
2. **Update Application** (optional) — Modify details before submission
3. **Upload Documents** (optional) — Provide supporting documentation
4. **Submit Application** — Finalise and trigger verification
**Note:** Unlike business applications, personal applications do **not** require associated people. The individual applicant's details are captured within the application itself.
***
## Understanding the onboarding process
**Why separate Create and Submit steps?**
The Onboarding API separates application creation from submission. This allows you to:
* Gradually collect customer information over multiple sessions
* Amend application details before final submission
* Validate data incrementally
* Upload supporting documents at your own pace
**Verification checks are only triggered upon submission, not when the application is created.**
***
## Step 1: Create application
**Endpoint:** `POST /v2/applications`
This endpoint creates a personal application for an individual.
### Application type and market
Set the `type` to `INDIVIDUAL` to indicate this is a personal application. Specify the `market` where the individual will operate (UK, EU, or US).
### Personal details
Provide the individual's basic information:
| Field | Required | Description | Format |
| ------------------------ | -------- | --------------------------------- | -------------------------------------------- |
| `firstName` | Yes | Individual's first name(s) | String |
| `lastName` | Yes | Individual's last name(s) | String |
| `dob` | Yes | Date of birth | YYYY-MM-DD |
| `nationalities` | Yes | Array of nationalities | ISO country codes (e.g., `["GB"]`) |
| `email` | Yes | Email address | String |
| `phoneNumber` | Yes | Phone number | International format (e.g., `+447911123456`) |
| `identityDocumentNumber` | No | National identity document number | String |
| `taxId` | No | Tax identification number | String |
**Full legal name required:** The first name(s) and last name(s) must be the applicant's full legal name, as per their identity document.
**Note:** Even if the person has a single nationality, provide it as an array with one element.
### Residential address
Personal applications require **exactly one** address with `addressType` set to `RESIDENTIAL`. This should be the individual's primary residential address.
| Field | Required | Description |
| ---------------- | -------- | ----------------------------- |
| `addressType` | Yes | Must be `RESIDENTIAL` |
| `streetName` | Yes | Street name |
| `buildingNumber` | Yes | Building/house number |
| `buildingName` | No | Building name (if applicable) |
| `postcode` | Yes | Postal code |
| `city` | Yes | City |
| `region` | No | Region/county (if applicable) |
| `countryCode` | Yes | ISO 3166-1 country code |
### Feature configuration
The `featureInformation` object determines what capabilities the account will have.
In `requestedFeatures`, specify an array containing `PAYMENTS`, `CARDS`, or both.
#### If requesting PAYMENTS:
Provide `paymentsInformation` with:
* `purposes` — Array of payment purposes
* `accountFundingSource` — Source of account funds
* `estimatedPaymentCount` — Expected number of payments per month
* `estimatedPaymentVolume` — Expected annual payment volume range
* `inboundCurrencies` / `outboundCurrencies` — Currencies used
* `receivingCountries` / `sendingCountries` — Countries involved
#### If requesting CARDS:
Provide `cardsInformation` with:
* `purposes` — Array of card usage purposes
* `estimatedAnnualSpend` — Expected annual spend range
* `atmWithdrawalsRequired` — Whether ATM access is needed
**Note:** For personal applications, omit `businessDisplayName`, `cardsAreForEmployees`, and `numberOfCardsRequired` — these are only for business accounts.
### Billing configuration (optional)
Set `configurationId` to link the account to a specific fee structure. This is an optional top-level string (maximum 36 characters) supplied by your implementation contact, it is typically an 11-digit numeric string (e.g., `12345678912`).
| Field | Required | Description |
| ----------------- | -------- | --------------------------------------------------------------------------------------------- |
| `configurationId` | No | Billing configuration ID. Links the account to a specific fee structure (e.g., `12345678912`) |
**When to include:** Only provide `configurationId` if your implementation contact has given you one. If omitted, the default billing configuration for your product is applied.
### Example request
```bash theme={null}
curl -X POST https://api.equalsmoney.com/v2/applications \
-H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"configurationId": "12345678912",
"market": "UK",
"type": "INDIVIDUAL",
"firstName": "John",
"lastName": "Smith",
"dob": "1990-01-15",
"nationalities": ["GB"],
"email": "john.smith@example.com",
"identityDocumentNumber": "AB123456C",
"phoneNumber": "+447911123456",
"taxId": "GB123456789",
"featureInformation": {
"requestedFeatures": ["PAYMENTS", "CARDS"],
"cardsInformation": {
"purposes": ["TRAVEL_EXPENSES_DOMESTIC"],
"estimatedAnnualSpend": "10001-50000",
"atmWithdrawalsRequired": true
},
"paymentsInformation": {
"purposes": ["RECEIVING-PAYMENTS-FROM-CUSTOMERS"],
"estimatedPaymentCount": "20-50",
"estimatedPaymentVolume": "10001-50000",
"inboundCurrencies": ["GBP"],
"outboundCurrencies": ["GBP"],
"receivingCountries": ["GB"],
"sendingCountries": ["GB"]
}
},
"addresses": [
{
"addressType": "RESIDENTIAL",
"streetName": "Main Street",
"buildingNumber": "123",
"postcode": "SW1A 1AA",
"city": "London",
"countryCode": "GB"
}
]
}'
```
**Response:** Returns the created application with an `id` and `status: 'DRAFT'`. Save the application ID for subsequent operations.
***
## Step 2: Update application (optional)
**Endpoint:** `PATCH /v2/applications/:applicationId`
You can update an application before submitting it. This is useful for gradually collecting information or correcting errors.
**Validation rules:**
* You cannot change the application type
* Addresses must contain exactly one RESIDENTIAL address
* You cannot add business-specific fields to a personal application
### Example request
```bash theme={null}
curl -X PATCH https://api.equalsmoney.com/v2/applications/{applicationId} \
-H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumber": "+447911999888",
"featureInformation": {
"requestedFeatures": ["PAYMENTS"],
"paymentsInformation": {
"purposes": ["RECEIVING-PAYMENTS-FROM-CUSTOMERS"],
"estimatedPaymentCount": "50-100",
"estimatedPaymentVolume": "50001-100000",
"inboundCurrencies": ["GBP"],
"outboundCurrencies": ["GBP"],
"receivingCountries": ["GB"],
"sendingCountries": ["GB"]
}
}
}'
```
***
## Step 3: Upload documents (optional)
**Endpoint:** `POST /v2/applications/:applicationId/documents`
You can upload documents to support the verification process.
### Document requirements by KYC model
| KYC model | Document upload requirements |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Managed by Equals** | Document upload via API is **optional**. A portal link will be generated for your customer to complete a guided ID verification journey. |
| **Hybrid** | Upload documents via API to support the verification process. This should include a Proof of Identity and Proof of Address, unless otherwise specified. |
| **Delegated** | Upload certified identity documents via API. |
**Note:** Additional information may be requested by the `KycInformationRequested` webhook after application submission.
### Document upload methods
1. **API Upload** (covered in this guide)
2. **Customer Portal** *(coming soon)* — End users receive a portal link with guided upload
3. **Internal Portal** *(coming soon)* — For your team to upload on behalf of customers
**Webhooks:** Document-related events always trigger webhooks regardless of upload method.
### Example request
```bash theme={null}
curl -X POST https://api.equalsmoney.com/v2/applications/{applicationId}/documents \
-H "Authorization: ApiKey YOUR_API_KEY" \
-F "purpose=PROOF_OF_IDENTITY" \
-F "file=@passport.pdf"
```
**Accepted purposes:** `PROOF_OF_IDENTITY`, `PROOF_OF_ADDRESS`, `OTHER`
**File requirements:** Media and document file types accepted, maximum 10MB.
***
## Step 4: Submit application
**Endpoint:** `POST /v2/applications/:applicationId/submit`
This finalises the application and submits it for review. Once submitted, the application status changes to `'SUBMITTED'` and cannot be modified.
**Important:** Verification checks are triggered at this point. For the Managed by Equals KYC model, this is when Guided ID verification is initiated and your customer will receive instructions to complete their verification journey. This can either be sent via a webhook or an email direct to your customer, for more details please refer to the [Webhooks documentation](/pages/webhooks/how-it-works).
### Example request
```bash theme={null}
curl -X POST https://api.equalsmoney.com/v2/applications/{applicationId}/submit \
-H "Authorization: ApiKey YOUR_API_KEY"
```
**Response:** Returns the application with `status: 'SUBMITTED'`.
***
## Validation rules and common errors
### Address validation
Personal applications must have exactly one address with `addressType: 'RESIDENTIAL'`.
**Errors:**
* `"Personal application must have exactly one address"`
* `"Personal application address must be of type RESIDENTIAL"`
### Type validation
You cannot add business-specific fields to a personal application.
**Error:** `"Cannot update personal application with business-specific fields: ..."`
### Market validation
The market must be valid for your product.
**Error:** `"The provided market is not valid for this product."`
### Authentication errors
**Error:** `401 Unauthorized`
* Verify your Authorization header uses the format: `Authorization: ApiKey YOUR_API_KEY`
* Check that your API key is valid and not expired
***
## Best practices
1. **Verify data**: Use GET endpoints to retrieve and verify application data before submission
2. **Handle errors**: Check validation error responses for specific field issues
3. **Test with DRAFT status**: Applications start with `status: 'DRAFT'` — use this to test your integration
4. **Understand your KYC model**: Know which verification model applies to set correct expectations
5. **Reference the API spec**: For complete field specifications, refer to the [API Reference documentation](/api-reference/onboarding/create-a-new-onboarding-application)
***
## Next steps
After submitting your application, you'll receive webhook notifications as it progresses through review. See [Onboarding webhooks](/pages/accounts/tutorial/onboarding-webhooks) to learn which events to expect and in what order.
For complete API specifications, refer to the [API Reference documentation](/api-reference/onboarding/create-a-new-onboarding-application).