Skip to content
Komplett LogoKomplett Platform

Customers Search

Search Customers — GET /customers/v1

Section titled “Search Customers — GET /customers/v1”

Uses the same sample dataset as the other customers examples.

At least one of email or mobile is required. When both are given, a customer matching either one is included — it’s not an AND filter. customerType narrows the result set afterwards; it never widens what counts as a match on email/mobile.

Success Scenarios

Section titled “Success Scenarios”

Match by Email

Section titled “Match by Email”

Request

GET /customers/v1?email=ada.lovelace%40example.com
Authorization: ******
Ocp-Apim-Subscription-Key: <subscription_key>

Response — 200 OK

{
  "customers": [
    {
      "customerId": "11111111-1111-1111-1111-111111111111",
      "name": "Ada Lovelace",
      "email": "ada.lovelace@example.com",
      "mobile": "91234567",
      "customerType": "Person",
      "isB2B": false,
      "isPublic": true,
      "country": "NO",
      "primaryAddress": {
        "streetLine1": "Enigmavegen 1",
        "postalCode": "0001",
        "city": "Oslo",
        "country": "NO"
      }
    }
  ],
  "continuationToken": null
}

Match by Mobile

Section titled “Match by Mobile”

The mobile query value must be digits only — no +, spaces, or dashes (enforced by this API; see validation rules below). How that value is matched against the stored customer record is handled by the underlying customer data store, not by this API layer.

Request

GET /customers/v1?mobile=91234567
Authorization: ******
Ocp-Apim-Subscription-Key: <subscription_key>

Response — 200 OK

{
  "customers": [
    {
      "customerId": "11111111-1111-1111-1111-111111111111",
      "name": "Ada Lovelace",
      "email": "ada.lovelace@example.com",
      "mobile": "91234567",
      "customerType": "Person",
      "isB2B": false,
      "isPublic": true,
      "country": "NO",
      "primaryAddress": {
        "streetLine1": "Enigmavegen 1",
        "postalCode": "0001",
        "city": "Oslo",
        "country": "NO"
      }
    }
  ],
  "continuationToken": null
}

Paging Through Results

Section titled “Paging Through Results”

Request

GET /customers/v1?mobile=91234567&pageSize=1
Authorization: ******
Ocp-Apim-Subscription-Key: <subscription_key>

Response — 200 OK

{
  "customers": [
    {
      "customerId": "11111111-1111-1111-1111-111111111111",
      "name": "Ada Lovelace",
      "customerType": "Person",
      "isB2B": false,
      "isPublic": true,
      "country": "NO"
    }
  ],
  "continuationToken": "eyJwYWdlIjogMn0="
}

Repeat the same request with continuationToken=eyJwYWdlIjogMn0= added to fetch the next page. Keep following continuationToken until a response comes back with null — see Pagination for the full rules, including why an empty page doesn’t necessarily mean you’re done.

Filtered by customerType

Section titled “Filtered by customerType”

customerType=Organization is applied after the email/mobile match — it doesn’t change which customers are found, only which of the matches are returned. Searching by an organization contact’s own email with customerType=Organization returns an empty customers array, not the contact’s parent organization.

Request

GET /customers/v1?email=ada.lovelace%40example.com&customerType=Organization
Authorization: ******
Ocp-Apim-Subscription-Key: <subscription_key>

Response — 200 OK

{
  "customers": [],
  "continuationToken": null
}

Key points:

  • Ada is a Person. Filtering for Organization drops her from the results entirely — it does not redirect to the organization she buys under. Use Get Organization for Contact for that relationship instead

No Match

Section titled “No Match”

Searching for an email or mobile that isn’t on record returns 200 OK with an empty customers array, not 404.

Request

GET /customers/v1?email=nobody%40example.com
Authorization: ******
Ocp-Apim-Subscription-Key: <subscription_key>

Response — 200 OK

{
  "customers": [],
  "continuationToken": null
}

Error Scenarios

Section titled “Error Scenarios”

400 — Neither email Nor mobile Given

Section titled “400 — Neither email Nor mobile Given”
{
  "type": "<docs-base-url>/errors/validation-failed",
  "title": "Validation Failed",
  "detail": "Some fields have validation errors",
  "status": 400,
  "instance": "/customers/v1",
  "code": "ERR_VALIDATION_0001",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "errors": [
    { "fieldName": "Email", "message": "At least one of Email or Mobile must be set." }
  ]
}

400 — Malformed Email

Section titled “400 — Malformed Email”

email is present but not a valid email address.

{
  "type": "<docs-base-url>/errors/validation-failed",
  "title": "Validation Failed",
  "detail": "Some fields have validation errors",
  "status": 400,
  "instance": "/customers/v1",
  "code": "ERR_VALIDATION_0001",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "errors": [
    { "fieldName": "Email", "message": "Email must be a valid email address of at most 254 characters." }
  ]
}

400 — Mobile Contains Formatting Characters

Section titled “400 — Mobile Contains Formatting Characters”

mobile must be 5–14 digits with no +, spaces, or dashes.

Request

GET /customers/v1?mobile=%2B47+912+34+567

Response — 400 Bad Request

{
  "type": "<docs-base-url>/errors/validation-failed",
  "title": "Validation Failed",
  "detail": "Some fields have validation errors",
  "status": 400,
  "instance": "/customers/v1",
  "code": "ERR_VALIDATION_0001",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "errors": [
    {
      "fieldName": "Mobile",
      "message": "Mobile must consist of 5 to 14 digits."
    }
  ]
}

400 — Page Size Out of Range

Section titled “400 — Page Size Out of Range”

pageSize must be between 1 and 100.

GET /customers/v1?mobile=91234567&pageSize=500
{
  "type": "<docs-base-url>/errors/validation-failed",
  "title": "Validation Failed",
  "detail": "Some fields have validation errors",
  "status": 400,
  "instance": "/customers/v1",
  "code": "ERR_VALIDATION_0001",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "errors": [
    { "fieldName": "PageSize", "message": "PageSize must be between 1 and 100." }
  ]
}

401 — Unauthorized

Section titled “401 — Unauthorized”

No response body. The request is missing or has an invalid Authorization header.

403 — Forbidden (no scope)

Section titled “403 — Forbidden (no scope)”

No response body. The token is valid but does not include the customer:read scope.