Skip to main content

​
Overview

The Patients API uses GraphQL to provide flexible access to patient demographics, medical records, medications, and visit history. GraphQL Endpoint: https://api.allcare.ai/graphql Authentication: API Key or OAuth 2.0 required Required Scope: read:patients (read), write:patients (write)

​
GraphQL vs REST

The Patients API uses GraphQL because:
  • Complex, nested patient data structures
  • Flexible query capabilities
  • Fetch only the data you need
  • Strongly typed schema
  • Single endpoint for all operations

​
Quick Start

​
Basic Query

query GetPatient {
  patient(id: "pat_12345") {
    id
    firstName
    lastName
    dateOfBirth
    email
    phone
  }
}

​
Query with Nested Data

query GetPatientWithMedications {
  patient(id: "pat_12345") {
    id
    firstName
    lastName
    medications {
      id
      name
      dosage
      frequency
      prescribedDate
      prescriber {
        firstName
        lastName
        npi
      }
    }
    visits {
      id
      date
      type
      provider {
        firstName
        lastName
      }
    }
  }
}

​
Schema

​
Patient Type

type Patient {
  id: ID!
  firstName: String!
  lastName: String!
  middleName: String
  dateOfBirth: Date!
  gender: Gender
  email: String
  phone: String
  address: Address
  facility: Facility
  medications: [Medication!]
  visits: [Visit!]
  allergies: [Allergy!]
  conditions: [Condition!]
  enrollmentStatus: EnrollmentStatus!
  assignedProvider: Doctor
  createdAt: DateTime!
  updatedAt: DateTime!
}

​
Queries

​
Get Single Patient

query GetPatient($id: ID!) {
  patient(id: $id) {
    id
    firstName
    lastName
    dateOfBirth
    facility {
      name
      address {
        city
        state
      }
    }
  }
}
Variables: 
{
  "id": "pat_12345"
}

​
Search Patients

query SearchPatients($facilityId: ID!, $search: String) {
  patients(facilityId: $facilityId, search: $search) {
    id
    firstName
    lastName
    dateOfBirth
    enrollmentStatus
  }
}

​
Get Patient Medications

query GetPatientMedications($patientId: ID!) {
  patient(id: $patientId) {
    id
    medications {
      id
      name
      genericName
      dosage
      strength
      frequency
      route
      prescribedDate
      startDate
      endDate
      status
      prescriber {
        id
        firstName
        lastName
        npi
      }
      pharmacy {
        name
        phone
      }
    }
  }
}

​
Mutations

​
Create Patient

mutation CreatePatient($input: CreatePatientInput!) {
  createPatient(input: $input) {
    id
    firstName
    lastName
    enrollmentStatus
    createdAt
  }
}
Variables: 
{
  "input": {
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1950-05-15",
    "gender": "MALE",
    "email": "[email protected]",
    "phone": "+1-555-0123",
    "facilityId": "fac_12345",
    "address": {
      "street1": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "zipCode": "90001"
    }
  }
}

​
Update Patient

mutation UpdatePatient($id: ID!, $input: UpdatePatientInput!) {
  updatePatient(id: $id, input: $input) {
    id
    email
    phone
    updatedAt
  }
}

​
Add Allergy

mutation AddAllergy($patientId: ID!, $allergy: AllergyInput!) {
  addPatientAllergy(patientId: $patientId, allergy: $allergy) {
    id
    allergies {
      allergen
      reaction
      severity
      notes
    }
  }
}

​
Example Requests

​
Using cURL

curl -X POST "https://api.allcare.ai/graphql" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetPatient($id: ID!) { patient(id: $id) { firstName lastName dateOfBirth } }",
    "variables": {"id": "pat_12345"}
  }'

​
Using JavaScript

const query = `
  query GetPatient($id: ID!) {
    patient(id: $id) {
      firstName
      lastName
      medications {
        name
        dosage
      }
    }
  }
`;

const response = await fetch('https://api.allcare.ai/graphql', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query,
    variables: { id: 'pat_12345' }
  })
});

const data = await response.json();

​
Using Python

import requests

query = """
  query GetPatient($id: ID!) {
    patient(id: $id) {
      firstName
      lastName
      medications {
        name
        dosage
      }
    }
  }
"""

response = requests.post(
    'https://api.allcare.ai/graphql',
    json={'query': query, 'variables': {'id': 'pat_12345'}},
    headers={'Authorization': f'Bearer {API_KEY}'}
)

data = response.json()

​
Pagination

For lists, use cursor-based pagination: 
query GetPatients($facilityId: ID!, $first: Int!, $after: String) {
  facility(id: $facilityId) {
    patients(first: $first, after: $after) {
      edges {
        node {
          id
          firstName
          lastName
        }
        cursor
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

​
Error Handling

GraphQL errors are returned in the errors array: 
{
  "errors": [
    {
      "message": "Patient not found",
      "locations": [{"line": 2, "column": 3}],
      "path": ["patient"],
      "extensions": {
        "code": "RESOURCE_NOT_FOUND",
        "patientId": "pat_99999"
      }
    }
  ],
  "data": null
}

​
HIPAA Compliance

Protected Health Information (PHI)Patient data contains PHI and must be handled according to HIPAA regulations:
  • Signed Business Associate Agreement required
  • Encryption in transit and at rest
  • Access logging and audit trails
  • Minimum necessary principle

​
GraphQL Schema Explorer

Use GraphQL introspection or GraphiQL interface to explore the full schema: 
https://api.allcare.ai/graphql/explorer
(Requires authentication)

​
Best Practices

​
Rate Limits

  • Query operations: 100 requests/minute
  • Mutation operations: 50 requests/minute
  • Complex queries: Counted by query complexity points

Doctors API

Provider management

Pharmacy API

Prescription data

Authentication

API authentication

GraphQL Docs

Learn GraphQL