Skip to content

List patients

GET/v1/practices/{practiceId}/patients

Lists patients in one practice and mode. Use externalId for an exact match in the calling integration's namespace. Use externalIdentitySource with externalIdentityValue to search an explicit alias. Identity matching is case-sensitive after trimming whitespace. Other filters also apply.

PracticesAPI key authenticationVersion 2026-09-28

Request example

curl -X GET 'https://api.affinityrx.com/v1/practices/{practiceId}/patients' \
  -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": [
    {
      "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": null,
            "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>"
    }
  ],
  "hasMore": false,
  "object": "list",
  "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": 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

practiceIdstringrequired

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

Query parameters

endingBeforestring | null
Show schema
Any of · 1: string

string

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

Any of · 2: null

null

externalIdstring | null
Show schema
Any of · 1: string

string

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

Any of · 2: null

null

externalIdentitySourcestring | null
Show schema
Any of · 1: string

string

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

Any of · 2: null

null

externalIdentityValuestring | null
Show schema
Any of · 1: string

string

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

Any of · 2: null

null

genderstring | null
Show schema
Any of · 1: string

string

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

Any of · 2: null

null

lastOrderAfterstring | null
Show schema
Any of · 1: string

string

Any of · 2: null

null

lastOrderBeforestring | null
Show schema
Any of · 1: string

string

Any of · 2: null

null

limitinteger

Default: 25

Minimum: 1

Maximum: 100

programstring | null
Show schema
Any of · 1: string

string

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

Any of · 2: null

null

querystring | null
Show schema
Any of · 1: string

string

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

Any of · 2: null

null

sortstring | null
Show schema
Any of · 1: string

string

Allowed: "created", "name"

Any of · 2: null

null

startingAfterstring | null
Show schema
Any of · 1: string

string

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

Any of · 2: null

null

statesstring | null
Show schema
Any of · 1: string

string

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

Any of · 2: null

null

statusstring | null
Show schema
Any of · 1: string

string

Allowed: "active", "inactive"

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.

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

dataobject[]required
Show data fields

Array items · object

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
hasMorebooleanrequired
objectstringrequired

Allowed: "list"

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

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

Type to search…

↑↓ navigate↵ selectEsc close