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"

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.