List Customers

Overview

This endpoint retrieves a paginated list of customers registered under an entity. It returns customer identifiers, contact information, business details, and creation/update timestamps.

Endpoint Details

Definition	Description
Endpoint	https://api.paas.sandbox.co.passportfintech.com/v1/customers
Method	GET
Headers	Content-Type: application/json, Authorization
Authentication	Access Token (Bearer Token)

Query Parameters

Pagination Parameters

Parameter	Description
page_params.page_size	Number of records to return per page.
page_params.page_number	Page number to retrieve.
page_params.first_request_timestamp.seconds	UTC seconds since Unix epoch (`1970-01-01T00:00:00Z`). Must be between `0001-01-01T00:00:00Z` and `9999-12-31T23:59:59Z` (inclusive).
page_params.first_request_timestamp.nanos	Nanosecond fraction (0 to 999,999,999). Must be a non-negative value and represents fractional seconds at nanosecond resolution.

Ordering Parameters

Parameter	Description
`order_params.order_key`	Field used to sort the results.
`order_params.order_direction`	Sort direction. Allowed values: `ORDER_DIRECTION_ENUM_UNSPECIFIED`, `ASC`, `DESC`.

Customer Filters

Parameter	Description
identification_number	Filters by the customer’s identification number.
customer_id	Filters by the unique customer identifier.
identification_type	Filters by the customer’s identification type (for example, `CC`, `NIT).`

Request Body

This endpoint does not require a request body.

Example Request

curl --location --request GET 'https://api.paas.sandbox.co.passportfintech.com/v1/customers' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --data ''

Response

HTTP Status Code: 200 OK.

Example of Response

{ "customers": [ { "business_name": "changing", "type": "BUSINESS", "created_at": "2025-10-09T10:40:27.446Z", "updated_at": "2025-10-09T17:19:27.951Z", "email": "eAqpUh6u@example.com", "status": "ACTIVE", "identification_number": "903978023", "merchant_category_code": "0412", "mobile_phone_number": "573956158117", "address": { "line_3": "Calle 20 675", "city": "Cartagena", "line_1": "Diagonal 46 1104", "country": "CO", "post_code": "101010", "state": "Bolivar", "line_2": "Carrera 18 2111" }, "identification_type": "NIT", "id": "db7e89e7-59d8-4ab1-b675-a2ae52c3339e" } ], "pagination_info": { "first_request_timestamp": "2025-10-09T17:35:17.864Z", "current_page": 1, "total_pages": 1, "total_elements": 1 } }

Common Errors and Handling

HTTP Status Code	Meaning	Description
400	Bad Request	Invalid request format
401	Unauthorized	Missing/expired bearer token, or token lacks `paas.core.entity_customers.list.get` scope
403	Forbidden	Caller does not have permission to list customers
404	Not Found	No customers exist for the entity
500	Server Error	Unexpected error; retry or contact support

Best Practices

Use pagination_info to retrieve all customers when many exist.
Pair with Retrieve Customer (GET/customers/{id}) to access detailed information when needed.

Last updated on