--- title: "List customers" method: GET path: "/customers" tags: ["Customers"] --- # List customers `GET /customers` Retrieve a list of customers with optional filtering parameters. Returns all customers that match the specified filters. If no filters are provided, returns all customers (paginated). ## Query parameters - `platformCustomerId` string - `customerType` 'INDIVIDUAL' | 'BUSINESS' — Whether the customer is an individual or a business entity - `createdAfter` string, date-time - `createdBefore` string, date-time - `updatedAfter` string, date-time - `updatedBefore` string, date-time - `limit` integer - `cursor` string - `region` string - `currency` string - `umaAddress` string - `isIncludingDeleted` boolean ## Response `200` Successful operation - CustomerListResponse - `data` CustomerOneOf[], required — List of customers matching the filter criteria - union - IndividualCustomer - `id` string — System-generated unique identifier - `platformCustomerId` string, required — Platform-specific customer identifier - `customerType` 'INDIVIDUAL', required — Whether the customer is an individual or a business entity - `region` string — Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction. - `currencies` string[] — List of currency codes enabled for this customer. - `email` string, email — Email address for the customer. - `phoneNumber` string — Phone number for the customer in strict E.164 format. - `umaAddress` string, required — Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer. - `createdAt` string, date-time — Creation timestamp - `updatedAt` string, date-time — Last update timestamp - `isDeleted` boolean — Whether the customer is marked as deleted - `contactVerification` ContactVerification — Email and/or phone verification state for the customer. This object is **only present when the customer's regulatory jurisdiction requires contact verification** (e.g. EU customers). For customers who have no such requirement, this object is omitted entirely — no action is needed. Each channel is reported independently: only the channels the customer's provider actually requires are present. A provider may require both email and phone, just one of them, or — when the object is absent — neither. Every channel that **is** present must reach `VERIFIED` before the customer can begin KYC. Drive each present channel with `POST /customers/{customerId}/verify-email` and/or `POST /customers/{customerId}/verify-phone` (and their `/confirm` sub-routes). - `email` 'PENDING' | 'VERIFIED' — Status of an individual contact-verification channel (email or phone). `PENDING` means verification is required but not yet completed; `VERIFIED` means the channel has been confirmed. - `phone` 'PENDING' | 'VERIFIED' — Status of an individual contact-verification channel (email or phone). `PENDING` means verification is required but not yet completed; `VERIFIED` means the channel has been confirmed. - `kycStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'HOLD' — The current KYC status of a customer. `HOLD` means the customer is placed on hold and may be required to update or provide more information. - `fullName` string — Individual's full name - `birthDate` string, date — Date of birth in ISO 8601 format (YYYY-MM-DD) - `nationality` string — Country code (ISO 3166-1 alpha-2) - `address` Address - `line1` string, required — Street address line 1 - `line2` string — Street address line 2 - `city` string — City - `state` string — State/Province/Region - `postalCode` string, required — Postal/ZIP code - `country` string, required — Country code (ISO 3166-1 alpha-2) - BusinessCustomer - `id` string — System-generated unique identifier - `platformCustomerId` string, required — Platform-specific customer identifier - `customerType` 'BUSINESS', required — Whether the customer is an individual or a business entity - `region` string — Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction. - `currencies` string[] — List of currency codes enabled for this customer. - `email` string, email — Email address for the customer. - `phoneNumber` string — Phone number for the customer in strict E.164 format. - `umaAddress` string, required — Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer. - `createdAt` string, date-time — Creation timestamp - `updatedAt` string, date-time — Last update timestamp - `isDeleted` boolean — Whether the customer is marked as deleted - `contactVerification` ContactVerification — Email and/or phone verification state for the customer. This object is **only present when the customer's regulatory jurisdiction requires contact verification** (e.g. EU customers). For customers who have no such requirement, this object is omitted entirely — no action is needed. Each channel is reported independently: only the channels the customer's provider actually requires are present. A provider may require both email and phone, just one of them, or — when the object is absent — neither. Every channel that **is** present must reach `VERIFIED` before the customer can begin KYC. Drive each present channel with `POST /customers/{customerId}/verify-email` and/or `POST /customers/{customerId}/verify-phone` (and their `/confirm` sub-routes). - `email` 'PENDING' | 'VERIFIED' — Status of an individual contact-verification channel (email or phone). `PENDING` means verification is required but not yet completed; `VERIFIED` means the channel has been confirmed. - `phone` 'PENDING' | 'VERIFIED' — Status of an individual contact-verification channel (email or phone). `PENDING` means verification is required but not yet completed; `VERIFIED` means the channel has been confirmed. - `kybStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'HOLD' — The current KYB status of a business customer. `HOLD` means the customer is placed on hold and may be required to update or provide more information. - `address` Address - `line1` string, required — Street address line 1 - `line2` string — Street address line 2 - `city` string — City - `state` string — State/Province/Region - `postalCode` string, required — Postal/ZIP code - `country` string, required — Country code (ISO 3166-1 alpha-2) - `businessInfo` object — Business information returned on a customer. `taxId` and `incorporatedOn` are required on creation but may be absent on legacy customers that pre-date the requirement, so both are optional in responses. - `legalName` string, required — Legal name of the business - `doingBusinessAs` string — Trade name or DBA name of the business, if different from the legal name - `country` string — Country of incorporation or registration (ISO 3166-1 alpha-2) - `registrationNumber` string — Business registration number - `incorporatedOn` string, date — Date of incorporation in ISO 8601 format (YYYY-MM-DD) - `entityType` 'SOLE_PROPRIETORSHIP' | 'PARTNERSHIP' | 'LLC' | 'CORPORATION' | 'S_CORPORATION' | 'NON_PROFIT' | 'OTHER' — Legal entity type of the business - `taxId` string — Tax identification number - `countriesOfOperation` string[] — List of countries where the business operates (ISO 3166-1 alpha-2) - `businessType` 'AGRICULTURE_FORESTRY_FISHING_AND_HUNTING' | 'MINING_QUARRYING_AND_OIL_AND_GAS_EXTRACTION' | 'UTILITIES' | 'CONSTRUCTION' | 'MANUFACTURING' | 'WHOLESALE_TRADE' | 'RETAIL_TRADE' | 'TRANSPORTATION_AND_WAREHOUSING' | 'INFORMATION' | 'FINANCE_AND_INSURANCE' | 'REAL_ESTATE_AND_RENTAL_AND_LEASING' | 'PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_SERVICES' | 'MANAGEMENT_OF_COMPANIES_AND_ENTERPRISES' | 'ADMINISTRATIVE_AND_SUPPORT_AND_WASTE_MANAGEMENT_AND_REMEDIATION_SERVICES' | 'EDUCATIONAL_SERVICES' | 'HEALTH_CARE_AND_SOCIAL_ASSISTANCE' | 'ARTS_ENTERTAINMENT_AND_RECREATION' | 'ACCOMMODATION_AND_FOOD_SERVICES' | 'OTHER_SERVICES' | 'PUBLIC_ADMINISTRATION' — The high-level industry category of the business - `purposeOfAccount` 'CONTRACTOR_PAYOUTS' | 'CREATOR_PAYOUTS' | 'EMPLOYEE_PAYOUTS' | 'MARKETPLACE_SELLER_PAYOUTS' | 'SUPPLIER_PAYMENTS' | 'CROSS_BORDER_B2B' | 'AR_AUTOMATION' | 'AP_AUTOMATION' | 'EMBEDDED_PAYMENTS' | 'PLATFORM_FEE_COLLECTION' | 'P2P_TRANSFERS' | 'CHARITABLE_DONATIONS' | 'OTHER' — The intended purpose for using the Grid account - `sourceOfFunds` string — The primary source of funds for the business - `expectedMonthlyTransactionCount` 'COUNT_UNDER_10' | 'COUNT_10_TO_100' | 'COUNT_100_TO_500' | 'COUNT_500_TO_1000' | 'COUNT_OVER_1000' — Expected number of transactions per month - `expectedMonthlyTransactionVolume` 'VOLUME_UNDER_10K' | 'VOLUME_10K_TO_100K' | 'VOLUME_100K_TO_1M' | 'VOLUME_1M_TO_10M' | 'VOLUME_OVER_10M' — Expected total transaction volume per month in USD equivalent - `expectedRecipientJurisdictions` string[] — List of countries where the business expects to send payments (ISO 3166-1 alpha-2) - `naicsCode` string — NAICS code describing the nature of the business (2-6 digits) - `sourceOfFundsCategories` SourceOfFundsCategory[] — Structured source-of-funds categories for the business - `sourceOfFundsOtherDescription` string — Description of the source of funds when OTHER is selected - `purposeOfAccountOtherDescription` string — Description of the account purpose when OTHER is selected - `expectedCounterpartyCountries` string[] — List of countries of the business's expected transaction counterparties (ISO 3166-1 alpha-2) - `beneficialOwners` BeneficialOwner[] - `id` string, required — Unique identifier for this beneficial owner - `customerId` string, required — The ID of the business customer this beneficial owner is associated with - `roles` BeneficialOwnerRole[], required — Roles of this person within the business - `ownershipPercentage` integer, required — Percentage of ownership in the business (0-100) - `personalInfo` BeneficialOwnerPersonalInfo, required - `firstName` string, required — First name of the individual - `middleName` string — Middle name of the individual - `lastName` string, required — Last name of the individual - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD) - `nationality` string, required — Country of nationality (ISO 3166-1 alpha-2) - `email` string, email — Email address of the individual - `phoneNumber` string — Phone number in E.164 format - `address` Address, required - … - `idType` 'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID', required — Type of tax identification - `identifier` string, required — The identification number or value - `countryOfIssuance` string — Country that issued the identification (ISO 3166-1 alpha-2) - `kycStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'HOLD', required — The current KYC status of a customer. `HOLD` means the customer is placed on hold and may be required to update or provide more information. - `createdAt` string, date-time, required — When this beneficial owner was created - `updatedAt` string, date-time — When this beneficial owner was last updated - `hasMore` boolean, required — Indicates if more results are available beyond this page - `nextCursor` string — Cursor to retrieve the next page of results (only present if hasMore is true) - `totalCount` integer — Total number of customers matching the criteria (excluding pagination) ## Other responses - `400` — Bad request - Invalid parameters - `401` — Unauthorized - `405` — Method not allowed. Returned (as JSON, not HTML) when the request uses an HTTP method that is not supported on this path. - `500` — Internal service error --- [API](https://skmtc.dev/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.dev/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stainless-api/grid-api/revisions/094458a989d2/schema)