/ Guides / Accounts & onboarding / Tutorial / Create an Account / Create a Personal Account

Create a Personal Account

This guide walks you through creating a personal account with Equals Money using the Onboarding API.

For complete API specifications, field definitions, and request/response schemas, refer to the API Reference documentation.

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

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:

Residential Address

Personal applications require exactly one address with addressType set to RESIDENTIAL. This should be the individual's primary residential address.

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
• estimatedPaymentVolume - Expected 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
• numberOfCardsRequired - Number of cards needed
• atmWithdrawalsRequired - Whether ATM access is needed

Example Request

curl -X POST https://api.equalsmoney.com/v2/applications \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "market": "UK",
    "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",
        "numberOfCardsRequired": "0-10",
        "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

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

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

Example Request

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.

Example Request

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

Next Steps

For information about webhook events and application status updates, see the Webhooks Documentation.

For complete API specifications, refer to the API Reference documentation.

Create a Business Account →