List locations

GET/v1/practices/{practiceId}/locations

Requires locations:read on a practice key or an authorized platform key. Lists active and archived locations by name, with cursor pagination. Use status to filter. Location records are shared between Test and Live for the same practice.

Practices API key authenticationVersion 2026-09-28

Request example

curl -X GET 'https://api.affinityrx.com/v1/practices/{practiceId}/locations' \
  -H "Authorization: Bearer $AFFINITY_API_KEY" \
  -H 'Affinity-Version: 2026-09-28'

Response example

These examples show the body structure. Values can differ. Select a status code to see its response.

{
  "data": [
    {
      "id": "loc_01j2y8m6jcc9tt24af5pw9x1bc",
      "object": "location",
      "practiceId": "prac_01j2y8m6jcc9tt24af5pw9x1bc",
      "name": "<string>",
      "timezone": "<string>",
      "city": "<string>",
      "country": "<string>",
      "line1": "<string>",
      "line2": "<string>",
      "phone": "<string>",
      "postalCode": "<string>",
      "state": "<string>",
      "status": "active",
      "createdAt": "<string>",
      "updatedAt": "<string>"
    }
  ],
  "object": "list",
  "hasMore": false,
  "url": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 400,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 401,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 403,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 404,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 409,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 429,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

Implementation specification

Use these field types and limits to build your integration. Download the OpenAPI document for the complete contract.

Path parameters

practiceIdstringrequired

Pattern: ^prac_[0-7][0-9a-hjkmnp-tv-z]{25}$

Query parameters

limitinteger

Default: 25

Minimum: 1

Maximum: 100

startingAfterstring | null

Show schema

Any of · 1: string

string

Pattern: ^loc_[0-7][0-9a-hjkmnp-tv-z]{25}$

Any of · 2: null

null

endingBeforestring | null

Show schema

Any of · 1: string

string

Pattern: ^loc_[0-7][0-9a-hjkmnp-tv-z]{25}$

Any of · 2: null

null

statusstring | null

Show schema

Any of · 1: string

string

Allowed: "active", "archived"

Any of · 2: null

null

Headers

Affinity-Versionstring

Selects the HTTP API contract for this request only. When omitted, API-key requests use their service account’s stored version. Does not change the stored default.

Pin requests to 2026-09-28.

Response specifications

200Successful response

application/json

dataobject[]required

Show data fields

Array items · object

idstringrequired

Pattern: ^loc_[0-7][0-9a-hjkmnp-tv-z]{25}$

objectstringrequired

Allowed: "location"

practiceIdstringrequired

Pattern: ^prac_[0-7][0-9a-hjkmnp-tv-z]{25}$

namestringrequired

timezonestring | nullrequired

Show timezone fields

Any of · 1: string

string

Any of · 2: null

null

citystring | nullrequired

Show city fields

Any of · 1: string

string

Any of · 2: null

null

countrystringrequired

line1string | nullrequired

Show line1 fields

Any of · 1: string

string

Any of · 2: null

null

line2string | nullrequired

Show line2 fields

Any of · 1: string

string

Any of · 2: null

null

phonestring | nullrequired

Show phone fields

Any of · 1: string

string

Any of · 2: null

null

postalCodestring | nullrequired

Show postalCode fields

Any of · 1: string

string

Any of · 2: null

null

statestring | nullrequired

Show state fields

Any of · 1: string

string

Any of · 2: null

null

statusstringrequired

Allowed: "active", "archived"

createdAtstringrequired

updatedAtstringrequired

objectstringrequired

Allowed: "list"

hasMorebooleanrequired

urlstringrequired

400HTTP 400

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri

401Unauthorized

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri

403Forbidden

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri

404Not found

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri

409Conflict

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri

429Too many requests

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri