Add patient API

Use this endpoint to create a patient record and optionally attach one or more encounter summaries in the same request.

Endpoint

POST /APIPatientData

Authentication and security

Send x-api-key with a key scoped for patient creation.

Use x-request-id to make retries traceable and easier to reconcile.

Request example

curl -X POST "https://popularishealth.web.app/APIPatientData" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-request-id: partner-patient-sync-20260307-001" \
  -d '{
    "patient": {
      "firstName": "John",
      "lastName": "Doe",
      "dob": "1980-01-01",
      "gender": "Male",
      "address": {
        "address1": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345"
      },
      "memberId": "A12345",
      "payerName": "HealthPayer"
    },
    "encounters": [
      {
        "dateOfService": "2026-03-07",
        "reasonForVisit": "Routine follow-up",
        "service": "Consultation",
        "encounterType": "In-person",
        "controlNumber": "CN123456",
        "notes": "Imported from partner system."
      }
    ]
  }'

Success response

{
  "status": "success",
  "message": "Patient data saved successfully with 1 encounter(s).",
  "patientId": "UID12345",
  "encounterCount": 1,
  "requestId": "partner-patient-sync-20260307-001"
}

Response headers

• x-request-id is returned as the stable trace id for the request.
• x-ratelimit-minute-limit shows the per-minute key limit.
• x-ratelimit-minute-remaining shows requests left in the current minute.
• x-ratelimit-reset returns the ISO reset time for the active minute bucket.

Common errors

• 400: the body is invalid or required patient fields are missing.
• 401: the API key is missing or invalid.
• 403: the active key is blocked by scope or partner policy.
• 429: the key exceeded the per-minute rate limit.

After creating a patient, partners often continue with attachment retrieval or result submission.