Search Customers

Purpose

Returns a paginated list of customers, with the core fields needed to identify a customer and reconcile it against your own records.

Filters can be combined freely: every filter sent is applied together, and a customer is returned only when it satisfies all of them. A customer can be looked up directly — by Sodtrack id, client reference, identification number or phone number — or indirectly, through the bookings it owns.

This endpoint is meant to resolve and identify customers. It does not return contact details, identity documents or addresses: request those for a single customer with Get Customer by Id

Field Definitions

🔐 Authentication

🔎 Query parameters

Every filter is optional. Sending none returns the paginated list of all customers.

Filters sent as empty or whitespace-only strings are ignored, exactly as if they had not been sent. Unrecognized query parameters are ignored.

This endpoint does not accept a request body. Any payload sent is ignored.

Example Request

Look up a customer by identification number:

GET /api/integration/customer/v2?identificationNumber=12.345.678-9
x-api-key: <your-api-key>

Confirm that a reference and an identification number belong to the same customer:

GET /api/integration/customer/v2?reference=EXT-CUSTOMER-REF-001&identificationNumber=123456789
x-api-key: <your-api-key>

Find the customer behind a booking reference:

GET /api/integration/customer/v2?bookingReference=EXT-BOOKING-REF-001
x-api-key: <your-api-key>

Paginate the full customer list:

GET /api/integration/customer/v2?pageNumber=2&pageSize=25
x-api-key: <your-api-key>

Response Example

{
  "data": [
    {
      "id": 2001,
      "reference": "EXT-CUSTOMER-REF-001",
      "name": "María",
      "lastname": "García",
      "createdDate": "2026-06-01T10:00:00.000Z"
    },
    {
      "id": 1987,
      "reference": null,
      "name": "Comercial Andes",
      "lastname": null,
      "createdDate": "2026-05-18T08:22:41.000Z"
    }
  ],
  "metadata": {
    "count": 2,
    "pageSize": 10,
    "pageNumber": 1,
    "totalPages": 1
  }
}

Response Fields

🧍 Customer — data[]

Error Responses

Filters that match no customer are not an error: the response is 200 OK with an empty data array and count of 0.

Business Rules & Constraints

Combining filters

Every filter present in the request is applied together, and only customers satisfying all of them are returned.

The filters reach the same customer through different paths: id, reference, identificationNumber and phoneNumber point at the customer directly, while bookingId and bookingReference reach it through its bookings. Combining them is a valid way to confirm that one customer matches more than one criterion.

Pointing two filters at different customers is not an error. The request succeeds and returns an empty page, because no single customer satisfies both conditions.

Identification number matching

The value sent is stripped of separator characters before matching, so punctuation formatting does not affect the result.

Spaces are not removed: send the identification number without internal spaces, or it will not match. Matching is exact after this normalization, so partial identification numbers return no results.

Phone number matching

The value sent is parsed and normalized to international format before matching, so spaces, dashes and parentheses are irrelevant.

A number without a country code is interpreted with the country of your Sodtrack operation. The normalized value matches customers whose phone is recorded with or without the leading +.

A value that cannot be parsed as a valid phone number is rejected with 400 INVALID_PHONE_NUMBER, instead of returning an empty page.

Booking-based filtering

bookingId and bookingReference select bookings first, and then return the customers those bookings belong to.

If no booking matches, or the matching bookings have no customer associated, the response is an empty page.

Ordering and pagination

• pageNumber is 1-based: the first page is 1.

• pageSize defaults to 10 and is capped at 50; a higher value is rejected with 400 Bad Request rather than silently reduced.

• count reflects every customer matching the filters, not only those on the current page.

• Customers are returned newest first.

Retrieving the full customer record

This endpoint returns only identification fields. To obtain a customer's email, phone, identification number and addresses, take the id from the result and call Get Customer

Returned data

• Timestamps are ISO 8601 in UTC.

• Optional fields that were never set are returned as null, not omitted.