List customers

GEThttps://api.fieldtask.example/public/v1/customers

Permission: customers:read
Pagination: Cursor, up to 100 per page
Also available as: fieldtask_list_customers

Returns the customers in your organization, oldest first by default, one page at a time.

You can list every customer, or find the one customer you created with a given external_reference. Lists show current data, so a customer created or changed while you page through may or may not appear.

Archived customers are included, with "is_archived": true. Customers deleted in FieldTask aren't.

Permissions

Permission	Dependency in the permission map
`customers:read`	No dependencies

Request

Responses

Response Headers

Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

Filtering

Parameter	Returns
none	All customers, archived or not.
`external_reference`	The one customer created through your client application with that exact reference, or an empty list. It can't be combined with any other parameter, including `page_size`.

external_reference is matched exactly: it's case-sensitive and never trimmed. It only finds customers created with that reference by the same client application; references set by other integrations aren't visible to you. If the customer has since been deleted, the list is empty. See External references.

There's no search by name, email or phone number. To find a customer by those, page through the list and compare in your own code. Keep FieldTask's id once you've found it.

Pagination

page_size sets the number of customers per page, from 1 to 100. The default is 25.
ordering is created_at (oldest first, the default) or -created_at (newest first).
When page.has_more is true, request page.next_page_url with the same Authorization header. It keeps your page size and ordering. It's null on the last page.
If you build URLs yourself, pass page.next_cursor as cursor and keep every other parameter unchanged. Cursors expire within 24 hours and only work with the query and connection that produced them.

To change the ordering or page size, start again without a cursor. See Pagination.

Customer fields

Field	What it holds
`name`	The customer's name. Names aren't unique.
`email`, `phone_number`	Contact details, or `null`. An email address belongs to at most one customer in the organization.
`color`	The customer's display color, such as `#336699`, or `null`.
`primary_address`	A single address shown on the customer record, or `null`. It's separate from the customer's locations. For a customer created through the API, it's set by the customer's first location.
`is_archived`	Whether the customer is archived. Archived customers can still be used for new jobs and locations.
`revision`	Included only where FieldTask has enabled change tracking for customers.

FieldTask can also withhold a field everywhere until it's published for your environment. Only id is always present, so handle missing fields rather than failing.

external_reference isn't returned. Keep your own mapping from your reference to the FieldTask id.

Errors

Status	`code`	Meaning	What to do
400	`invalid_query`	The query string has an unknown, repeated or invalid parameter, or `external_reference` is combined with another parameter.	Send only the documented query parameters, each once. Send `external_reference` on its own.
400	`invalid_cursor`	The cursor is malformed, was changed, or belongs to a different query, connection or page size.	Use `next_page_url` or the cursor exactly as returned, with the same query. To change the query, start again without a cursor.
401	`invalid_token`	The bearer token is missing, malformed, expired, revoked or issued for a different resource (for example an MCP sign-in).	Send a current REST API token or REST OAuth access token as `Authorization: Bearer …`.
403	`api_access_not_enabled`	FieldTask hasn't enabled API access for this organization, or has disabled it.	An owner or admin requests access in Settings → API connections.
403	`insufficient_scope`	The connection lacks a permission this request needs. `error.code` is `missing_permission`.	Add the permission named in `error.message` to the connection.
404	`resource_not_found`	The record doesn't exist or isn't visible to this connection, the feature isn't available in this environment, or the URL is wrong.	Check the ID, the API origin and the path (no trailing slash).
405	`method_not_allowed`	This path doesn't accept the HTTP method, or the create isn't enabled in this environment. The `Allow` header lists the methods that are.	Use a method listed in `Allow`.
429	`rate_limit_exceeded`	Too many requests in the current minute, or too many concurrent requests, for the organization or connection.	Wait for `Retry-After` seconds, then retry.
429	`daily_quota_exceeded`	The organization or connection has used its daily allowance for this kind of request. Allowances reset at 00:00 UTC.	Wait for `Retry-After` seconds, or check remaining allowance in Settings → API connections.
503	`temporarily_unavailable`	The service couldn't complete the request.	Retry with exponential backoff. Retry creates with the same key and body.

Request

# Find the customer you created with this external_reference.
# Returns a list with zero or one customer.
curl --get "$FIELDTASK_API_ORIGIN/public/v1/customers" \
  --header "Authorization: Bearer $FIELDTASK_API_TOKEN" \
  --data-urlencode "external_reference=example-crm-customer-2041"

Response200 OK

First page with more results

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Example Property Services",
      "email": "facilities@example.com",
      "phone_number": "+15555550100",
      "color": "#336699",
      "primary_address": "100 Example Avenue, Springfield",
      "is_archived": false,
      "revision": 2,
      "created_at": "2026-11-03T13:58:20.114Z",
      "updated_at": "2026-11-03T14:01:05.732Z"
    }
  ],
  "page": {
    "has_more": true,
    "next_cursor": "EXAMPLE_OPAQUE_CURSOR",
    "next_page_url": "https://api.fieldtask.example/public/v1/customers?page_size=1&cursor=EXAMPLE_OPAQUE_CURSOR"
  }
}

Example values. IDs and times will differ in your organization.

Try itRequest builder

1. Set the base URL to your API origin with Edit. 2. Paste your token. 3. Fill in parameters or the body. 4. Press Send API Request, or copy the request below and run it yourself. Your token is only kept on this page. Sends are real requests: a create makes a real record.

Loading the request builder…

List customers

Permissions​

Request​

Responses​

Filtering​

Pagination​

Customer fields​

Errors​

Permissions

Request

Responses

Filtering

Pagination

Customer fields

Errors