Referring Physicians¶

Manage referring physicians who can refer patients to your practice. This includes creating new referring physician records and searching existing ones.

Create Referring Physician¶

Create a new referring physician record in the system.

Endpoint¶

POST /apis/v1/referring-physician

Request Body¶

{
  "first_name": "string",
  "last_name": "string",
  "npi": "string",
  "degree": "string",
  "fax_number": "string",
  "phone_number": "string",
  "address1": "string",
  "address2": "string",
  "city": "string",
  "state": "string",
  "zip": "string"
}

Request Body Parameters¶

Parameter	Type	Required	Description
first_name	string	Yes	First name of the referring physician
last_name	string	Yes	Last name of the referring physician
npi	string	Yes	National Provider Identifier (10 digits)
degree	string	Yes	Medical degree (e.g., MD, DO, NP)
fax_number	string	No	Fax number without spaces
phone_number	string	No	Phone number with spaces
address1	string	No	Primary address line
address2	string	No	Secondary address line
city	string	No	City name
state	string	No	State code (2 letters)
zip	string	No	ZIP code

Example Request¶

curl -X POST '{base_url}/apis/v1/referring-physician' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  -d '{
    "first_name": "John",
    "last_name": "Smith",
    "npi": "1234567890",
    "degree": "MD",
    "fax_number": "5551234567",
    "phone_number": "555 123 4567",
    "address1": "123 Medical Center Dr",
    "address2": "Suite 200",
    "city": "Healthcare City",
    "state": "CA",
    "zip": "90210"
  }'

Response¶

Success Response¶

Status Code: 200 Ok

{
  "code": 2000,
  "data": {
    "id": 12345,
    "first_name": "John",
    "last_name": "Smith",
    "npi": "1234567890",
    "degree": "MD",
    "fax_number": "5551234567",
    "phone_number": "555 123 4567",
    "address1": "123 Medical Center Dr",
    "address2": "Suite 200",
    "city": "Healthcare City",
    "state": "CA",
    "zip": "90210",
    "created_at": "2025-07-18T10:30:00Z",
    "updated_at": "2025-07-18T10:30:00Z"
  },
  "message": "Referring physician created successfully"
}

Search Referring Physicians¶

Search for existing referring physicians in the system.

Endpoint¶

GET /apis/v1/referring-physician

Query Parameters¶

Parameter	Type	Required	Description
organisation_id	integer	Yes	Organization ID to search within
q	string	No	Search query (name, NPI, etc.)
page	integer	No	Page number (default: 1)
size	integer	No	Number of results per page (default: 10)

Example Request¶

curl '{base_url}/apis/v1/referring-physician?organisation_id=74&q=mark&page=1&size=10' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer {token}'

Response¶

Success Response¶

Status Code: 200 OK

{
  "code": 2000,
  "data": {
    "total": 25,
    "pages": 3,
    "current": 1,
    "size": 10,
    "results": [
      {
        "id": 12345,
        "first_name": "Mark",
        "last_name": "Johnson",
        "npi": "1234567890",
        "degree": "MD",
        "fax_number": "5551234567",
        "phone_number": "555 123 4567",
        "address1": "456 Clinic Ave",
        "address2": "Floor 3",
        "city": "Medical City",
        "state": "TX",
        "zip": "75001",
        "created_at": "2025-07-15T14:20:00Z",
        "updated_at": "2025-07-15T14:20:00Z"
      },
      {
        "id": 12346,
        "first_name": "Mark",
        "last_name": "Williams",
        "npi": "0987654321",
        "degree": "DO",
        "fax_number": "5559876543",
        "phone_number": "555 987 6543",
        "address1": "789 Hospital Blvd",
        "address2": null,
        "city": "Health Town",
        "state": "FL",
        "zip": "33101",
        "created_at": "2025-07-10T09:15:00Z",
        "updated_at": "2025-07-16T11:30:00Z"
      }
    ]
  },
  "message": "Success"
}

Response Parameters¶

Parameter	Type	Description
total	integer	Total number of matching results
pages	integer	Total number of pages available
current	integer	Current page number
size	integer	Number of results per page
results	array	Array of referring physician records
id	integer	Unique identifier for the physician
first_name	string	First name of the physician
last_name	string	Last name of the physician
npi	string	National Provider Identifier
degree	string	Medical degree
fax_number	string	Fax number
phone_number	string	Phone number
address1	string	Primary address line
address2	string	Secondary address line (can be null)
city	string	City name
state	string	State code
zip	string	ZIP code
created_at	string	Record creation timestamp (ISO 8601)
updated_at	string	Last update timestamp (ISO 8601)

Usage Notes¶

Creating Referring Physicians¶

NPI Validation: The NPI must be exactly 10 digits and unique in the system
Required Fields: Only first_name, last_name, npi, and degree are required
Phone Formatting: Phone numbers should include spaces for readability
Fax Formatting: Fax numbers should not include spaces
State Codes: Use standard 2-letter state abbreviations (e.g., CA, TX, NY)

Searching Referring Physicians¶

Organization Scope: Search is limited to the specified organization
Search Query: The q parameter searches across name, NPI, and other text fields
Pagination: Results are paginated; use page and size parameters to navigate
Case Insensitive: Search queries are case-insensitive