Replace allergies

PUT/v1/practices/{practiceId}/patients/{patientId}/allergies

Replaces the patient's structured allergy record. Sending no_known is the explicit no-known-allergies acknowledgement; recorded requires at least one entry. Idempotency-Key is required.

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.

{
  "allergies": [
    {
      "category": "drug",
      "code": "<string>",
      "codeSystem": "rxnorm",
      "reactions": [
        {
          "code": "<string>",
          "codeSystem": "snomed-ct",
          "display": "<string>"
        }
      ],
      "severity": "mild",
      "source": "Doctor",
      "substance": "<string>",
      "type": "allergy",
      "verificationStatus": "unconfirmed"
    }
  ],
  "reviewStatus": "not_reviewed"
}

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

{
  "allergies": [
    {
      "category": "drug",
      "code": "<string>",
      "codeSystem": "rxnorm",
      "id": "alg_01j2y8m6jcc9tt24af5pw9x1bc",
      "reactions": [
        {
          "code": "<string>",
          "codeSystem": "snomed-ct",
          "display": "<string>"
        }
      ],
      "severity": "mild",
      "source": "Doctor",
      "substance": "<string>",
      "type": "allergy",
      "verificationStatus": "unconfirmed"
    }
  ],
  "reviewStatus": "not_reviewed"
}

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

Idempotency-Keystringrequired

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.

Request body specification application/json

allergiesobject[]required

Maximum items: 50

Show allergies fields

Array items · object

categorystringrequired

Allowed: "drug", "food", "insect", "latex", "mold", "pet", "pollen", "environmental", "biologic", "other"

codestring | null | null

Show code fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

codeSystemstring | null | null | null

Show codeSystem fields

Any of · 1: string | null | null

Any of · 1: string | null

Any of · 1: string

string

Allowed: "rxnorm", "snomed-ct"

Any of · 2: null

null

Any of · 2: null

null

Any of · 2: null

null

reactionsobject[]required

Maximum items: 20

Show reactions fields

Array items · object

codestring | null | null

Show code fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

codeSystemstring | null | null

Show codeSystem fields

Any of · 1: string | null

Any of · 1: string

string

Allowed: "snomed-ct"

Any of · 2: null

null

Any of · 2: null

null

displaystringrequired

severitystring | null | null | null

Show severity fields

Any of · 1: string | null | null

Any of · 1: string | null

Any of · 1: string

string

Allowed: "mild", "moderate", "severe", "unknown"

Any of · 2: null

null

Any of · 2: null

null

Any of · 2: null

null

sourcestringrequired

Allowed: "Doctor", "Patient", "Patient Agent/Guardian", "Pharmacist"

substancestringrequired

typestring | nullrequired

Show type fields

Any of · 1: string

string

Allowed: "allergy", "intolerance"

Any of · 2: null

null

verificationStatusstringrequired

Allowed: "unconfirmed", "presumed", "confirmed"

reviewStatusstringrequired

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

Response specifications

200Successful response

application/json

allergiesobject[]required

Show allergies fields

Array items · object

categorystringrequired

Allowed: "drug", "food", "insect", "latex", "mold", "pet", "pollen", "environmental", "biologic", "other"

codestring | nullrequired

Show code fields

Any of · 1: string

string

Any of · 2: null

null

codeSystemstring | nullrequired

Show codeSystem fields

Any of · 1: string

string

Allowed: "rxnorm", "snomed-ct"

Any of · 2: null

null

idanyrequired

Show id fields

All of · 1: any

any

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

reactionsobject[]required

Show reactions fields

Array items · object

codestring | nullrequired

Show code fields

Any of · 1: string

string

Any of · 2: null

null

codeSystemstring | nullrequired

Show codeSystem fields

Any of · 1: string

string

Allowed: "snomed-ct"

Any of · 2: null

null

displaystringrequired

severitystring | nullrequired

Show severity fields

Any of · 1: string

string

Allowed: "mild", "moderate", "severe", "unknown"

Any of · 2: null

null

sourcestringrequired

Allowed: "Doctor", "Patient", "Patient Agent/Guardian", "Pharmacist"

substancestringrequired

typestring | nullrequired

Show type fields

Any of · 1: string

string

Allowed: "allergy", "intolerance"

Any of · 2: null

null

verificationStatusstringrequired

Allowed: "unconfirmed", "presumed", "confirmed"

reviewStatusstringrequired

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

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