Create a task

POST /create-task

Queues one eligibility check and returns immediately with a task id. The portal work happens afterwards; nothing about the patient's coverage is known when this call returns.

Request

Response

organization_api_task_db is internal bookkeeping that predates this API. It carries the same id as task_id; you can ignore the whole object.

Choosing an identifier

Send exactly one identifier, and tell the API which kind it is with id_type. Support varies by payer; the TPA matrix has the per-payer list.

Emirates ID

The default, and the only identifier every payer accepts.

{ "id_type": "EMIRATESID", "id_value": "784-0000-0000000-0" }

The value must start with 784. This is checked before the task is created, so a bad prefix costs you nothing:

Hyphens are accepted. Nothing else about the format is validated at create time: a well-formed but non-existent Emirates ID will be accepted, run, and come back as member_not_found.

Member ID or card number

{ "id_type": "CARDNUMBER", "id_value": "MBR-0000000" }

Use this when the patient has their insurance card but their Emirates ID is not linked at the payer. AXA (INS010) expects the full seven-segment card number here; most other payers accept the member id as printed.

Two rules govern it, and neither is enforced at create time:

• The payer has to support it. Only some payers can search on a card number; the rest treat whatever you send as an Emirates ID and find nobody. The TPA matrix marks which is which.
• A search-all accepts it. Prefer the Emirates ID for a sweep when you have one. See Search-all, member ID below.

DHA member ID

{ "id_type": "DHAMEMBERID", "id_value": "0000000000" }

The regulator-issued member id. Supported by NAS, Neuron, Nextcare, Al Madallah, MedNet, AXA, NGI and Lifeline.

Policy number

{ "id_type": "POLICYNUMBER", "id_value": "POL-0000000" }

Supported by Nextcare and Lifeline only. Least reliable of the four: a policy number can match several members, and the portal will pick one.

Single TPA versus search all

If you know the payer, name it. If you do not, send one of three sentinels and the platform will ask the aggregators first and then fan out across every payer your clinic has credentials for.

Daman is never part of a search-all. If the patient may be on Daman you have to ask for INS026, TPA023, D004, D002 or INS078 by name.

A search-all create response carries two extra keys:

From there the flow is the same, except that you watch search_all_status rather than status, and the result carries aggregated_results instead of eligibility_result.

Visit type

visit_type defaults to OUTPATIENT. Each payer accepts its own list and nothing is validated at create time, so an unsupported value produces a task that runs and then fails at the portal. The TPA matrix has every accepted value per payer.

Two payers deserve a note:

• MedNet (TPA036) encodes the consultation type and the benefit in this one field. A bare benefit token means outpatient plus that benefit (DENTAL = outpatient dental); prefix it with INPATIENT_ for the inpatient variant.
• Daman uses a much longer service taxonomy (consultation reasons, ultrasound trimesters, PCSP screening packages) rather than the usual inpatient / outpatient split.

Optional patient fields

name, dob and phone are optional and are used only by payers whose portal search needs more than an identifier, or which print them onto a generated claim form. Sending them costs nothing and occasionally rescues a lookup that would otherwise fail.

doctorId matters only where the check generates a claim form. FMC (TPA010) is the clearest case. Sending it on every check is fine: payers that do not need it ignore it. Note the camelCase: it is the one field on this endpoint that is not snake_case.

It is the clinician's professional licence ID, the one issued by DHA, Riayati or Shafafiya. You hold the mapping from your clinicians to their licence IDs on your side; there is no endpoint here that returns it. A name you compose yourself will not match the portal's physician list, and at an Abu Dhabi practice a failed match fails the check rather than falling back.

extra_args

A free-form object for per-payer extras. Nothing in it is validated, so a misspelled key is accepted, the check runs, and the payer answers a question you did not mean to ask. The server also adds its own request_start_time key to whatever you send, so do not rely on getting the object back unchanged.

Every extra is an ordinary key on the object:

{
  "extra_args": {
    "maternity_treatment": true,
    "is_member_present_at_the_facility": true
  }
}

The documented extras today:

Worked combinations

Every combination below returns 200 and creates a task. Only the answer tells them apart, so they are worth reading before you meet one in production. The Try it walkthrough flags each of them as you build a request, and Payer-specific requirements collects them on one page you can send from the browser.

{
  "tpa_name": "TPA004",
  "id_type": "EMIRATESID",
  "id_value": "784-0000-0000000-0",
  "visit_type": "OUTPATIENT"
}

{
  "tpa_name": "BOTH",
  "id_type": "EMIRATESID",
  "id_value": "784-0000-0000000-0",
  "visit_type": "OUTPATIENT"
}

{
  "tpa_name": "TPA004",
  "id_type": "CARDNUMBER",
  "id_value": "MBR-0000000",
  "visit_type": "OUTPATIENT"
}

{
  "tpa_name": "BOTH",
  "id_type": "CARDNUMBER",
  "id_value": "MBR-0000000",
  "visit_type": "OUTPATIENT"
}

{
  "tpa_name": "TPA023",
  "id_type": "EMIRATESID",
  "id_value": "784-0000-0000000-0",
  "visit_type": "CONSULTATION_ELECTIVE"
}

{
  "tpa_name": "TPA004",
  "id_type": "EMIRATESID",
  "id_value": "784-0000-0000000-0",
  "visit_type": "MATERNITY",
  "extra_args": {
    "maternity_treatment": true,
    "is_member_present_at_the_facility": true
  }
}

mode and test_mode

The handler reads two further keys, mode (default "prod") and test_mode (default false).

When a check comes back empty

Three situations look like a failure but are really a hint to retry differently.

Errors

See Errors for the full list.