Sign in

v1

latestOpenAPI 3.1.0© Modulr Finance2026-08-04207430590.4 KB
Customers

Create a new customer

This endpoint allows you to create a new customer. Creating a customer is a complex process with several dependencies, e.g: Directors, type of customer, legal specifications. For further information, please visit 'Creating a customer and account' entry on our API documentation

post/customers

Request body

externalReferencestring

External Reference can only have alphanumeric characters plus underscore, hyphen and space up to 50 characters long

namestring

AlphaNumeric characters plus [ _ ' @ , & £ $ € ¥ = # % ‘ ’ : ; \ / < > « » ! ‘ “ ” . ? - *{ } + % ( )]. Mandatory for all types except 'INDIVIDUAL and PCM_INDIVIDUAL'

companyRegNumberstring

Company registration number. Mandatory for 'LLC' and 'PLC'

industryCodestring

Mandatory for all types except 'INDIVIDUAL', 'PCM_INDIVIDUAL' and 'PCM_BUSINESS'. In-house KYC partners -> Refer to Modulr Industry Code list. Outsourced KYC partners -> custom codes allowed.

tcsVersioninteger

Terms and conditions version. Mandatory for all types except 'PCM_INDIVIDUAL' and 'PCM_BUSINESS'

typestring required

Type of the customer, can be one of:

  1. LLC -> limited company
  2. PLC -> publicly listed company
  3. SOLETRADER -> sole trader
  4. OPARTNRSHP -> ordinary partnership
  5. LPARTNRSHP -> limited partnership
  6. LLP -> limited liability partnership
  7. CHARITY -> charity
  8. INDIVIDUAL -> individual consumer
  9. PCM_INDIVIDUAL -> partner clearing model individual consumer
  10. PCM_BUSINESS -> partner clearing model business consumer
  11. TRUST -> trust customer
  12. PREQUALIFIED -> only for use by customers who have been pre-authorised by Modulr
expectedMonthlySpendinteger

Mandatory for all types except 'PCM_INDIVIDUAL' and 'PCM_BUSINESS'

legalEntity'GB' | 'NL' | 'IE'

Legal entity of the customer

provisionalCustomerIdstring

Reference to provisional customer in onboarding flow

contractCounterparty'MFBV' | 'MFSL' | 'MUS'

Business unit the customer contracts with

Example request

{
  "associates": [
    {
      "documentInfo": [
        {
          "uploadedDate": "2017-01-28T01:01:01+0000"
        }
      ]
    }
  ],
  "documentInfo": [
    {
      "uploadedDate": "2017-01-28T01:01:01+0000"
    }
  ],
  "accountancy": {
    "amlPolicy": {
      "uploadedDate": "2017-01-28T01:01:01+0000"
    }
  },
  "travel": {
    "travelBodyDoc": {
      "uploadedDate": "2017-01-28T01:01:01+0000"
    }
  }
}

Response

Created

idstring required

Unique identifier for a Customer. Begins with 'C'

namestring required

Customer's company name - must be unique across the Modulr platform.

typestring required

Type of the customer, can be one of:

  1. LLC -> limited company
  2. PLC -> publicly listed company
  3. SOLETRADER -> sole trader
  4. OPARTNRSHP -> ordinary partnership
  5. LPARTNRSHP -> limited partnership
  6. LLP -> limited liability partnership
  7. CHARITY -> charity
  8. INDIVIDUAL -> individual consumer
  9. PCM_INDIVIDUAL -> partner clearing model individual consumer
  10. PCM_BUSINESS -> partner clearing model business consumer
status'ACTIVE' | 'CLOSED' | 'BLOCKED' required

Status of the Customer. Customers must be 'Active' for Accounts to be created for them.

verificationStatusstring required

How the identity of the Customer has been verified. Can be:

  1. UNVERIFIED -> no verification checks have been completed
  2. VERIFIED -> verification checks completed satisfactorily
  3. EXVERIFIED -> verification completed externally
  4. REFERRED -> verification is pending manual review
  5. DECLINED -> verification is complete with a negative result
  6. REVIEWED -> verification check has been reviewed
companyRegNumberstring

The company registration / incorporation number of the company. Only applicable for companies registered with Companies House

expectedMonthlySpendinteger

Indication of the monthly spend of the customer.

partnerIdstring

The owning partner identifier

industryCodestring
tcsVersioninteger

Version of the Modulr Account Terms and Conditions the Customer has agreed to.

externalReferencestring
createdDatestring date-time required

Datetime when the customer was created.Format is 'yyyy-MM-dd'T'HH:mm:ssZ' where Z is UTC offset. e.g 2017-01-28T01:01:01+0000

legalEntity'GB' | 'NL' | 'IE'

Legal entity of the customer

complianceSectorstring
generateStatementsboolean

True if the customer is configured to generate statements

Example response

{
  "id": "C00000001",
  "associates": [
    {
      "documentInfo": [
        {
          "uploadedDate": "2017-01-28T01:01:01+0000"
        }
      ]
    }
  ],
  "documentInfo": [
    {
      "uploadedDate": "2017-01-28T01:01:01+0000"
    }
  ],
  "createdDate": "2017-01-28T01:01:01+0000",
  "delegate": {
    "id": "D0000001",
    "roleId": "R02002M5",
    "partner": "R0000001",
    "created": "2017-01-28T01:01:01+0000",
    "updated": "2017-01-28T01:01:01+0000"
  },
  "complianceSector": "Agency Lite Consumer"
}