Create a new customer

post https://api-sandbox.modulrfinance.com/api-sandbox-token/customers

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

time	status	user agent
Retrieving recent requests…

Loading…

Body Params

externalReference

string

length between 0 and 50

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

name

string

length between 0 and 100

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

companyRegNumber

string

length between 0 and 40

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

registeredAddress

object

Mandatory for 'LLC', 'LLP' and 'LPARTNRSHP'

tradingAddress

object

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

industryCode

string

length between 0 and 5

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.

tcsVersion

int32

1 to 1000

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

type

string

required

Type of the customer, can be one of:

LLC -> limited company
PLC -> publicly listed company
SOLETRADER -> sole trader
OPARTNRSHP -> ordinary partnership
LPARTNRSHP -> limited partnership
LLP -> limited liability partnership
CHARITY -> charity
INDIVIDUAL -> individual consumer
PCM_INDIVIDUAL -> partner clearing model individual consumer
PCM_BUSINESS -> partner clearing model business consumer
TRUST -> trust customer
PREQUALIFIED -> only for use by customers who have been pre-authorised by Modulr

expectedMonthlySpend

int32

0 to 2147483647

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

associates

array of objects

Mandatory for all types except 'PCM_BUSINESS'

associates

documentInfo

array of objects

information on uploaded documents

documentInfo

legalEntity

string

required

Legal entity of the customer

provisionalCustomerId

string

Reference to provisional customer in onboarding flow

customerTrust

object

Trust nature for customers of type Trust. Mandatory for type Trust, not to be set for non-trust customers.

taxProfile

object

Tax profile for customers of type SOLETRADER. Optional for type SOLETRADER, not to be set for non-SOLETRADER customers.

complianceData

object

Required for customers of type PREQUALIFIED.

consumerDuty

object

Consumer Duty data of the customer

Responses

Response body

object

string

required

Unique identifier for a Customer. Begins with 'C'

name

string

required

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

brandNames

array of objects

The customers brand name(s)

brandNames

object

string

required

Unique id for the Brand Name

name

string

required

The Brand Name

type

string

required

Type of the customer, can be one of:

LLC -> limited company
PLC -> publicly listed company
SOLETRADER -> sole trader
OPARTNRSHP -> ordinary partnership
LPARTNRSHP -> limited partnership
LLP -> limited liability partnership
CHARITY -> charity
INDIVIDUAL -> individual consumer
PCM_INDIVIDUAL -> partner clearing model individual consumer
PCM_BUSINESS -> partner clearing model business consumer

LLC PLC SOLETRADER OPARTNRSHP LPARTNRSHP LLP CHARITY INDIVIDUAL PCM_INDIVIDUAL PCM_BUSINESS TRUST PREQUALIFIED

status

string

required

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

ACTIVE CLOSED BLOCKED

verificationStatus

string

required

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

UNVERIFIED -> no verification checks have been completed
VERIFIED -> verification checks completed satisfactorily
EXVERIFIED -> verification completed externally
REFERRED -> verification is pending manual review
DECLINED -> verification is complete with a negative result
REVIEWED -> verification check has been reviewed

UNVERIFIED VERIFIED EXVERIFIED REFERRED DECLINED REVIEWED MIGRATED

companyRegNumber

string

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

expectedMonthlySpend

int32

Indication of the monthly spend of the customer.

registeredAddress

object

The address of the company's registered office.

addressLine1

string

required

addressLine2

string

postTown

string

required

postCode

string

required

country

string

required

countrySubDivision

string

tradingAddress

object

The address of the company's day-to-day trading activities.

addressLine1

string

required

addressLine2

string

postTown

string

required

postCode

string

required

country

string

required

countrySubDivision

string

partnerId

string

The owning partner identifier

associates

array of objects

Array of associate objects that link to the Customer. For example, this could contain the details of the company directors for a Limited company, or or the partners for a partnership.

associates

object

string

required

Unique id for the Associate

firstName

string

required

Associate's first name(s)

middleName

string

Associate's middle name

lastName

string

required

Associate's surname

string

Associate's email address

phone

string

Associate's phone number, in international number format

applicant

boolean

Indicates which Associate originally applied for the Modulr account

ownership

int32

The Associate's percentage ownership of the Customer

type

string

required

Describes the relation between the Associate and the Customer. Can be one of

DIRECTOR PARTNER CSECRETARY SOLETRADER BENE_OWNER C_INTEREST INDIVIDUAL PCM_INDIVIDUAL SIGNATORY TRUST_SETTLOR TRUST_BENEFICIARY TRUST_TRUSTEE PREQUALIFIED

dateOfBirth

string

required

Associate's date of birth in format yyyy-MM-dd, or format yyyy-MM where day is unknown

verificationStatus

string

required

How the Associate was verified. Can be one of

UNVERIFIED VERIFIED EXVERIFIED REFERRED DECLINED REVIEWED MIGRATED

homeAddress

object

Home address of the Associate

documentInfo

array of objects

Documents gathered during Customer Due Diligence checks on an Associate.

documentInfo

object

path

string

required

fileName

string

required

uploadedDate

string

required

Valid date. Format is 'yyyy-MM-dd'T'HH:mm:ssZ' where Z is UTC offset. e.g 2017-01-28T01:01:01+0000

additionalPersonalIdentifiers

array of objects

Additional personal identifier(s)

additionalPersonalIdentifiers

object

type

string

required

The type of Additional Personal Identifier

BSN

value

string

required

Additional Personal Identifier value

complianceData

object

Optional for associates of type C_INTEREST and an EU customer legal entity. Mandatory for associates of type PREQUALIFIED. Not to be set for other associate types and/or for UK customer legal entity.

industryCode

string

tcsVersion

int32

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

documentInfo

array of objects

Array of document objects that relate to the Customer being created. Examples of Documents could be proof of a Company Director's identity or address, Articles of Association or a Partnership Agreement.

documentInfo

object

path

string

required

fileName

string

required

uploadedDate

string

required

Valid date. Format is 'yyyy-MM-dd'T'HH:mm:ssZ' where Z is UTC offset. e.g 2017-01-28T01:01:01+0000

externalReference

string

createdDate

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

delegate

object

Details of this Customer's linked Delegate

string

required

Unique reference for the Delegate.

name

string

required

Name for the Delegate

address

object

Address of the Delegate

roleId

string

required

The id of the Role assigned to the delegate

externalReference

string

External system reference for the Delegate

partner

string

Partner Bid.

status

string

required

Status of the Delegate.

created

date-time

required

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

updated

date-time

required

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

legalEntity

string

Legal entity of the customer

GB NL IE

customerTrust

object

Trust nature for customers of type trust. Mandatory for type Trust, not to be set for non-trust customers.

trustNature

string

BARE_TRUSTS INTEREST_IN_POSSESSION_TRUSTS DISCRETIONARY_TRUSTS ACCUMULATION_TRUSTS MIXED_TRUSTS SETTLOR_INTERESTED_TRUSTS NON_RESIDENT_TRUSTS OFFSHORE_TRUSTS FAMILY_LIVING_TRUST PILOT_TRUST VULNERABLE_BENEFICIARY_TRUST CHARITABLE_TRUSTS IRREVOCABLE_LIFE_INSURANCE_TRUST TESTAMENTARY_TRUSTS OTHER

taxProfile

object

Tax profile for customers of type SOLETRADER. Optional for type SOLETRADER, not to be set for non-SOLETRADER customers.

taxIdentifier

string

required

Tax identifier for customers of type SOLETRADER. Optional for type SOLETRADER, not to be set for non-SOLETRADER customers.

complianceData

object

Required for customers of type PREQUALIFIED. Not allowed for all other customer types.

typeDescription

string

riskLevel

string

LOW MEDIUM HIGH UNDETERMINED

vulnerabilityReasons

array of strings

vulnerabilityReasons

business

object

consumer

object

complianceSector

string

generateStatements

boolean

True if the customer is configured to generate statements

Language

Credentials

Header


xxxxxxxxxx
10
1
curl --request POST \
2
     --url https://api-sandbox.modulrfinance.com/api-sandbox-token/customers \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '
6
{
7
  "type": "LLC",
8
  "legalEntity": "GB"
9
}
10
'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

*/*

201Created

400Validation errors