--- title: "List Customers" source_url: https://docs.rapyd.net/en/list-customers-364253.html lang: en --- # List Customers Retrieve a list of all customers. You can filter the list with query parameters. > **Note:** > > - A date range that exceeds 90 days, defined with both `starting_after` and `ending_before`, returns ERROR_QUERY_DATE_RANGE_EXCEEDS_90_DAYS. > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Customer Errors](https://docs.rapyd.net/en/customer-errors.md "Customer Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). ### Parameters ### Request Query Parameters - - ending_before - The ID of the customer created after the last customer you want to retrieve. String starting with **cus_**. Date range: 1-90 days. Default: 90 days. - - limit - The maximum number of customers to return. Range: 1-100. 10 - - starting_after - The ID of the customer created before the first customer you want to retrieve. String starting with **cus_**. Date range: 1-90 days. Default: 90 days. ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Response Parameters - - addresses - Describes the addresses associated with this customer. For details of the fields in the 'address' object, see [Create Address](https://docs.rapyd.net/en/create-address.md "Create Address"). - - birth_country - Country where the customer was born. Two-letter ISO 3166-1 ALPHA-2 code for the country. - - business_vat_id - The tax ID number of the customer. Relevant when the customer is a business. - - category - Category of payment method. One of the following: - **bank_redirect** - **bank_transfer** - **card** - **card_redirect** - **cash** - **ewallet** - **ewallet_redirect** - - coupon - The ID of a discount coupon that is assigned to this customer. The coupon must use the same currency as the customer's default payment method. - - created_at - Time of creation of this customer, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - customer - ID of the customer profile, a string starting with **cus_**. - - date_of_birth - Date of birth of the customer. Format: **DD/MM/YYYY** - - default_payment_method - The payment method that is used when the `payment` object or subscription does not specify a payment method. The value must also appear in the `payment_methods` list. The payment method is referenced by its `name` field. - - delinquent - Indicates whether there is currently a failure of an automatic payment that is part of a subscription, or an invoice that was not paid when due. - - description - A text description of the customer. - - discount - Contains information about the coupon that applies to the customer. To add a discount to a customer, see [Update Customer](https://docs.rapyd.net/en/update-customer.md "Update Customer"). - - email - Customer's email address. - - ewallet - ID of the wallet that is linked to the customer. String starting with **ewallet_**. Each wallet can be associated with only one customer. - - fields - Contains the fields that are for the specific payment method. To determine what fields are required for the payment method, see [Get Payment Method Required Fields](https://docs.rapyd.net/en/get-payment-method-required-fields.md "Get Payment Method Required Fields"). - - holder_id - A generic identifier for the account holder associated with this customer. - - id - ID of the customer profile. String starting with **cus_**. - - invoice_prefix - A custom string that is prefixed to all invoices for this customer. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - name - The name of the customer. - - nationality - The citizenship of the customer. Two-letter ISO 3166-1 ALPHA-2 code for the country. - - next_action - Indicates the next action for completing the payment. One of the following values: - **3d_verification** - The next action is 3DS authentication. Relevant only to card payments. - **pending_capture** - The next action is pending the capture of the amount. Relevant only to card payments when the amount is not zero. - **pending_confirmation** - The next action is pending the confirmation for the payment. Relevant to all payment methods excluding card payment. - **pending_offline_capture** - The next action is pending an offline capture, where the payment settles to a **closed** (**CLO**) status via the clearing process. A payment in this state can be successfully refunded, **but cannot be canceled**. Currently, relevant only to Shva Arena card payments. - **not_applicable** - The payment has completed or the next action is not relevant. - - occupation - Occupation of the customer. - - payment_methods - An object containing the following fields: - - data - A list of up to three payment methods. - - acs_check - Results of the Access Control Server (ACS) check. Possible values: - **pass** - **fail** - **unavailable** - **unchecked** Relevant to cards. - - address - Address of the customer. - - canton - Name of the canton administrative subdivision, as used in banking. - - city - City portion of the address. - - country - The two-letter ISO 3166-1 ALPHA-2 code for the country. - - created_at - Time of creation of the object, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - district - Name of the district administrative subdivision, as used in banking. - - id - ID of the `address` object. - - line_1 - Line 1 of the address, such as a building number and street name. - - line_2 - Line 2 of the address, such as a suite or apartment number, or the name of a named building. - - line_3 - Line 3 of the address. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - name - The name of a contact person or an "in care of" person at this address. For a **personal** wallet contact, alphabetic characters and spaces. - - phone_number - Phone number associated with this specific address in E.164 format. Must be unique. - - state - State or province portion of the address. - - zip - Postal code portion of the address. - - bin_details - Bank identification details. Includes the following fields: - - bin_number - BIN number of the bank. - - brand - The brand of the card. For example, **Visa**. - - country - Country of the bank that issued the card. - - issuer - Business name of the bank that issued the card. - - level - Type of card as categorized by the issuer. - - type - The type of the card: - **credit** - **debit** - **prepaid** - - category - Category of payment method. One of the following: - **bank_redirect** - **bank_transfer** - **card** - **card_redirect** - **cash** - **ewallet** - **ewallet_redirect** - - cvv_check - Verification of the card’s CVV. Valid values: - **pass** - **fail** - **unavailable** - **unchecked** - - fingerprint_token - Hash of the card number, expiration date and CVV. Relevant to cards. - - id - ID of the Payment Method object. String starting with **card_** or **other_**. - - image - A URL to the image of the icon for the type of payment method. - - last4 - Last 4 digits of the card. Relevant to card payment methods. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - name - Full name of the customer. - - next_action - Indicates the next action for completing the payment. One of the following values: - **3d_verification** - The next action is 3DS authentication. Relevant only to card payments. - **pending_capture** - The next action is pending the capture of the amount. Relevant only to card payments when the amount is not zero. - **pending_confirmation** - The next action is pending the confirmation for the payment. Relevant to all payment methods excluding card payment. - **pending_offline_capture** - The next action is pending an offline capture, where the payment settles to a **closed** (**CLO**) status via the clearing process. A payment in this state can be successfully refunded, **but cannot be canceled**. Currently, relevant only to Shva Arena card payments. - **not_applicable** - The payment has completed or the next action is not relevant. - - supporting_documentation - Reserved. - - type - Name of the payment method type. For example, **us_mastercard_card**. To get a list of payment methods for a country, use [List Payment Methods by Country](https://docs.rapyd.net/en/list-payment-methods-by-country.md "List Payment Methods by Country"). - - webhook_url - Reserved. - - has_more - Indicates whether there are more than three payment methods for this customer. - - total_count - Total number of payment methods for this customer. - - url - URL for requesting all of the payment methods for this customer. - - phone_number - Customer's primary phone number in E.164 format. The merchant is responsible for verifying that the number is correct. - - subscriptions - Describes the subscriptions associated with this customer. Array of objects. For details of the fields in the 'subscriptions' object, see [Create Subscription](https://docs.rapyd.net/en/create-subscription.md "Create Subscription"). ### Code Samples - - .NET - ```csharp using System; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string result = RapydApiRequestSample.Utilities.MakeRequest("GET", "/v1/customers?limit=2"); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ```javascript const makeRequest = require('/utilities').makeRequest; async function main() { try { const result = await makeRequest( 'GET', '/v1/customers?limit=2' ); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); try { $object = make_request('get', "/v1/customers?limit=2"); var_dump($object); } catch (Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request result = make_request(method='get', path='/v1/customers?limit=2') pprint(result) ``` - /v1/customers - List Customers - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/customers?limit=2' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "8875eb5d-d43b-461e-acba-b603e26ec134" }, "data": [ { "id": "cus_a97ac31867f1e2e9903fc2cb936241a7", "delinquent": false, "discount": null, "name": "Person Customer", "default_payment_method": "", "description": "", "email": "person.customer.162417@example.com", "phone_number": "+14155551237", "invoice_prefix": "", "addresses": [], "payment_methods": null, "subscriptions": null, "created_at": 1753881860, "metadata": { "merchant_defined": true }, "business_vat_id": "", "ewallet": "ewallet_31fb2dbbaf6519461ee4fbe1062220d3", "occupation": "", "birth_country": "", "date_of_birth": "", "nationality": "" }, { "id": "cus_f3d4d8575d30b27aa39230e76fb83a54", "delinquent": false, "discount": null, "name": "Company Customer", "default_payment_method": "", "description": "", "email": "company.customer.162417@example.com", "phone_number": "+14155551236", "invoice_prefix": "", "addresses": [], "payment_methods": { "data": [ { "id": "other_2d1a55ed70548f259f6a488fd81ed96a", "type": "pl_p24_bank", "category": "bank_redirect", "metadata": { "merchant_defined": true }, "image": "https://iconslib.rapyd.net/checkout/pl_p24_bank.png", "webhook_url": "", "supporting_documentation": "", "next_action": "not_applicable", "bic_swift": "", "account_last4": "" } ], "has_more": false, "total_count": 1, "url": "/v1/customers/cus_f3d4d8575d30b27aa39230e76fb83a54/payment_methods" }, "subscriptions": null, "created_at": 1753881859, "metadata": { "merchant_defined": true }, "business_vat_id": "", "ewallet": "ewallet_b5320c566cc4aa01fe77440ad08693f7", "occupation": "", "birth_country": "", "date_of_birth": "", "nationality": "" } ] } ``` - Bad Request - Query Date Range Exceeds 90 Days - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/customers?ending_before=cus_550dbb2aef362826a333f0cf834c3b86&starting_after=cus_e942934d553ca9c1215f4f5201f1fddd' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' ``` - ```json { "status": { "error_code": "ERROR_QUERY_DATE_RANGE_EXCEEDS_90_DAYS", "status": "ERROR", "message": "The request included temporal query parameters for defining a date range, but the date range defined via the IDs of the objects exceeds limit days. Corrective action: Create a query where the date range does not exceed limit days.", "response_code": "ERROR_QUERY_DATE_RANGE_EXCEEDS_90_DAYS", "operation_id": "8966aaef-ea90-4f92-b96c-a3df0a3e1aad" } } ``` - Bad Request - Invalid Limit Query Parameter - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/customers?limit=500' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' ``` - ```json { "status": { "error_code": "INVALID_LIMIT", "status": "ERROR", "message": "The request tried to retrieve a list of objects, but the 'limit' query parameter was not set to a valid value. The request was rejected. Corrective action: Set 'limit' to an integer between 1 and 100.", "response_code": "INVALID_LIMIT", "operation_id": "ada73d14-0ae5-43ba-9eb0-8373d6efc286" } } ```