> ## Documentation Index > Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt > Use this file to discover all available pages before exploring further. # Match a patient by demographics > Scores existing charts against submitted demographics and returns ranked candidates. Use this before creating a chart: `GET /patients?search=` matches name or MRN only, so matching from a booking form otherwise means paging every candidate surname — which either exhausts the rate budget or truncates, and a truncated match creates a duplicate chart. `truncated: true` means the candidate set was capped and MUST NOT be read as 'no match'. ## OpenAPI ````yaml /openapi-v2.json post /patients/match openapi: 3.0.0 info: title: Max AI Public API description: API for third-party marketplace apps version: '2.0' contact: {} servers: - url: https://api.maxcare.ai/v2 security: [] tags: [] paths: /patients/match: post: tags: - Patients summary: Match a patient by demographics description: >- Scores existing charts against submitted demographics and returns ranked candidates. Use this before creating a chart: `GET /patients?search=` matches name or MRN only, so matching from a booking form otherwise means paging every candidate surname — which either exhausts the rate budget or truncates, and a truncated match creates a duplicate chart. `truncated: true` means the candidate set was capped and MUST NOT be read as 'no match'. operationId: PatientsPublicController_matchPatient parameters: - name: X-Organization-Id in: header required: true schema: type: string description: Target clinic organization ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MatchPatientBody' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/MatchPatientSuccessResponse' '400': description: Missing or invalid request parameter content: application/json: schema: $ref: '#/components/schemas/PublicApiBadRequestResponse' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/PublicApiUnauthorizedResponse' '403': description: Insufficient scope content: application/json: schema: $ref: '#/components/schemas/PublicApiForbiddenResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/PublicApiRateLimitResponse' security: - api-key: [] components: schemas: MatchPatientBody: type: object properties: firstName: type: string example: Jane lastName: type: string example: Doe dateOfBirth: type: string description: YYYY-MM-DD example: '1984-02-11' phone: type: string example: '+13135550123' email: type: string example: jane@example.com postalCode: type: string example: '48507' threshold: type: number description: Minimum score to return (0–1). Defaults to 0.75. example: 0.75 limit: type: number description: Maximum candidates to return (1–25). Defaults to 5. example: 5 MatchPatientSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/MatchPatientData' required: - code - data PublicApiBadRequestResponse: type: object properties: code: type: string description: Error code example: bad_request message: type: string description: Human-readable error message example: '''id'' must be a valid UUID' trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiUnauthorizedResponse: type: object properties: code: type: string description: Error code example: unauthorized message: type: string description: Human-readable error message example: Invalid or missing API key trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiForbiddenResponse: type: object properties: code: type: string description: Error code example: forbidden message: type: string description: Human-readable error message example: Insufficient scope trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiRateLimitResponse: type: object properties: code: type: string description: Error code example: rate_limit_exceeded message: type: string description: Human-readable error message example: Rate limit exceeded. Maximum 1000 requests per 60 seconds. trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id MatchPatientData: type: object properties: candidates: type: array items: $ref: '#/components/schemas/MatchCandidateResponse' truncated: type: boolean description: >- Whether the candidate set was truncated by `limit` — a truncated match must never be treated as 'no match' example: false required: - candidates - truncated MatchCandidateResponse: type: object properties: patientId: type: string example: pat_c56103bcd39c46d39f3138dd2b5e05f6 mrn: type: string nullable: true example: MM0000123456 score: type: number description: 0–1 confidence example: 0.97 matchedFields: example: - lastName - dateOfBirth - phone type: array items: type: string unverifiedFields: description: >- Fields you supplied that the chart has no value for, so they could neither agree nor disagree. These do not count against the score — but when `dateOfBirth` appears here the score is CAPPED below the default threshold, because a chart with no DOB scored on name and phone alone is how a booking flow attaches to the wrong person. Ask the patient to confirm rather than auto-accepting. example: - dateOfBirth type: array items: type: string conflictingFields: description: >- Fields present on both sides that disagree — the reason a high score may still need human review example: - postalCode type: array items: type: string required: - patientId - mrn - score - matchedFields - unverifiedFields - conflictingFields securitySchemes: api-key: scheme: bearer bearerFormat: JWT type: http description: Marketplace API key ````