Retrieve customers using filters

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

Either using unique references, such as customer ID, or filter parameters, such as verification status, get details of any customers found.

time	status	user agent
Retrieving recent requests…

Loading…

Query Params

array of strings

ID of Customer(s) to fetch

delegateId

array of strings

List of delegate IDs to retrieve linked customers

delegateId

string

Query parameter. ID, name or external reference of customer to search for

type

string

Type to filter, 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

verificationStatus

string

Verification Status to filter, can be one of:

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

fromCreatedDate

string

Customers created after and on this date. Format is 'yyyy-MM-dd'T'HH:mm:ssZ' where Z is UTC offset. e.g 2017-01-28T01:01:01+0000

toCreatedDate

string

Customers created before and on this date. Format is 'yyyy-MM-dd'T'HH:mm:ssZ' where Z is UTC offset. e.g 2017-01-28T01:01:01+0000

page

int32

≥ 0

Page to fetch (0 indexed)

size

int32

≤ 500

Size of Page to fetch

sortField

string

Sort by field. Sorted by createdDate if not present

sortOrder

string

Sorting order:

asc -> ascendant
desc -> descendant

externalReference

array of objects

A list of external references to filter

externalReference

name.type

string

WORD_MATCH - using word boundaries,
WORD_MATCH_ALPHANUMERIC - using word boundaries, but replaces non-alphanumeric characters in the search with a word boundary match,
PREFIX - same case prefix,
SUFFIX - same case suffix,
CONTAINS - same case contains
EXACT - same case exact

name.value

string

companyRegNumber

string

Customer registration number

legalEntity

string

Customer legal entity

addressLines

array of strings

Set of the address lines. If specified, they must be present in the address line 1 or in the address line 2.
Search results by number may include numbers with any suffix

addressLines

postCode

string

postTown

string

country

string

associateSearchCriteria.firstNameInitial

string

length between 1 and 1

Person's first name initial

associateSearchCriteria.lastName.type

string

associateSearchCriteria.lastName.value

string

associateSearchCriteria.lastNamePrefix

string

Person's prefix

associateSearchCriteria.dateOfBirth

date

Person's date of birth

associateSearchCriteria.additionalIdentifier.type

string

Type of additional personal identifier

associateSearchCriteria.additionalIdentifier.value

string

Personal identifier value

associateTypes

array of strings

List of types to filter, can be one of:

DIRECTOR -> director
PARTNER -> partner
CSECRETARY -> company secretary
SOLETRADER -> sole trader
BENE_OWNER -> beneficial owner
C_INTEREST -> controlling interest
INDIVIDUAL -> individual
PCM_INDIVIDUAL -> pcm individual
SIGNATORY -> signatory
TRUST_SETTLOR -> trust settlor
TRUST_BENEFICIARY -> trust beneficiary
TRUST_TRUSTEE -> trust trustee

associateTypes

Show Deprecated

Responses

Response body

object

content

array of objects

List of responses on the current page

content

object

string

Unique identifier for a Customer. Begins with 'C'

name

string

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

brandNames

array of objects

The customers brand name(s)

brandNames

object

string

Unique id for the Brand Name

name

string

The Brand Name

type

string

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

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

ACTIVE CLOSED BLOCKED

verificationStatus

string

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.

tradingAddress

object

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

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

Unique id for the Associate

firstName

string

Associate's first name(s)

middleName

string

Associate's middle name

lastName

string

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

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

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

verificationStatus

string

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

The type of Additional Personal Identifier

BSN

value

string

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

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

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.

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. Not allowed for all other customer types.

complianceSector

string

generateStatements

boolean

True if the customer is configured to generate statements

size

int32

Page size

totalSize

int64

Total count

page

int32

Current page number, 0 based; i.e first-page = 0, second-page = 1

totalPages

int32

Total pages

200OK

400Bad Request