Create practice

POST/v1/practices

Creates a practice owned by the platform. Set liveEnabled to true to enable Live access at creation with an approved platform and a Live request. Defaults to false. Requires practices:write. Send Idempotency-Key when you retry the same request.

Platforms 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.

{
  "address": {
    "city": "Los Angeles",
    "country": "US",
    "line1": "100 Practice Way",
    "line2": null,
    "postalCode": "90001",
    "state": "CA"
  },
  "attestations": {
    "authorizedPracticeRelationship": true,
    "authorizedPhiTransfer": true,
    "minimumNecessaryPhi": true,
    "providerDataAccuracy": true
  },
  "complianceContact": null,
  "externalId": "practice_123",
  "legalName": "Example Medical Group PLLC",
  "metadata": {},
  "name": "Example Medical Group",
  "prescribers": [
    {
      "credentials": "MD",
      "licenseStates": [
        "CA"
      ],
      "name": "Alex Morgan",
      "npi": "1234567893"
    }
  ],
  "primaryContact": {
    "email": "operations@example-practice.com",
    "name": "Jordan Lee",
    "phone": null
  },
  "supportEmail": "support@example-practice.com",
  "supportPhone": null
}

curl -X POST 'https://api.affinityrx.com/v1/practices' \
  -H "Authorization: Bearer $AFFINITY_API_KEY" \
  -H 'Affinity-Version: 2026-09-28' \
  -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.

{
  "address": {
    "city": "<string>",
    "country": "<string>",
    "line1": "<string>",
    "line2": "<string>",
    "postalCode": "<string>",
    "state": "<string>"
  },
  "contacts": {
    "compliance": {
      "email": "<string>",
      "name": "<string>",
      "phone": "<string>"
    },
    "primary": {
      "email": "<string>",
      "name": "<string>",
      "phone": "<string>"
    }
  },
  "createdAt": "<string>",
  "externalId": "<string>",
  "id": "prac_01j2y8m6jcc9tt24af5pw9x1bc",
  "legalName": "<string>",
  "livemode": false,
  "metadata": "<string>",
  "name": "<string>",
  "object": "practice",
  "prescribers": [
    {
      "credentials": "<string>",
      "licenseStates": [
        "<string>"
      ],
      "name": "<string>",
      "npi": "<string>"
    }
  ],
  "liveEnabled": false,
  "supportEmail": "<string>",
  "supportPhone": "<string>",
  "timezone": "<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.

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-Keystring

Request body specification application/json

liveEnabledboolean

Enable Live access at creation. Requires an approved platform and a Live request. Defaults to false.

addressobjectrequired

No additional properties

Show address fields

cityanyrequired

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

Show city fields

All of · 1: any

any

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

countryany | null

Show country fields

Any of · 1: any

All of · 1: any

any

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

Any of · 2: null

null

line1anyrequired

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

Show line1 fields

All of · 1: any

any

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

line2any | null | null

Show line2 fields

Any of · 1: any | null

Any of · 1: any

All of · 1: any

any

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

Any of · 2: null

null

Any of · 2: null

null

postalCodeanyrequired

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

Show postalCode fields

All of · 1: any

any

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

stateanyrequired

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

Show state fields

All of · 1: any

any

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

attestationsobjectrequired

No additional properties

Show attestations fields

authorizedPracticeRelationshipbooleanrequired

authorizedPhiTransferbooleanrequired

minimumNecessaryPhibooleanrequired

providerDataAccuracybooleanrequired

complianceContactobject | null | null

Show complianceContact fields

Any of · 1: object | null

Any of · 1: object

emailstringrequired

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

Any of · 2: null

null

Any of · 2: null

null

externalIdstring | null | null

Show externalId fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

legalNamestring | null | null

Show legalName fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

metadataobject | null

Show metadata fields

Any of · 1: object

object

Any of · 2: null

null

namestringrequired

prescribersobject[] | null

Show prescribers fields

Any of · 1: object[]

Array items · object

credentialsstring | null | null

Show credentials fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

licenseStatesstring[]required

Show licenseStates fields

Array items · string

string

namestringrequired

npistringrequired

Any of · 2: null

null

primaryContactobject | null | null

Show primaryContact fields

Any of · 1: object | null

Any of · 1: object

emailstringrequired

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

Any of · 2: null

null

Any of · 2: null

null

supportEmailstring | null | null

Show supportEmail fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

supportPhonestring | null | null

Show supportPhone 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

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

contactsobjectrequired

No additional properties

Show contacts fields

complianceobject | nullrequired

Show compliance fields

Any of · 1: object

emailstringrequired

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

Any of · 2: null

null

primaryobject | nullrequired

Show primary fields

Any of · 1: object

emailstringrequired

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

Any of · 2: null

null

createdAtstringrequired

externalIdstring | nullrequired

Show externalId fields

Any of · 1: string

string

Any of · 2: null

null

idstringrequired

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

legalNamestring | nullrequired

Show legalName fields

Any of · 1: string

string

Any of · 2: null

null

livemodebooleanrequired

metadataobjectrequired

namestringrequired

objectstringrequired

Allowed: "practice"

prescribersobject[]required

Show prescribers fields

Array items · object

credentialsstring | null | null

Show credentials fields

Any of · 1: string | null

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

licenseStatesstring[]required

Show licenseStates fields

Array items · string

string

namestringrequired

npistringrequired

liveEnabledbooleanrequired

Whether this practice currently has Live access. False for Test practices.

supportEmailstring | nullrequired

Show supportEmail fields

Any of · 1: string

string

Any of · 2: null

null

supportPhonestring | nullrequired

Show supportPhone fields

Any of · 1: string

string

Any of · 2: null

null

timezonestring | nullrequired

Show timezone fields

Any of · 1: string

string

Any of · 2: null

null

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