/ Guides / Accounts & onboarding / Tutorial / BETA: Create an account

Create an account BETA

To create an account with Equals Money, you'll need to submit details about the business or person you're onboarding. This guide walks you through integrating with the Onboarding API so you can submit applications for both personal and business accounts. For complete API specifications, field definitions, and request/response schemas, refer to the API Reference documentation.

After you submit an onboarding request, we may need to run additional checks or request more information. For example, if you're using Equals Money to complete know-your-customer (KYC) checks, your customer may need to complete a guided verification journey (including a liveness check and document upload). Even if you are set up to do your own KYC checks and have a hybrid or delegated KYC model we may still need to request more information.

This will happen after the onboarding request is submitted and is covered in Next steps.

Overview

The Onboarding API allows you to programmatically create and manage account applications for your customers. The API supports two types of applications:

• Personal Applications : For personal accounts ( type: 'INDIVIDUAL' )
• Business Applications : For company accounts ( type: 'PRIVATE_COMPANY' , 'SOLE_TRADER' , 'PARTNERSHIP' , etc.)

Prerequisites

Before using the Onboarding API, ensure you have:

• A valid API key for authentication
• Information about the business or person that you want to onboard

Workflow Overview

The typical onboarding flow follows this order:

1. Create Associated People (business applications only)
2. Create Application
3. Update Application (optional, only allowed before submission)
4. Upload Application Documents (optional but recommended)
5. Update Associated People Documents (optional but recommended, business applications only)
6. Submit Application

Step 1: Create Associated People (Business applications only)

For business applications, you will need to create associated people (Directors, Authorised Signatory, or Ultimate beneficial owners) before creating the application.

Ultimate beneficial owners (UBOs) are defined as any person with 25% or more ownership of the business.

Authorised Signatory (Applicant) is the person who has authority to open the account on behalf of the business.

Endpoint: POST /v2/applications/associated-people

When to use: Business applications always need an Authorised Signatory (Applicant), and may need Directors and UBOs depending on the company type.

In order to process your application as quickly as possible we need the following information for each Associated person type:

Example Request:

curl -X POST [https://api.equalsmoney.com/v2/applications/associated-people](https://api.equalsmoney.com/v2/applications/associated-people) \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '[
    {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-01-01",
      "emailAddress": "[john.doe@example.com](mailto:john.doe@example.com)",
      "nationalities": ["US"],
      "taxId": "1234567890"
    },
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "dateOfBirth": "1985-05-15",
      "emailAddress": "[jane.smith@example.com](mailto:jane.smith@example.com)",
      "nationalities": ["GB"],
      "taxId": "9876543210"
    }
  ]'

Response: Returns an array of created associated people with their IDs. Save these IDs to link them to your application later.

Step 2: Create Application

Endpoint: POST /v2/applications

This is the core endpoint for creating either a personal or business application. The request body structure differs based on the application type.

Business Application

When creating a business application, you'll need to provide comprehensive information about the company. This includes basic company details, operational information, and the features you want to enable for the account.

Understanding business application types

The type field determines what kind of business entity you're onboarding. Common types include PRIVATE_COMPANY, SOLE_TRADER, PARTNERSHIP, and CHARITY. If you aren't sure which company type to use, you can use our company type mapping table to help:

Market and incorporation details

Start by specifying the market where the business will operate (UK, EU, or US) and the countryOfIncorporation using the ISO 3166-1 country code. If located in Germany, France or the United States please also provide the regionOfIncorporation to ensure we can locate the business in the relevant registry. You'll also need to provide the company's registeredName (the legal name), at least one tradingName, and the incorporationDate.

If the business is registered, it is essential to include the registrationNumber.

Business profile

Provide a clear description of the business in the businessOverview field (between 1 and 1000 characters). This should explain what the company does and how it operates.

You'll also need to classify the business using the industry object, which contains both main and sub industry codes (refer to the API document for valid industry classifications). Additionally, specify the company size using employeeCount (e.g., ONE_TO_TEN, ELEVEN_TO_FIFTY, FIFTY_ONE_TO_TWO_HUNDRED).

Contact and promotional information

Include a phoneNumber and a website for the business. If the business does not have a website please use the businessPromotionDescription to explain how the business acquires customers and promotes itself.

Addresses

Every business application needs at least one address with addressType set to either REGISTERED or TRADING , if these addresses differ they must both be provided. You can include multiple trading addresses if the business operates from different locations. Each address should include the street details, postcode, city, region (if applicable), and 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 depending on what the business needs.

If you include PAYMENTS in the requested features, you must provide paymentsInformation with details about payment purposes, estimated volumes, currencies, and countries involved in transactions.

If you include CARDS in the requested features, you must provide cardsInformation with details about card purposes, estimated annual spend, number of cards needed, ATM withdrawal requirements, and for business accounts specifically, the businessDisplayName (max 15 characters to appear on cards) and whether cardsAreForEmployees.

Linking associated people

The associatedPeople array links the individuals created in Step 1 to the business application. This array specifies their roles (Applicant, Director, or Ultimate Beneficial Owner).

Example Business Application Request:

{
  "market": "UK",
  "countryOfIncorporation": "GB",
  "type": "PRIVATE_COMPANY",
  "registeredName": "Equals Money",
  "registrationNumber": "08922461",
  "tradingNames": ["Acme Trading"],
  "businessOverview": "We provide software services to SMEs across the UK and EU.",
  "industry": {
    "main": "INFORMATION-AND-COMMUNICATION",
    "sub": "IT-AND-COMPUTER-SERVICES"
  },
  "employeeCount": "ELEVEN_TO_FIFTY",
  "incorporationDate": "2020-01-01",
  "phoneNumber": "+447911123456",
  "taxId": "GB123456789",
  "website": "[https://equalsmoney.com/](https://equalsmoney.com/)",
  "businessPromotionDescription": "We use online ads and referrals to acquire customers.",
  "featureInformation": {
    "requestedFeatures": ["PAYMENTS", "CARDS"],
    "cardsInformation": {
      "businessDisplayName": "ACME",
      "purposes": ["EMPLOYEE_INCENTIVES", "TRAVEL_EXPENSES_DOMESTIC"],
      "estimatedAnnualSpend": "100001-250000",
      "numberOfCardsRequired": "11-50",
      "cardsAreForEmployees": true,
      "atmWithdrawalsRequired": false
    },
    "paymentsInformation": {
      "purposes": ["RECEIVING-PAYMENTS-FROM-CUSTOMERS-AND-PAYING-SUPPLIERS"],
      "estimatedPaymentCount": "100-500",
      "estimatedPaymentVolume": "100001-250000",
      "inboundCurrencies": ["GBP", "EUR"],
      "outboundCurrencies": ["GBP", "EUR"],
      "receivingCountries": ["GB", "FR"],
      "sendingCountries": ["GB", "DE"]
    }
  },
  "addresses": [
    {
      "addressType": "REGISTERED",
      "streetName": "Upper Thames Street",
      "buildingNumber": "68",
      "buildingName": "Vintners Place",
      "postcode": "EC4V 3BJ",
      "city": "London",
      "region": "Greater London",
      "countryCode": "GB"
    },
    {
      "addressType": "TRADING",
      "streetName": "Tech Park Road",
      "buildingNumber": "12",
      "postcode": "SW1A 1AA",
      "city": "London",
      "countryCode": "GB"
    }
  ],
  "associatedPeople": [
    {
      "associatedPersonId": "e9293471-5eb3-4dbc-916c-dbaf9e2deefd",
      "associationType": "APPLICANT",
      "jobTitle": "Director"
    },
    {
      "associatedPersonId": "a1234567-8b90-4cde-f012-3456789abcde",
      "associationType": "DIRECTOR"
    }
  ]
}

Personal Application

When creating a personal application, you'll provide information about an individual who wants to open a personal account. The process is more straightforward than business applications as you don't need to manage associated people or company structures.

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: firstName, lastName, and dob (date of birth in YYYY-MM-DD format). You'll also need to include their nationalities as an array of ISO country codes. Even if the person has a single nationality, provide it as an array with one element.

Contact and identity information

Provide the person's email address and phoneNumber.

Residential address

Personal applications require one address with addressType set to RESIDENTIAL. This should be the individual's primary residential address, including street details, postcode, city, and ISO 3166-1 country code.

Feature configuration

Just like business applications, the featureInformation object determines what capabilities the account will have. In requestedFeatures, specify an array containing PAYMENTS, CARDS, or both.

If you include PAYMENTS in the requested features, provide paymentsInformation with details about how the individual expects to use payments, including purposes, estimated volumes, and the currencies and countries involved.

If you include CARDS in the requested features, provide cardsInformation with details about card usage. Note that for personal applications, you should omit the businessDisplayName and cardsAreForEmployees fields, as these are only relevant for business accounts.

Example Personal Application Request:

{
  "type": "INDIVIDUAL",
  "market": "UK",
  "firstName": "John",
  "lastName": "Smith",
  "dob": "1990-01-15",
  "nationalities": ["GB"],
  "email": "[john.smith@example.com](mailto: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 3: Update Application (Optional)

Endpoint: PATCH /v2/applications/:applicationId

You can update an application before submitting it. Important validation rules:

• You cannot change the application type (e.g., from business to personal)
• You cannot mix personal and business-specific fields
• For personal applications: addresses must contain exactly one RESIDENTIAL address
• For business applications: you cannot use personal-specific fields

Example Update Request:

curl -X PATCH [https://api.equalsmoney.com/v2/applications/{applicationId}](https://api.equalsmoney.com/v2/applications/{applicationId}) \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "registeredName": "Acme Ltd Updated",
    "businessOverview": "Updated overview",
    "featureInformation": {
      "requestedFeatures": ["PAYMENTS"],
      "paymentsInformation": {
        "purposes": ["RECEIVING-PAYMENTS-FROM-CUSTOMERS"],
        "estimatedPaymentCount": "50-100",
        "estimatedPaymentVolume": "50001-100000",
        "inboundCurrencies": ["GBP"],
        "outboundCurrencies": ["GBP"],
        "receivingCountries": ["GB"],
        "sendingCountries": ["GB"]
      }
    }
  }'

Step 4: Upload Application Documents (Optional but recommended)

You can upload documents for applications (both business and personal). Documents help with the verification process.

Application Documents: POST /v2/applications/:applicationId/documents

Associated Person Documents: POST /v2/applications/associated-people/:associatedPersonId/documents

Request: Multipart form data with:

• purpose - Document purpose (e.g., 'PROOF_OF_FORMATION' , 'PROOF_OF_OWNERSHIP_STRUCTURE' , 'OTHER' )
• file - The document file (accepts media and document file types, maximum file size is 10MB)

Example:

curl -X POST [https://api.equalsmoney.com/v2/applications/{applicationId}/documents](https://api.equalsmoney.com/v2/applications/{applicationId}/documents) \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -F "purpose=OTHER" \\
  -F "file=@document.pdf"

Step 5: Upload Associated People Documents (Optional but recommended, business applications only)

For business applications, you can upload documents for associated people (Directors, Applicants, or UBOs). This helps with the verification process for these individuals.

Endpoint: POST /v2/applications/associated-people/:associatedPersonId/documents

Request: Multipart form data with:

• purpose - Document purpose (e.g., 'PROOF_OF_IDENTITY' , 'PROOF_OF_ADDRESS' , 'OTHER' )
• file - The document file (accepts media and document file types, maximum file size is 10MB)

Example:

curl -X POST [https://api.equalsmoney.com/v2/applications/associated-people/{associatedPersonId}/documents](https://api.equalsmoney.com/v2/applications/associated-people/{associatedPersonId}/documents) \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -F "purpose=OTHER" \\
  -F "file=@document.pdf"

Step 6: Submit Application

Endpoint: POST /v2/applications/:applicationId/submit

This finalizes 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](https://api.equalsmoney.com/v2/applications/{applicationId}/submit) \\
  -H "Authorization: Bearer YOUR_API_KEY"

Response: Returns the application with status: 'SUBMITTED'.

Associated People Linkage

For business applications, you must link at least one person with an association type:

• APPLICANT : The authorised person applying for the account (requires jobTitle )
• DIRECTOR : A company director
• ULTIMATE_BENEFICIAL_OWNER : A UBO (requires ownershipPercentage 0-100)

Note: All UBOs with at least 25% ownership must be added to the application.

Example:

{
  "associatedPeople": [
    {
      "associatedPersonId": "e9293471-5eb3-4dbc-916c-dbaf9e2deefd",
      "associationType": "APPLICANT",
      "jobTitle": "Director"
    },
    {
      "associatedPersonId": "a1234567-8b90-4cde-f012-3456789abcde",
      "associationType": "DIRECTOR"
    },
    {
      "associatedPersonId": "b2345678-9c01-4def-0123-456789abcdef",
      "associationType": "ULTIMATE_BENEFICIAL_OWNER",
      "ownershipPercentage": 75
    }
  ]
}

Note: You can link the same person multiple times with different association types. For example, for a sole trader, the same person might be both the APPLICANT and the ULTIMATE_BENEFICIAL_OWNER.

Validation Rules and Common Errors

Market Validation

• The market must be valid for your product
• Error: "The provided market is not valid for this product."

Type Validation

• You cannot mix personal and business-specific fields
• Business applications cannot be changed to personal type
• Personal applications cannot include business fields
• Error: "Cannot update personal application with business-specific fields: ..."

Address Validation

• Personal applications : Must have exactly one address with addressType: 'RESIDENTIAL'
• Business applications : Must have at least one address with addressType: 'REGISTERED' or 'TRADING'
• Error: "Personal application must have exactly one address" or "Personal application address must be of type RESIDENTIAL"

Best Practices

1. Order matters : For business applications, create associated people before creating the application
2. Verify data : Use GET endpoints to retrieve and verify application/associated person data before submission
3. Handle errors : Check validation error responses for specific field issues
4. Upload documents : While optional, uploading supporting documents will speed up the review process
5. Test with incomplete status : Applications start with status: 'DRAFT' - use this to test your integration before submitting
6. Reference the API spec : For complete field specifications, valid enum values, and detailed schemas, refer to the API Reference documentation

Troubleshooting

Common Issues

400 Bad Request - Field Validation

• Review the error response for specific field paths and messages
• Ensure required fields are present and have valid values
• Check that field types match (arrays vs strings, etc.)

400 Bad Request - Type Mismatch

• Verify you're not mixing personal and business fields
• Ensure the application type matches the fields you're using

404 Not Found

• Verify the application ID or associated person ID exists
• Check that you're using the correct endpoint path

For complete API specifications and detailed field definitions, refer to the API Reference documentation.