List customers

GEThttps://<your-url>/api/v2/customers

MCP id customers.indexAlso on this path: POST Create a customer

Returns the customers the caller may read, by name A-Z.

Token scope: api:read:customers
Without it: 403 insufficient-token-scope.
Permission: customers::read
Without it: 403 insufficient-permission.
Rate cost: 1 unit, read bucket. view=detail makes it 3. Adds: each include +1 (to-many +3), q +2.
Also: If-None-Match answers 304 when nothing changed. Never cached: private, no-store. Unknown query parameters are refused, never ignored.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: My active customers, oldest relationships first

curl -G \
  'https://<your-url>/api/v2/customers' \
  --data-urlencode 'filter[status]=active' \
  --data-urlencode 'filter[account_manager_id]=me' \
  --data-urlencode 'sort=customer_since' \
  --data-urlencode 'include=customer_category,tags' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

const response = await fetch('https://<your-url>/api/v2/customers?filter[status]=active&filter[account_manager_id]=me&sort=customer_since&include=customer_category%2Ctags', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
  },
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->get('https://<your-url>/api/v2/customers?filter[status]=active&filter[account_manager_id]=me&sort=customer_since&include=customer_category%2Ctags');

import requests
response = requests.request(
    'GET',
    'https://<your-url>/api/v2/customers?filter[status]=active&filter[account_manager_id]=me&sort=customer_since&include=customer_category%2Ctags',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json'},
)

Response

The shape of the response, with sample values.

{
  "data": [
    {
      "id": 1,
      "name": "Acme Industries",
      "code": "ACM",
      "color": "#1d4ed8",
      "status": "active",
      "email": "hello@acme.test",
      "phone": "…",
      "address": "Keizersgracht 1",
      "zip": "1015 CJ",
      "city": "Amsterdam",
      "country": "NL",
      "lat": "…"
    }
  ],
  "meta": {
    "page": {
      "per_page": 1,
      "next_cursor": "…",
      "prev_cursor": "…",
      "total": 1,
      "current_page": 1,
      "last_page": 1
    },
    "warnings": [
      {
        "…": "6 fields of warnings"
      }
    ]
  },
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "next": "https://<your-url>/api/v2/work-items/1",
    "prev": "https://<your-url>/api/v2/work-items/1"
  }
}

23 more fields, listed under Response

Defaults to the summary view; view=detail carries the same fields on this resource (no field of it is detail-only) and costs three read units instead of one. Search with q= over name, code and email, filter on the five reference ids, the status, the VAT flag and the three dates, and pass trashed=with|only to see deleted customers. filter[account_manager_id]=me is the "my customers" query. There is no relationship sort: sort=customer_category.name is a 400.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

46 parameters in 7 groups

Views

viewstring

Which field set to render.

summarydefaultdetail

Pagination

per_pageinteger1 to 100

Rows per page. At most 25 when include names a to-many relation; a larger value is 400 invalid-query-parameter.

Default: 25

cursorstring

Opaque keyset cursor from a previous page's links.next. Never construct one by hand.

pageinteger1 to 1000

Opt in to page-number paging: 1-based, at most 1000. Omit it, the default, to page by opaque cursor, which is what links.next hands you. Cannot be combined with cursor. Published only on collections that count their rows on every request.

Filters

=: equals
[in]: any of a comma-separated list
[null]: true or false: whether it is empty
[gte][lte][lt]: at least, at most, less than
[ne]: not equal

filter[account_manager_id]integer=[in][null]

Responsible account manager. Accepts the literal me. Use the null operator to list customers with no account manager.