List a customer's locations

GEThttps://api.fieldtask.example/public/v1/customers/{customer_id}/locations

Permissions

customer_locations:read, customers:read

Pagination

Cursor, up to 100 per page

Also available as

fieldtask_list_customer_locations

Returns one customer's service locations, oldest first by default, one page at a time.

Put the customer's ID in the path: GET /public/v1/customers/{customer_id}/locations. Locations of an archived customer are listed as usual. If the customer doesn't exist, belongs to another organization or was deleted in FieldTask, the response is 404 resource_not_found. A customer with no locations returns an empty list.

Lists show current data, so a location created or changed while you page through may or may not appear. Deleted locations aren't included.

Permissions

Permission	Dependency in the permission map
customer_locations:read	Depends on customers:read
customers:read	No dependencies

Request

Responses

200

OK

Response Headers

Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

400

Bad Request

Response Headers

Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

401

Unauthorized

Response Headers

Cache-Control

Responses must not be cached.

WWW-Authenticate
X-Request-ID

Server-generated request correlation ID.

403

Forbidden

Response Headers

Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

404

Not Found

Response Headers

Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

405

Method Not Allowed

Response Headers

Allow
Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

429

Too Many Requests

Response Headers

Cache-Control

Responses must not be cached.

Retry-After

Seconds before retry; present on 429 and an in-progress operation.

X-Request-ID

Server-generated request correlation ID.

503

Service Unavailable

Response Headers

Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

Filtering and pagination

The customer in the path is the only filter. There's no search by name or address, and locations can't be looked up by external_reference. To find a location, list the customer's locations and compare names and addresses.

• page_size sets the number of locations 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 and the customer unchanged. Cursors expire within 24 hours and only work with the query, customer and connection that produced them.

See Pagination.

Location fields

Field	What it holds
customer_id	The customer the location belongs to.
name, address	The location's label and street address.
latitude, longitude	The location's position, or both null when it isn't known. A location created without coordinates gets them once FieldTask has looked up the address, where that's enabled.
radius	The geofence radius around the location, in metres, whatever distance unit your organization displays. Older locations may have null.
is_default	Whether this is the customer's default location. At most one of a customer's locations is the default; a customer's first location becomes it.
revision	Included only where FieldTask has enabled change tracking for locations.

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.

A location's address is separate from the customer's primary_address. See The customer's primary address.

Errors

Status	code	Meaning	What to do
400	invalid_query	The query string has an unknown, repeated or invalid parameter. external_reference isn't accepted here.	Send only page_size, ordering and cursor, each once.
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 customer in the path doesn't exist, belongs to another organization or was deleted, or the URL is wrong.	Check the customer ID with GET /public/v1/customers, the API origin and the path.
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

CUSTOMER_ID=11111111-1111-4111-8111-111111111111

curl --get "$FIELDTASK_API_ORIGIN/public/v1/customers/$CUSTOMER_ID/locations" \
  --header "Authorization: Bearer $FIELDTASK_API_TOKEN" \
  --data-urlencode "page_size=100"

Response200 OK

Default location and a second site

{
  "data": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "customer_id": "11111111-1111-4111-8111-111111111111",
      "name": "Main office",
      "address": "100 Example Avenue, Springfield",
      "latitude": 39.799,
      "longitude": -89.644,
      "radius": 100,
      "is_default": true,
      "revision": 2,
      "created_at": "2026-11-03T14:01:05.732Z",
      "updated_at": "2026-11-03T14:01:09.418Z"
    },
    {
      "id": "22222222-2222-4222-8222-222222222223",
      "customer_id": "11111111-1111-4111-8111-111111111111",
      "name": "North warehouse",
      "address": "200 Example Road, Springfield",
      "latitude": null,
      "longitude": null,
      "radius": 250,
      "is_default": false,
      "revision": 1,
      "created_at": "2026-11-03T14:20:41.006Z",
      "updated_at": "2026-11-03T14:20:41.006Z"
    }
  ],
  "page": {
    "has_more": false,
    "next_cursor": null,
    "next_page_url": null
  }
}

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…