--- title: "Retrieve customers using filters" method: GET path: "/customers" tags: ["Customers"] --- # Retrieve customers using filters `GET /customers` Either using unique references, such as customer ID, or filter parameters, such as verification status, get details of any customers found. ## Query parameters - `id` string[] — ID of Customer(s) to fetch - `delegateId` string[] — List of delegate IDs to retrieve linked customers - `q` string — Query parameter. ID, name or external reference of customer to search for - `type` 'LLC' | 'PLC' | 'SOLETRADER' | 'OPARTNRSHP' | 'LPARTNRSHP' | 'LLP' | 'INDIVIDUAL' | 'PCM_INDIVIDUAL' | 'PCM_BUSINESS' | 'TRUST' | 'PREQUALIFIED' — Type to filter, 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. INDIVIDUAL -> individual consumer 8. PCM_INDIVIDUAL -> partner clearing model individual consumer 9. PCM_BUSINESS -> partner clearing model business consumer - `verificationStatus` 'UNVERIFIED' | 'VERIFIED' | 'EXVERIFIED' | 'REFERRED' | 'DECLINED' | 'REVIEWED' — Verification Status to filter, can be one of: 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 - `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` integer — Page to fetch (0 indexed) - `size` integer — Size of Page to fetch - `sortField` string — Sort by field. Sorted by createdDate if not present - `sortOrder` string — Sorting order: 1. asc -> ascendant 2. desc -> descendant - `externalRef` string[] — A list of external references to filter - `externalReference` AccountStringSearchCriteria[] — A list of external references to filter - `type` 'WORD_MATCH' | 'WORD_MATCH_ALPHANUMERIC' | 'PREFIX' | 'SUFFIX' | 'CONTAINS' | 'EXACT', required — 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 - `value` string, required - `name.type` 'WORD_MATCH' | 'WORD_MATCH_ALPHANUMERIC' | 'PREFIX' | 'SUFFIX' | 'CONTAINS' | 'EXACT' — 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` 'GB' | 'NL' | 'IE' — Customer legal entity - `contractCounterparty` 'MFBV' | 'MFSL' | 'MUS' — Business unit the customer contracts with - `addressLines` string[] — 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 - `postCode` string - `postTown` string - `country` string - `associateSearchCriteria.firstNameInitial` string — Person's first name initial - `associateSearchCriteria.lastName.type` 'WORD_MATCH' | 'WORD_MATCH_ALPHANUMERIC' | 'PREFIX' | 'SUFFIX' | 'CONTAINS' | 'EXACT' — 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 - `associateSearchCriteria.lastName.value` string - `associateSearchCriteria.lastNamePrefix` string — Person's prefix - `associateSearchCriteria.dateOfBirth` string, date — Person's date of birth - `associateSearchCriteria.additionalIdentifier.type` 'BSN' — Type of additional personal identifier - `associateSearchCriteria.additionalIdentifier.value` string — Personal identifier value - `associateTypes` string[] — List of types to filter, can be one of: 1. DIRECTOR -> director 2. PARTNER -> partner 3. CSECRETARY -> company secretary 4. SOLETRADER -> sole trader 5. BENE_OWNER -> beneficial owner 6. C_INTEREST -> controlling interest 7. INDIVIDUAL -> individual 8. PCM_INDIVIDUAL -> pcm individual 9. SIGNATORY -> signatory 9. TRUST_SETTLOR -> trust settlor 9. TRUST_BENEFICIARY -> trust beneficiary 10. TRUST_TRUSTEE -> trust trustee ## Response `200` OK - AccountCustomerPageResponse - `content` AccountCustomer[] — List of responses on the current page - `id` string — Unique identifier for a Customer. Begins with 'C' - `name` string — Customer's company name - must be unique across the Modulr platform. - `brandNames` AccountBrandNameResponse[] — The customers brand name(s) - `id` string — Unique id for the Brand Name - `name` string — The Brand Name - `type` string — 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. INDIVIDUAL -> individual consumer 8. PCM_INDIVIDUAL -> partner clearing model individual consumer 9. PCM_BUSINESS -> partner clearing model business consumer - `status` 'ACTIVE' | 'CLOSED' | 'BLOCKED' — Status of the Customer. Customers must be 'Active' for Accounts to be created for them. - `verificationStatus` string — 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 - `companyRegNumber` string — The company registration / incorporation number of the company. Only applicable for companies registered with Companies House - `expectedMonthlySpend` integer — Indication of the monthly spend of the customer. - `registeredAddress` AccountAddressResponse — Address - `addressLine1` string - `addressLine2` string - `postTown` string - `postCode` string - `country` string - `countrySubDivision` string - `tradingAddress` AccountAddressResponse — Address - `addressLine1` string - `addressLine2` string - `postTown` string - `postCode` string - `country` string - `countrySubDivision` string - `partnerId` string — The owning partner identifier - `associates` AccountAssociateResponse[] — 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. - `id` string — Unique id for the Associate - `firstName` string — Associate's first name(s) - `middleName` string — Associate's middle name - `lastName` string — Associate's surname - `email` 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` integer — The Associate's percentage ownership of the Customer - `type` string — Describes the relation between the Associate and the Customer. Can be one of - `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 - `homeAddress` AccountAddressResponse — Address - `addressLine1` string - `addressLine2` string - `postTown` string - `postCode` string - `country` string - `countrySubDivision` string - `documentInfo` AccountDocumentInfo[] — Documents gathered during Customer Due Diligence checks on an Associate. - `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` AccountAdditionalPersonalIdentifierResponse[] — Additional personal identifier(s) - `type` 'BSN' — The type of Additional Personal Identifier - `value` string — Additional Personal Identifier value - `complianceData` AccountAssociateComplianceDataResponse - `relationship` string - `industryCode` string - `tcsVersion` integer — Version of the Modulr Account Terms and Conditions the Customer has agreed to. - `documentInfo` AccountDocumentInfo[] — 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. - `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` string, 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` AccountDelegateResponse — Delegate - `id` string — Unique reference for the Delegate. - `name` string — Name for the Delegate - `address` AccountAddressResponse — Address - `addressLine1` string - `addressLine2` string - `postTown` string - `postCode` string - `country` string - `countrySubDivision` string - `roleId` string — The id of the Role assigned to the delegate - `externalReference` string — External system reference for the Delegate - `partner` string — Partner Bid. - `status` string — Status of the Delegate. - `created` string, date-time — 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` string, date-time — 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` 'GB' | 'NL' | 'IE' — Legal entity of the customer - `customerTrust` AccountCustomerTrustResponse - `trustNature` '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` AccountCustomerTaxProfileResponse - `taxIdentifier` string — Tax identifier for customers of type SOLETRADER. Optional for type SOLETRADER, not to be set for non-SOLETRADER customers. - `complianceData` AccountCustomerComplianceDataResponse - `typeDescription` string - `riskLevel` 'LOW' | 'MEDIUM' | 'HIGH' | 'UNDETERMINED' - `vulnerabilityReasons` string[] - `business` AccountBusinessDataResponse - `natureOfRelationship` string - `expectedTransactionalActivity` AccountExpectedTransactionalActivityResponse - `sourceOfFunds` string - `monthlyVolume` integer - `outboundPaymentJurisdictions` string[] - `screeningResults` AccountScreeningResultsResponse - `adverseMedia` string[] - `peps` string[] - `sanctions` string[] - `sourceOfWealth` AccountSourceOfWealthResponse - `standard` string - `pep` string - `consumer` AccountConsumerDataResponse - `employment` string - `natureOfRelationship` string - `expectedTransactionalActivity` AccountExpectedTransactionalActivityResponse - `sourceOfFunds` string - `monthlyVolume` integer - `outboundPaymentJurisdictions` string[] - `screeningResults` AccountScreeningResultsResponse - `adverseMedia` string[] - `peps` string[] - `sanctions` string[] - `sourceOfWealth` AccountSourceOfWealthResponse - `standard` string - `pep` string - `complianceSector` string - `generateStatements` boolean — True if the customer is configured to generate statements - `size` integer — Page size - `totalSize` integer — Total count - `page` integer — Current page number, 0 based; i.e first-page = 0, second-page = 1 - `totalPages` integer — Total pages ## Other responses - `400` — Bad Request --- [API](https://skmtc.net/modulrfinance/apis/modulr-api.md) · [All operations](https://skmtc.net/modulrfinance/apis/modulr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/modulrfinance/modulr-api/revisions/cbd52524c8ef/schema)