{
  "openapi": "3.0.3",
  "info": {
    "title": "ApexEHR Patient Selection API",
    "version": "1.0.0",
    "description": "Public reference for the ApexEHR patient-selection workflow. API use is governed by https://apexehr.com/developers/api-terms."
  },
  "servers": [
    {
      "url": "https://api.apexehr.com",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "apx_sid",
        "description": "HttpOnly session cookie set by POST /v1/api/auth/login. Preserve the cookie and send it with subsequent requests until the server expires, revokes, or clears the session."
      }
    }
  },
  "paths": {
    "/v1/api/auth/login": {
      "post": {
        "operationId": "startSession",
        "summary": "Authenticate a user and start a session",
        "description": "Authenticates the user with username and password. On success, the server sets the apx_sid HttpOnly session cookie. Complete the applicable MFA flow when the response indicates MFA is required.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["username", "password"],
                "properties": {
                  "username": { "type": "string" },
                  "password": { "type": "string", "format": "password" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Authentication succeeded. The response sets the apx_sid HttpOnly session cookie." },
          "400": { "description": "Username or password was missing or malformed." },
          "401": { "description": "Authentication failed." }
        }
      }
    },
    "/v1/api/patients": {
      "get": {
        "operationId": "selectPatient",
        "summary": "Find a patient and return the ApexEHR patient identifier",
        "description": "Use keyword in Last, First format together with dateOfBirth to identify a patient. Add primaryPhone when additional discrimination is needed. The returned data[].id is the stable patient token for subsequent API requests.",
        "security": [{ "sessionCookie": [] }],
        "parameters": [
          {
            "name": "X-Request-Clinic",
            "in": "header",
            "required": false,
            "schema": { "type": "string", "format": "uuid" },
            "description": "Optional clinic context for an authorized non-default clinic."
          },
          {
            "name": "keyword",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Recommended value: Last, First. MRN and name-term matching are also supported."
          },
          {
            "name": "dateOfBirth",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "date" },
            "description": "Date of birth in YYYY-MM-DD format. Use with keyword for patient selection."
          },
          {
            "name": "primaryPhone",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Exact phone match; optional additional discriminator."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 10, "minimum": 1 },
            "description": "Maximum number of records to return."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 0, "minimum": 0 },
            "description": "Number of records to skip."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching patients and pagination metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["success", "data", "pagination"],
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": ["id", "mrn", "first_name", "last_name", "date_of_birth"],
                        "properties": {
                          "id": { "type": "string", "format": "uuid", "description": "Stable patient identifier for subsequent requests." },
                          "mrn": { "type": "string" },
                          "first_name": { "type": "string" },
                          "last_name": { "type": "string" },
                          "date_of_birth": { "type": "string", "format": "date" }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "total": { "type": "integer" },
                        "offset": { "type": "integer" },
                        "limit": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid request, including an invalid dateOfBirth value." },
          "401": { "description": "Missing, invalid, or expired authenticated session." },
          "403": { "description": "The authenticated user lacks required permission or clinic access." },
          "500": { "description": "Unexpected server error." }
        }
      }
    }
  }
}