Patient Matching Middleware API

Probabilistic patient matching and deduplication middleware. Explainable, deterministic scoring from demographics only — no external data lookups. Identity resolution aid; human review recommended for ambiguous matches.

Authentication

x-rapidapi-key: YOUR_RAPIDAPI_KEY
Content-Type: application/json

Pricing Tiers

Feature	Free ($0)	Pro ($25/mo)	Ultra ($75/mo)	Mega ($150/mo)
Requests/mo	200	25,000	100,000	5,500,000
Rate limit	10 req/min	60 req/min	240 req/min	600 req/min
Indexed mode	—	25K patients	500K patients	5M patients
Audit retention	—	30 days	90 days	180 days

All plans billed through RapidAPI. Default no_store=true on all match endpoints — no PHI is persisted unless you explicitly enable retention.

Patient Object Schema

{
  "patient_id": "string (optional)",
  "first_name": "string (required)",
  "last_name": "string (required)",
  "dob": "YYYY-MM-DD (required)",
  "sex": "M | F | X | U (optional)",
  "phone": "string (optional)",
  "email": "string (optional)",
  "address": {
    "line1": "string",
    "city": "string",
    "state": "string",
    "postal": "string",
    "country": "string"
  },
  "identifiers": {
    "mrn": "string",
    "external_id": "string"
  }
}

Scoring & Decisions

The engine uses weighted Jaro-Winkler similarity across demographics with these default thresholds:

Decision	Score Range	Recommended Action
`no_match`	< 0.65	`create_new`
`possible_match`	0.65 – 0.79	`human_review`
`likely_match`	0.80 – 0.92	`human_review`
`exact_match`	≥ 0.93	`merge_candidate`

Field weights: dob 25%, last_name 20%, first_name 15%, phone 15%, address 10%, email 8%, identifiers 5%, sex 2%. Thresholds are customizable per request via the options.thresholds object.

Endpoints

GET /health

Health check. No authentication required.

curl https://matchpulse.p.rapidapi.com/v1/health

Response (200):

{
  "ok": true,
  "service": "matchpulse",
  "version": "1.0.0",
  "timestamp": "2026-04-13T12:00:00.000Z"
}

POST /patient/match

Match a single candidate against a roster of patients. Returns the best matches with explainable scores, factors, conflicts, and recommended actions.

curl -X POST https://matchpulse.p.rapidapi.com/v1/patient/match \
  -H "x-rapidapi-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "candidate": {
    "first_name": "Jane",
    "last_name": "Smith",
    "dob": "1985-03-15",
    "phone": "555-0142"
  },
  "mode": "inline",
  "roster": [
    {
      "patient_id": "p1",
      "first_name": "Janet",
      "last_name": "Smith",
      "dob": "1985-03-15",
      "phone": "5550142"
    },
    {
      "patient_id": "p2",
      "first_name": "Jane",
      "last_name": "Smyth",
      "dob": "1985-03-15"
    }
  ],
  "options": {
    "max_results": 5,
    "no_store": true
  }
}'

Response (200):

{
  "decision": "likely_match",
  "match_score": 0.8721,
  "best_matches": [
    {
      "patient_id": "p1",
      "score": 0.8721,
      "decision": "likely_match",
      "factors": [
        { "field": "dob", "contribution": 0.25, "evidence": "exact" },
        { "field": "last_name", "contribution": 0.20, "evidence": "exact" },
        { "field": "phone", "contribution": 0.15, "evidence": "normalized exact" },
        { "field": "first_name", "contribution": 0.1388, "evidence": "JaroWinkler 0.926" }
      ],
      "conflicts": [],
      "recommended_action": "human_review"
    }
  ],
  "request_id": "a1b2c3d4-..."
}

Mode: inline — you supply the roster in the request. indexed — matches against your pre-uploaded patient index (requires Pro+ tier with retention enabled).

POST /patient/match/bulk

Match multiple candidates against a shared roster in a single call. Each candidate is scored independently. Max 200 candidates, max 2000 roster records.

curl -X POST https://matchpulse.p.rapidapi.com/v1/patient/match/bulk \
  -H "x-rapidapi-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "candidates": [
    { "first_name": "Jane", "last_name": "Smith", "dob": "1985-03-15" },
    { "first_name": "Robert", "last_name": "Johnson", "dob": "1972-08-22" }
  ],
  "roster": [
    { "patient_id": "p1", "first_name": "Janet", "last_name": "Smith", "dob": "1985-03-15" },
    { "patient_id": "p2", "first_name": "Bob", "last_name": "Johnson", "dob": "1972-08-22" }
  ]
}'

Response (200):

{
  "results": [
    {
      "candidate_index": 0,
      "decision": "likely_match",
      "match_score": 0.87,
      "best_matches": [ ... ]
    },
    {
      "candidate_index": 1,
      "decision": "possible_match",
      "match_score": 0.72,
      "best_matches": [ ... ]
    }
  ],
  "request_id": "b2c3d4e5-..."
}

POST /patient/cluster

Detect duplicate clusters within a patient list using Disjoint Set Union. Groups patients that likely refer to the same person. Max 2000 patients.

curl -X POST https://matchpulse.p.rapidapi.com/v1/patient/cluster \
  -H "x-rapidapi-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "patients": [
    { "patient_id": "p1", "first_name": "John", "last_name": "Doe", "dob": "1990-01-01" },
    { "patient_id": "p2", "first_name": "Jon", "last_name": "Doe", "dob": "1990-01-01" },
    { "patient_id": "p3", "first_name": "Jane", "last_name": "Smith", "dob": "1985-05-20" }
  ],
  "options": { "threshold": 0.80 }
}'

Response (200):

{
  "clusters": [
    {
      "cluster_id": "c1",
      "members": ["p1", "p2"],
      "confidence": 0.91,
      "summary": "last_name: exact + dob: exact + first_name: JaroWinkler 0.933"
    }
  ],
  "request_id": "c3d4e5f6-..."
}

Note: p3 (Jane Smith) is not included in any cluster because she doesn't match above the threshold with any other patient.

POST /patient/merge/suggest

Generate a merge plan for two patients identified as duplicates. Returns which fields to keep, which to merge, any conflicts requiring manual review, and risk notes.

curl -X POST https://matchpulse.p.rapidapi.com/v1/patient/merge/suggest \
  -H "x-rapidapi-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "primary": {
    "first_name": "John",
    "last_name": "Doe",
    "dob": "1990-01-01",
    "phone": "555-1234",
    "email": "john@example.com",
    "identifiers": { "mrn": "MRN001" }
  },
  "duplicate": {
    "first_name": "Jon",
    "last_name": "Doe",
    "dob": "1990-01-01",
    "phone": "555-5678",
    "email": "jdoe@example.com"
  }
}'

Response (200):

{
  "merge_plan": {
    "keep_fields": {
      "dob": "1990-01-01",
      "first_name": "John",
      "last_name": "Doe",
      "mrn": "MRN001"
    },
    "merge_fields": {
      "phones": ["5551234", "5555678"],
      "emails": ["john@example.com", "jdoe@example.com"]
    },
    "conflicts": [
      {
        "field": "email",
        "primary": "john@example.com",
        "duplicate": "jdoe@example.com",
        "resolution": "manual_review"
      }
    ]
  },
  "risk_notes": [
    "Identity resolution aid; human review recommended for ambiguous matches."
  ],
  "request_id": "d4e5f6g7-..."
}

POST /normalize/name

Normalize a patient name — lowercases, strips special characters, collapses whitespace.

curl -X POST https://matchpulse.p.rapidapi.com/v1/normalize/name \
  -H "x-rapidapi-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "  O\'Brien-Smith  " }'

Response (200):

{
  "original": "  O'Brien-Smith  ",
  "normalized": "o'brien-smith",
  "type": "name",
  "request_id": "e5f6g7h8-..."
}

POST /normalize/phone

Normalize a phone number — strips formatting, removes country code prefix 1.

curl -X POST https://matchpulse.p.rapidapi.com/v1/normalize/phone \
  -H "x-rapidapi-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "+1 (555) 014-2000" }'

Response (200):

{
  "original": "+1 (555) 014-2000",
  "normalized": "5550142000",
  "type": "phone",
  "request_id": "f6g7h8i9-..."
}

POST /normalize/address

Normalize an address — lowercases, abbreviates street types (Street→st, Avenue→ave, etc.), strips punctuation, tokenizes for comparison.

curl -X POST https://matchpulse.p.rapidapi.com/v1/normalize/address \
  -H "x-rapidapi-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "address": {
    "line1": "123 North Main Street, Apt. 4B",
    "city": "Springfield",
    "state": "IL",
    "postal": "62704"
  }
}'

Response (200):

{
  "original": { "line1": "123 North Main Street, Apt. 4B", "city": "Springfield", "state": "IL", "postal": "62704" },
  "normalized": {
    "tokens": ["123", "n", "main", "st", "apt", "4b"],
    "city": "springfield",
    "state": "il",
    "postal": "62704"
  },
  "type": "address",
  "request_id": "g7h8i9j0-..."
}

POST /index/upsert

Upload patients to your tenant index for use with indexed match mode. Requires Pro+ tier and retention: true.

curl -X POST https://matchpulse.p.rapidapi.com/v1/index/upsert \
  -H "x-rapidapi-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "patients": [
    { "patient_id": "p100", "first_name": "Alice", "last_name": "Wong", "dob": "1992-07-14", "phone": "555-9999" }
  ],
  "options": { "retention": true }
}'

Response (200):

{
  "upserted": 1,
  "request_id": "h8i9j0k1-..."
}

POST /index/delete

Remove patients from your tenant index by ID.

curl -X POST https://matchpulse.p.rapidapi.com/v1/index/delete \
  -H "x-rapidapi-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "delete",
  "patient_ids": ["p100"]
}'

Response (200):

{
  "deleted": 1,
  "request_id": "i9j0k1l2-..."
}

GET /index/stats

Get statistics about your tenant patient index.

curl https://matchpulse.p.rapidapi.com/v1/index/stats \
  -H "x-rapidapi-key: YOUR_KEY"

Response (200):

{
  "total_patients": 1,
  "last_updated": "2026-04-13T12:00:00.000Z",
  "request_id": "j0k1l2m3-..."
}

GET /audit/events

Retrieve your audit log. Metadata only — never contains PHI. Query parameter limit controls the number of events returned (default 50, max 100). Requires Pro+ tier.

curl "https://matchpulse.p.rapidapi.com/v1/audit/events?limit=10" \
  -H "x-rapidapi-key: YOUR_KEY"

Response (200):

{
  "events": [
    {
      "endpoint": "POST /v1/patient/match",
      "meta": { "mode": "inline", "roster_size": 2, "decision": "likely_match", "match_score": 0.87, "contains_phi": false },
      "created_at": "2026-04-13T12:00:00.000Z"
    }
  ],
  "request_id": "k1l2m3n4-..."
}

GET /limits

Check your current usage and remaining quota for the billing period.

curl https://matchpulse.p.rapidapi.com/v1/limits \
  -H "x-rapidapi-key: YOUR_KEY"

Response (200):

{
  "tier": "free",
  "limits": {
    "match_calls": { "used": 12, "max": 200 },
    "bulk_calls": { "used": 0, "max": 10 },
    "cluster_calls": { "used": 1, "max": 5 },
    "index_ops": { "used": 0, "max": 0 }
  },
  "rate_limit": "10 req/min",
  "request_id": "l2m3n4o5-..."
}

Error Codes

Status	Meaning	Common Cause
`400`	Bad Request	Missing required fields (`first_name`, `last_name`, `dob`), empty roster, exceeding max roster/candidate limits (2000/200), missing `retention: true` for index ops
`401`	Unauthorized	Missing or invalid `x-rapidapi-key`, proxy secret mismatch
`405`	Method Not Allowed	Wrong HTTP method (e.g., GET on a POST-only endpoint)
`429`	Rate Limited	Exceeded your tier's rate limit (handled by RapidAPI proxy)
`500`	Internal Error	Server-side failure — retry with exponential backoff

All error responses follow this format:

{
  "error": {
    "message": "candidate requires first_name, last_name, dob",
    "status": 400
  },
  "request_id": "m3n4o5p6-..."
}

Request Limits

Limit	Value
Max roster size (inline mode)	2,000 patients
Max candidates (bulk match)	200 per call
Max patients (cluster)	2,000 per call
Max results returned	5 (configurable via `options.max_results`)
Audit events per query	100 max

Privacy & Compliance

No external lookups — all matching is done from the demographics you provide.
no_store: true is the default. No PHI is persisted unless you explicitly opt in with retention: true.
redact_output: true — available on match endpoints to redact PII from responses.
Audit logs contain only metadata (endpoint, decision, record counts) — never PHI.
Never auto-merges — all merge suggestions require human review.

Contact

Email	patientmatch@fastmail.com
API Support & Billing	RapidAPI Dashboard