Create location

POST/v1/practices/{practiceId}/locations

Requires locations:write and Idempotency-Key for API keys. Creates an active location with a unique name in this practice. Locations are shared between Test and Live. Use the returned ID for Team location access.

Practices API key authenticationVersion 2026-09-28

Request example

Replace example values with your Test data. Check the field rules below before you send a request.

{
  "city": "<string>",
  "country": "<string>",
  "line1": "<string>",
  "line2": "<string>",
  "name": "<string>",
  "phone": "<string>",
  "postalCode": "<string>",
  "state": "<string>",
  "timezone": "<string>"
}

curl -X POST 'https://api.affinityrx.com/v1/practices/{practiceId}/locations' \
  -H "Authorization: Bearer $AFFINITY_API_KEY" \
  -H 'Affinity-Version: 2026-09-28' \
  -H 'Idempotency-Key: <Idempotency-Key>' \
  -H 'Content-Type: application/json' \
  --data @request.json

Response example

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

{
  "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>"
}

{
  "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}$

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.

Idempotency-Keystringrequired

Request body specification application/json

citystring | null | null

Show city fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

countrystring | null

Show country fields

Any of · 1: string

string

Any of · 2: null

null

line1string | null | null

Show line1 fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

line2string | null | null

Show line2 fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

namestringrequired

phonestring | null | null

Show phone fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

postalCodestring | null | null

Show postalCode fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

statestring | null | null

Show state fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

timezonestring | null | null

Optional IANA timezone override. Omit to leave unchanged; null clears it. No timezone is inferred when creating a record.

Show timezone fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

Response specifications

200Successful response

application/json

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

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