Create a check

POST /v4/eligibility-checks starts a check and returns its id straight away. The check then runs in the background (usually under a minute). Poll it with GET /v4/eligibility-checks/{id}.

In each identifiers entry, id_type is EMIRATESID, CARDNUMBER, DHAMEMBERID or POLICYNUMBER. Each payer accepts only some of these. Send a member number (not a DHA member id) as CARDNUMBER. An Emirates ID must be 784-YYYY-NNNNNNN-N or 15 digits starting 784.

Any other field is rejected with 422. That includes id_type and id_value at the top level of the body: put them inside identifiers.

• doctorId, doctorName and payerName may also be sent as doctor_id, doctor_name and payer_name.
• tpa_name, id_type and visit_type are not case-sensitive: tpa002 is read as TPA002.

Example

curl -X POST "$HOST/v4/eligibility-checks" \
  -H "X-Api-Key: Bearer $API_KEY" \
  -H "X-Clinic-Id: $CLINIC_ID" \
  -H "X-Client-ID: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{"tpa_name": "INS026", "identifiers": [{"id_type": "EMIRATESID", "id_value": "784-1990-1234567-1"}], "visit_type": "OUTPATIENT", "doctorName": "DHA-P-0000000", "name": "Patient Name"}'

Response: 201

{ "id": "3f6c2a9e-...", "status": "IN_QUEUE", "is_search_all": false, "search_all": null }

For a search across all payers, is_search_all is true and search_all holds the search's progress at creation:

{
  "id": "3f6c2a9e-...",
  "status": "IN_QUEUE",
  "is_search_all": true,
  "search_all": { "total_tpas": null, "completed_tpas": 0, "status": "SEARCH_ALL_PROCESSING" }
}

total_tpas is null because the payers to search are not known yet. The GET does not repeat this object: poll the check the same way as any other. It finishes when every payer has answered.

If a payer does not accept your id_type or visit_type, you get 400 VALIDATION_FAILED, with every problem listed in details. Nothing is started. One exception: when no ID in identifiers is usable, the 400 names only the ID problems. Fix them and resend to see anything else.

extra_args

v4 passes extra_args to the payer exactly as v3 does, so the keys, shapes and defaults are the ones on Create a task. Nothing in it is validated: a misspelled key is accepted and ignored. Every key is optional; the last column is what you get when you leave it out.

Three keys are reserved in v4. Sending any of them is 422 VALIDATION_FAILED, and nothing is started:

On POST /v4/appointment-checks, a submitter key is overwritten by the top-level submitter field when you send one.