Patient selection API.

Base URL and transport security

Production requests use https://api.apexehr.com. HTTPS is required. Do not send credentials or protected health information over an unencrypted connection.

Authentication and clinic context

Start a session with POST /v1/api/auth/login. A successful login establishes an HttpOnly apx_sid session cookie. API clients must preserve and send that cookie on subsequent requests until the session expires or is ended. This patient-selection API uses the session cookie; an Authorization: Bearer header is not the client authentication mechanism for this flow. If the login response requires MFA, complete the applicable MFA step before calling patient endpoints.

POST /v1/api/auth/login
Content-Type: application/json

{"username":"developer.user","password":"<password>"}

HTTP/1.1 200 OK
Set-Cookie: apx_sid=<authenticated-session>; HttpOnly; Secure

Use X-Request-Clinic to select a non-default clinic context when the authenticated user has access to more than one clinic.

# Preserve the cookie from login, then reuse it for the API request.
curl --cookie-jar cookies.txt --header "Content-Type: application/json" \
  --data '{"username":"developer.user","password":"<password>"}' \
  https://api.apexehr.com/v1/api/auth/login

curl --cookie cookies.txt \
  --header "X-Request-Clinic: <clinic-uuid>" \
  "https://api.apexehr.com/v1/api/patients?keyword=Doe%2C%20Jane&dateOfBirth=1985-03-15"

On session expiry or timeout, the API returns 401. Obtain a new session through the login flow before making another patient request.

Patient selection

Function: GET /v1/api/patients

Supply enough information to distinguish the patient. The recommended request combines the patient name in Last, First format with an exact date of birth. primaryPhone may be included as an additional discriminator.

GET /v1/api/patients?keyword=Doe%2C%20Jane&dateOfBirth=1985-03-15&limit=10
Host: api.apexehr.com
Cookie: apx_sid=<authenticated-session>
X-Request-Clinic: 550e8400-e29b-41d4-a716-446655440000

Parameters

• keyword — optional string. Use Last, First for a name match; it also supports MRN and name-term matching.
• dateOfBirth — optional string in YYYY-MM-DD format. Use with keyword for patient selection.
• primaryPhone — optional string. Exact phone match; use only as an additional discriminator.
• limit — optional integer; maximum records returned.
• offset — optional integer; number of records to skip.

Successful response

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "mrn": "MRN-10042",
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1985-03-15"
    }
  ],
  "pagination": { "total": 1, "offset": 0, "limit": 10 }
}

data[].id is the stable ApexEHR patient identifier to use in subsequent patient-data requests. If a search returns more than one patient, provide additional permitted identifying information and repeat the request; do not choose a patient arbitrarily.

Errors

• 400 — invalid request, such as an invalid dateOfBirth value.
• 401 — missing, invalid, or expired session.
• 403 — authenticated user lacks permission or clinic access.
• 500 — an unexpected server error.

Implementation requirements

• An HTTPS-capable HTTP client that preserves session cookies.
• A valid ApexEHR user account with permission to view patient demographics.
• The clinic UUID for the authorized clinic context.
• JSON parsing for the response envelope and returned patient identifier.

Download the machine-readable specification: OpenAPI 3.0 JSON.

Terms and developer agreement

API use is governed by the ApexEHR API Terms of Use and Developer Agreement and the ApexEHR Terms of Use.

For integration support, contact api-support@apexehr.com.