Create Referring Physician

Adds a physician to the organisation's registry. Cases then reference the record by id.

Endpoint

POST /v2/referring-physicians

Request Body

Parameter	Type	Required	Description
first_name	string	Yes
last_name	string	Yes
clinic_id	string	Yes	The clinic this record belongs to.
middle_name	string	No
title	string	No
degree	string	No
npi	string	No
speciality	string	No	The record's primary speciality.
taxonomy_code	string	No	NUCC provider taxonomy code.
email	string	No
phone	string	No
fax	string	No
group_name	string	No
office_name	string	No
address	object	No	See Address.

Address

Parameter	Type	Required	Description
line1	string or null	No
line2	string or null	No
city	string or null	No
state	string or null	No
postal_code	string or null	No
country	string or null	No

Request

curl --location '{base_url}/v2/referring-physicians' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "first_name": "Priya",
  "last_name": "Raman",
  "clinic_id": "5831",
  "middle_name": null,
  "title": "L Knee Post-Op",
  "degree": null,
  "npi": "1740398215",
  "speciality": "PHYSICAL_THERAPY",
  "taxonomy_code": null,
  "email": "m.delgado@example.com",
  "phone": "+1-555-0143",
  "fax": null,
  "group_name": null,
  "office_name": null,
  "address": {
    "line1": "482 Willow Creek Rd",
    "line2": null,
    "city": "Fairview",
    "state": "OR",
    "postal_code": "97024",
    "country": "US"
  }
}'

Response

Success Response

Code: 201 Created

{
  "id": "3377",
  "organisation_id": "7412",
  "clinic_id": "5831",
  "first_name": "Priya",
  "middle_name": null,
  "last_name": "Raman",
  "full_name": "Priya Raman",
  "title": "L Knee Post-Op",
  "degree": null,
  "npi": "1740398215",
  "speciality": "PHYSICAL_THERAPY",
  "taxonomy_code": null,
  "email": "m.delgado@example.com",
  "phone": "+1-555-0143",
  "fax": null,
  "group_name": null,
  "office_name": null,
  "address": {
    "line1": "482 Willow Creek Rd",
    "line2": null,
    "city": "Fairview",
    "state": "OR",
    "postal_code": "97024",
    "country": "US"
  }
}

The Location header carries the URL of the created resource.

Response Fields

Field	Type	Description
id	string or null	The registry id for this physician. Reference it from a case as referring_physician_id.
organisation_id	string or null	The organisation this record belongs to. Derived from the access token on writes and never trusted from the body.
clinic_id	string or null	The clinic this record belongs to.
first_name	string or null
middle_name	string or null
last_name	string or null
full_name	string or null	Always derived from the name parts.
title	string or null
degree	string or null
npi	string or null
speciality	string or null	The record's primary speciality.
taxonomy_code	string or null	NUCC provider taxonomy code.
email	string or null
phone	string or null
fax	string or null
group_name	string or null
office_name	string or null
address	object or null	See Address.

Address

Field	Type	Description
line1	string or null
line2	string or null
city	string or null
state	string or null
postal_code	string or null
country	string or null

Error Response

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	code	Meaning
400 Bad Request	bad_request	The request body or parameters failed validation. errors[] names the offending fields.
401 Unauthorized	unauthorized	The access token is missing, malformed or expired.
403 Forbidden	forbidden	The request references a resource outside the token's organisation or clinic scope.
404 Not Found	not_found	No such resource, or it's outside your scope.
429 Too Many Requests	rate_limited	Rate limit exceeded. Back off and retry.
500 Internal Server Error	internal_error	Unexpected server error.
502 Bad Gateway	upstream_error	Upstream service failed or timed out.