Quickstart

Before you start

You need three values: an API key, a clinic id and a client id. All three are issued by Mantys during onboarding. To request them, or to check which payers your clinic is configured for, contact kriti@mantys.io or sudhanshu@mantys.io. See Authentication for what each one identifies.

Export them, along with the base URL every step below uses:

export MANTYS_API_KEY=...      # without the "Bearer " prefix
export MANTYS_CLINIC_ID=...
export MANTYS_CLIENT_ID=...
export BASE=https://prod.api.mantys.org/v2/api-integration-v3

Every call is a real call

There is no sandbox and no test payer. A create-task request signs in to a live insurer portal on your clinic's credentials and runs a real lookup, which the payer sees and rate-limits. Do your first run with a patient you are actually seeing, and do not point a load test at this API.

Check you can reach the API

The health endpoint checks service availability; it does not validate credentials. A 200 confirms the host is up and your base URL is correct, and nothing more.

curl -sS "$BASE/health"

{ "status": "healthy", "timestamp": "2026-03-14T09:12:44.106321" }

Create a task

curl -sS -X POST "$BASE/create-task" \
  -H "x-api-key: Bearer $MANTYS_API_KEY" \
  -H "X-Clinic-ID: $MANTYS_CLINIC_ID" \
  -H "X-Client-ID: $MANTYS_CLIENT_ID" \
  -H 'Content-Type: application/json' \
  -d '{
        "tpa_name": "TPA004",
        "id_type": "EMIRATESID",
        "id_value": "784-0000-0000000-0",
        "visit_type": "OUTPATIENT"
      }'

Sample not captured yet

create-task/single will be filled in once the sample capture pass has run against a completed production task.

Keep data.task_id. Everything after this is that id.

If you do not know the payer, send "tpa_name": "BOTH" instead and read search all.

Poll until the status is terminal

curl -sS "$BASE/eligibility-result/$TASK_ID" \
  -H "x-api-key: Bearer $MANTYS_API_KEY" \
  -H "X-Clinic-ID: $MANTYS_CLINIC_ID" \
  -H "X-Client-ID: $MANTYS_CLIENT_ID"

Use GET /eligibility-result/{task_id} to retrieve both task progress and the result. Stop when status is PROCESS_COMPLETE, CANCELLED or FAILED; anything else means the task is still running.

A search-all check reports its own progress alongside that: stop when search_all_status is SEARCH_ALL_COMPLETE, or when the top-level status is CANCELLED or FAILED. See Search all.

Use these numbers:

	Interval	Polling timeout
Single payer	5 s	5 minutes
Search all	5 s	10 minutes

Provisional numbers: confirm before you ship

These are a recommended starting point, not a service level guarantee. Confirm them with kriti@mantys.io or sudhanshu@mantys.io before you build a hard timeout around them.

A polling timeout is not a task failure. Reaching your own deadline means your client stopped waiting; the task keeps running, usually because the payer is slow to respond. Surface it as "still checking" rather than as an error, keep the task id, and poll again later. A task only failed if its status came back as FAILED.

Read the response you already have

There is no fourth request. The body from the last poll is the result.

The two fields to branch on are eligibility_result.status (what happened) and eligibility_result.data_dump.data.is_eligible (the answer).

Sample not captured yet

eligibility-result/eligible at eligibility_result.status will be filled in once the sample capture pass has run against a completed production task.

status: "found" with is_eligible: true is a covered patient. Every other combination is covered on the results page.

Common first-run mistakes

Emirates ID without the 784 prefix. Rejected at create time with a 400; the check never runs. Send the full 784-YYYY-XXXXXXX-D.
Stopping on any status you do not recognise. The set of in-flight statuses can grow. Stop only on PROCESS_COMPLETE, CANCELLED or FAILED.
Treating PROCESS_COMPLETE as "eligible". It only means the task finished. The member may not have been found at all.
Sending a visit_type the payer does not accept. Nothing validates it at create time; the check runs and comes back with an error from the payer. Check the TPA matrix.