Read patient

GET/v1/practices/{practiceId}/patients/{patientId}

Returns one patient in the authorized practice and mode.

Practices API key authenticationVersion 2026-09-28

Request example

curl -X GET 'https://api.affinityrx.com/v1/practices/{practiceId}/patients/{patientId}' \
  -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.

{
  "address": {
    "city": "<string>",
    "country": "<string>",
    "line1": "<string>",
    "line2": "<string>",
    "postalCode": "<string>",
    "state": "<string>"
  },
  "defaultShippingAddressId": "addr_01j2y8m6jcc9tt24af5pw9x1bc",
  "shippingAddress": {
    "city": "<string>",
    "country": "<string>",
    "line1": "<string>",
    "line2": "<string>",
    "postalCode": "<string>",
    "state": "<string>"
  },
  "allergyReviewStatus": "not_reviewed",
  "allergySummary": [
    {
      "reaction": "<string>",
      "substance": "<string>"
    }
  ],
  "createdAt": "<string>",
  "clinicalProfile": {
    "currentMedications": [
      "<string>"
    ],
    "heightInches": 0,
    "reviewedAt": "<string>",
    "weightPounds": 0
  },
  "dateOfBirth": "<string>",
  "email": "<string>",
  "externalId": "<string>",
  "externalIdentities": [
    {
      "source": "<string>",
      "value": "<string>"
    }
  ],
  "addresses": [
    {
      "id": "addr_01j2y8m6jcc9tt24af5pw9x1bc",
      "address": {
        "city": "<string>",
        "country": "<string>",
        "line1": "<string>",
        "line2": "<string>",
        "postalCode": "<string>",
        "state": "<string>"
      },
      "label": "<string>",
      "preferredShipping": false,
      "recipientName": "<string>",
      "archivedAt": "<string>"
    }
  ],
  "encounters": [
    {
      "notes": "<string>",
      "occurredAt": "<string>",
      "providerName": "<string>",
      "type": "<string>"
    }
  ],
  "gender": "f",
  "id": "pat_01j2y8m6jcc9tt24af5pw9x1bc",
  "livemode": false,
  "location": {
    "id": "loc_01j2y8m6jcc9tt24af5pw9x1bc",
    "name": "<string>",
    "state": "<string>",
    "status": "active"
  },
  "locationId": "loc_01j2y8m6jcc9tt24af5pw9x1bc",
  "metadata": "<string>",
  "medicalRecordNumber": "<string>",
  "measurements": [
    {
      "heightCentimeters": "<string>",
      "recordedAt": "<string>",
      "source": "<string>",
      "weightKilograms": "<string>"
    }
  ],
  "name": {
    "first": "<string>",
    "last": "<string>",
    "middle": "<string>",
    "preferred": "<string>"
  },
  "object": "patient",
  "phone": "<string>",
  "programs": [
    {
      "endedAt": "<string>",
      "name": "<string>",
      "startedAt": "<string>",
      "status": "active"
    }
  ],
  "practiceId": "prac_01j2y8m6jcc9tt24af5pw9x1bc",
  "status": "active",
  "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": 422,
  "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

patientIdstringrequired

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

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.

Affinity-Actor-Idstring

Required for user actors and optional for system actors. Omit both actor headers to use the authenticated service account as a system actor.

Affinity-Actor-Typestring

Use user when a person initiated the action and system for autonomous work. Omit both actor headers to default to system.

Response specifications

200Successful response

application/json

addressobject | nullrequired

Show address fields

Any of · 1: object

cityany & anyrequired

Show city fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

countryany & any | null

Show country fields

Any of · 1: any & any

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

Any of · 2: null

null

line1any & anyrequired

Show line1 fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

line2any & any | null | null

Show line2 fields

Any of · 1: any & any | null

Any of · 1: any & any

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

Any of · 2: null

null

Any of · 2: null

null

postalCodeany & anyrequired

Show postalCode fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

stateany & anyrequired

Show state fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

Any of · 2: null

null

defaultShippingAddressIdany | nullrequired

Show defaultShippingAddressId fields

Any of · 1: any

All of · 1: any

any

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

Any of · 2: null

null

shippingAddressobject | nullrequired

Show shippingAddress fields

Any of · 1: object

cityany & anyrequired

Show city fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

countryany & any | null

Show country fields

Any of · 1: any & any

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

Any of · 2: null

null

line1any & anyrequired

Show line1 fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

line2any & any | null | null

Show line2 fields

Any of · 1: any & any | null

Any of · 1: any & any

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

Any of · 2: null

null

Any of · 2: null

null

postalCodeany & anyrequired

Show postalCode fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

stateany & anyrequired

Show state fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

Any of · 2: null

null

allergyReviewStatusstringrequired

Allowed: "not_reviewed", "no_known", "recorded"

allergySummaryobject[]required

Show allergySummary fields

Array items · object

reactionstring | nullrequired

Show reaction fields

Any of · 1: string

string

Any of · 2: null

null

substancestringrequired

createdAtstringrequired

clinicalProfileobjectrequired

No additional properties

Show clinicalProfile fields

currentMedicationsstring[]required

Show currentMedications fields

Array items · string

string

heightInchesnumber | string | nullrequired

Show heightInches fields

Any of · 1: number | string

Any of · 1: number

number

Any of · 2: string

string

Allowed: "Infinity", "-Infinity", "NaN"

Any of · 2: null

null

reviewedAtstring | nullrequired

Show reviewedAt fields

Any of · 1: string

string

Any of · 2: null

null

weightPoundsnumber | string | nullrequired

Show weightPounds fields

Any of · 1: number | string

Any of · 1: number

number

Any of · 2: string

string

Allowed: "Infinity", "-Infinity", "NaN"

Any of · 2: null

null

dateOfBirthstringrequired

Pattern: ^\d{4}-\d{2}-\d{2}$

emailstring | nullrequired

Show email fields

Any of · 1: string

string

Any of · 2: null

null

externalIdany | nullrequired

Show externalId fields

Any of · 1: any

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

Any of · 2: null

null

externalIdentitiesobject[]required

Show externalIdentities fields

Array items · object

sourceanyrequired

Show source fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

valueanyrequired

Show value fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

addressesobject[]required

Show addresses fields

Array items · object

idanyrequired

Show id fields

All of · 1: any

any

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

addressobjectrequired

No additional properties

Show address fields

cityany & anyrequired

Show city fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

countryany & any | null

Show country fields

Any of · 1: any & any

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

Any of · 2: null

null

line1any & anyrequired

Show line1 fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

line2any & any | null | null

Show line2 fields

Any of · 1: any & any | null

Any of · 1: any & any

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

Any of · 2: null

null

Any of · 2: null

null

postalCodeany & anyrequired

Show postalCode fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

stateany & anyrequired

Show state fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

labelanyrequired

Show label fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

preferredShippingbooleanrequired

recipientNameany & any | nullrequired

Show recipientName fields

Any of · 1: any & any

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Pattern: ^[^\p{Cc}\u200B\u2028-\u202E\u2066-\u2069]*$

Any of · 2: null

null

archivedAtstring | nullrequired

Show archivedAt fields

Any of · 1: string

string

Any of · 2: null

null

encountersobject[]required

Show encounters fields

Array items · object

notesany & any | nullrequired

Show notes fields

Any of · 1: any & any

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

All of · 2: any

any

Maximum length: 5000

Any of · 2: null

null

occurredAtstringrequired

providerNameany | nullrequired

Show providerName fields

Any of · 1: any

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

Any of · 2: null

null

typeanyrequired

Show type fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

genderstringrequired

Allowed: "f", "m", "o", "u"

idstringrequired

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

livemodebooleanrequired

locationobjectrequired

No additional properties

Show location fields

idanyrequired

Show id fields

All of · 1: any

any

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

namestringrequired

statestring | nullrequired

Show state fields

Any of · 1: string

string

Any of · 2: null

null

statusstringrequired

Allowed: "active", "archived"

locationIdstringrequired

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

metadataobjectrequired

medicalRecordNumberstring | nullrequired

Show medicalRecordNumber fields

Any of · 1: string

string

Any of · 2: null

null

measurementsobject[]required

Show measurements fields

Array items · object

heightCentimetersany | string | nullrequired

Show heightCentimeters fields

Any of · 1: any | string

Any of · 1: any

All of · 1: any

any

Greater than: 0

Any of · 2: string

string

Allowed: "Infinity", "-Infinity", "NaN"

Any of · 2: null

null

recordedAtstringrequired

sourceanyrequired

Show source fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

weightKilogramsany | string | nullrequired

Show weightKilograms fields

Any of · 1: any | string

Any of · 1: any

All of · 1: any

any

Greater than: 0

Any of · 2: string

string

Allowed: "Infinity", "-Infinity", "NaN"

Any of · 2: null

null

nameobjectrequired

No additional properties

Show name fields

firststringrequired

laststringrequired

middlestring | nullrequired

Show middle fields

Any of · 1: string

string

Any of · 2: null

null

preferredstring | nullrequired

Show preferred fields

Any of · 1: string

string

Any of · 2: null

null

objectstringrequired

Allowed: "patient"

phonestring | nullrequired

Show phone fields

Any of · 1: string

string

Any of · 2: null

null

programsobject[]required

Show programs fields

Array items · object

endedAtstring | nullrequired

Show endedAt fields

Any of · 1: string

string

Any of · 2: null

null

nameanyrequired

Show name fields

All of · 1: any

any

Pattern: ^[^\u0000\p{Cs}]*$

startedAtstringrequired

statusstringrequired

Allowed: "active", "completed", "paused"

practiceIdstringrequired

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

statusstringrequired

Allowed: "active", "inactive"

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

422Validation error

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