List Referring Physicians¶

The organisation's referring physician registry. Cases reference these records by id — resolve an NPI to an id with ?npi=.

Endpoint¶

GET /v2/referring-physicians

Query Parameters¶

Parameter	Type	Required	Description
`page`	integer	Yes	1-based page number. Defaults to `1`.
`page_size`	integer	Yes	Results per page. Defaults to `25`.
`clinic_id`	string	No	The clinic this record belongs to.
`npi`	string	No
`query`	string	No	Free-text match on name

Request¶

curl --location '{base_url}/v2/referring-physicians?page=1&page_size=25' \
  --header 'Authorization: Bearer JWT_TOKEN'

Response¶

Success Response¶

Code: 200 OK

{
  "items": [
    {
      "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"
      }
    }
  ],
  "page": 1,
  "page_size": 25,
  "total": 1,
  "total_pages": 1
}

Response Fields¶

Field	Type	Description
`items`	array of object	The page of results. See Items.
`page`	integer	1-based page number.
`page_size`	integer	Results per page.
`total`	integer	Total results matching the query.
`total_pages`	integer	Total pages available.

Items¶

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.

Notes¶

?npi= resolves an NPI to a registry id — use it to find an existing record before creating a duplicate. ?query= matches on name.