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

{
  "success": true,
  "message": "Task created successfully",
  "data": {
    "task_id": "00000000-0000-4000-a000-000000000001",
    "status": "pending",
    "organization_api_task_db": {
      "task_id_in_db": "00000000-0000-4000-a000-000000000001",
      "status": "IN_QUEUE"
    }
  }
}

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:

{
  "success": false,
  "message": "Emirates ID does not start with 784-",
  "data": null
}

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. A search-all that carries credentials asks DHPO only, and checks only the payers it sent logins 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:

{
  "success": true,
  "message": "Task created successfully",
  "data": {
    "task_id": "00000000-0000-4000-a000-000000000001",
    "status": "pending",
    "organization_api_task_db": {
      "task_id_in_db": "00000000-0000-4000-a000-000000000001",
      "status": "SEARCH_ALL_PROCESSING"
    },
    "is_search_all": true,
    "search_all_status": "SEARCH_ALL_PROCESSING"
  }
}

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. Every one of them is optional, and none is validated, so the column that matters is the last one: what the payer does when the key is absent is what you get by default.

Three things about the shapes are worth reading twice, because none of them produces an error when you get it wrong:

• A boolean is not always a boolean. use_dental, use_metlife and use_dubaicare are compared against the literal string "YES", so a JSON true reads as no. is_emergency, exception_case and the Daman flags do take a real boolean.
• visit_category is the one extra with an enum behind it, and the only one where a wrong value fails the check rather than being ignored.
• is_maternity needs doctorId. Daman applies it only when the clinician licence on the request resolves to a maternity specialty; without one the flag is read and dropped.

credentials

By default a check runs under the portal logins Mantys holds for the clinic named by X-Clinic-ID. An integration that keeps those logins on its own side can send them on the request instead. When credentials is present, the portals it names use the supplied login for this check only. On a search-all (BOTH, DHPO, RIYATI) it also sets the scope: only the portals it names are checked. The DHPO lookup still runs on the stored DHPO login and narrows them; Riayati is skipped, and no other stored login is used. The Sending credentials page walks through the whole contract with a full request.

Key the object by TPA code. A portal with one login takes an object; a portal with several takes a list, and license_number is only read by payers that need it:

{
  "tpa_name": "BOTH",
  "id_type": "EMIRATESID",
  "id_value": "784-0000-0000000-0",
  "visit_type": "OUTPATIENT",
  "credentials": {
    "TPA004": { "username": "sample.user@sampleclinic.com", "password": "..." },
    "INS012": [
      { "username": "sample.user.a@sampleclinic.com", "password": "...", "license_number": "MOH-F-0000000" },
      { "username": "sample.user.b@sampleclinic.com", "password": "...", "license_number": "DHA-F-0000000" }
    ]
  }
}

For a single-TPA request you can send one login without the key, and it applies to tpa_name:

{
  "tpa_name": "TPA004",
  "id_type": "EMIRATESID",
  "id_value": "784-0000-0000000-0",
  "visit_type": "OUTPATIENT",
  "credentials": { "username": "sample.user@sampleclinic.com", "password": "..." }
}

Unlike extra_args, this object is validated, and a bad shape is rejected with a 400 before any task is created:

• every login needs a non-empty username and password; license_number is the only other key accepted
• keys must be TPA codes: BOTH, DHPO and RIYATI name a fan-out, not a portal, so they are not accepted as keys
• the single-login shorthand is only accepted when tpa_name is one portal, because there is nothing for it to belong to on a search-all request

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 Common search scenarios 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": "TPA002",
  "id_type": "EMIRATESID",
  "id_value": "784-0000-0000000-0",
  "visit_type": "DENTAL"
}

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

{
  "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
  }
}

{
  "tpa_name": "INS010",
  "id_type": "CARDNUMBER",
  "id_value": "MBR-0000000",
  "visit_type": "DENTAL",
  "extra_args": {
    "use_dental": "YES"
  }
}

{
  "tpa_name": "TPA004",
  "id_type": "EMIRATESID",
  "id_value": "784-0000-0000000-0",
  "visit_type": "OUTPATIENT",
  "extra_args": {
    "exception_case": false,
    "referral_document_url": "https://files.example.com/referral.pdf",
    "referring_physician": "DHA-P-0000000"
  }
}

{
  "tpa_name": "INS026",
  "id_type": "EMIRATESID",
  "id_value": "784-0000-0000000-0",
  "visit_type": "CONSULTATION_REFERRAL",
  "extra_args": {
    "referring_physician": "DHA-P-0000000"
  }
}

{
  "tpa_name": "INS026",
  "id_type": "EMIRATESID",
  "id_value": "784-0000-0000000-0",
  "visit_type": "ULTRASOUND_SECOND_TRIMESTER"
}

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

{
  "success": false,
  "message": "TPA or Insurance name not provided",
  "data": null
}

See Errors for the full list.