Mantys Eligibility APIQuickstart
Your first successful check, in four steps, with the polling numbers to use.
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://hrcm-api.themantys.com/v2/api-integration-v3Every call with a real ID is a real call
A create-task request with a real member ID signs in to a live insurer portal on your clinic's
credentials and runs a real lookup, which the payer sees and rate-limits. To build and test your
client first, send a test ID such as 990-01: it never contacts a payer and
returns a documented response after 30 seconds. Do not point a load test at this API with either.
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"
}'The response is a 200, not a 201:
{
"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"
}
}
}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).
{"id": "00000000-0000-4000-a000-000000000001","tenant_id": "yourorg","clinic_id": "00000000-0000-4000-a000-000000000002","created_at": "2026-04-23T04:15:44.832000","updated_at": "2026-04-23T04:16:20.953000","task_id": "00000000-0000-4000-a000-000000000001","status": "PROCESS_COMPLETE","request_dump": {"name": "Sample Patient","phone": "+971 50 000 0000","id_type": "CARDNUMBER","tpa_name": "TPA002","payerName": "","doctorName": "Sample Clinician","extra_args": {"title": "","value": "","request_start_time": 1776917744.8226814},"visit_type": "OUTPATIENT","emirates_id": "MBR-0000000","practice_id": "00000000-0000-4000-a000-000000000002","user_id": "00000000-0000-4000-a000-000000000003","dob": null,"mode": "prod","test_mode": false},"interim_results": {"tpa_name": "TPA002","screenshot_key": "https://storage.example.com/eligibility/00000000-0000-4000-a000-000000000001/document.png?sig=PLACEHOLDER&se=2026-01-01T00%3A00%3A00Z","referral_documents": [{"id": "claim_form","tag": "Claim Form","s3_url": "https://storage.example.com/eligibility/00000000-0000-4000-a000-000000000001/document.png?sig=PLACEHOLDER&se=2026-01-01T00%3A00%3A00Z"},{"id": "claim_form_image","tag": "Claim Form Image","s3_url": "https://storage.example.com/eligibility/00000000-0000-4000-a000-000000000001/document.png?sig=PLACEHOLDER&se=2026-01-01T00%3A00%3A00Z"},{"id": "table_of_benefits","tag": "Table of Benefits","s3_url": "https://storage.example.com/eligibility/00000000-0000-4000-a000-000000000001/document.png?sig=PLACEHOLDER&se=2026-01-01T00%3A00%3A00Z"},{"id": "member_eligibility_document","tag": "Member Eligibility Document","s3_url": "https://storage.example.com/eligibility/00000000-0000-4000-a000-000000000001/document.png?sig=PLACEHOLDER&se=2026-01-01T00%3A00%3A00Z"}]},"is_search_all": false,"search_all_status": null,"created_by_user_id": null,"eligibility_result": {"id": "00000000-0000-4000-a000-000000000001:TPA002","tenant_id": "yourorg","clinic_id": "00000000-0000-4000-a000-000000000002","created_at": "2026-04-23T04:16:21.691000","updated_at": "2026-04-23T04:16:21.691000","data_dump": {"tpa": "TPA002","data": {"payer_id": "TPA002","is_eligible": true,"patient_info": {"policy_holder_dob": "1990-01-01","policy_holder_name": "Sample Policy Holder","patient_emirates_id": "784-0000-0000000-0","policy_primary_member_id": "MBR-0000000","policy_primary_dha_member_id": "0000000000"},"copay_analysis": {"copay_details": [{"remarks": "Citation: Co-Part: 10% | \n\n ","visit_type": "Laboratory","copay_amount": null,"cost_sharing": {"visit_type": "Outpatient","copay_amount": null,"visit_setting": "Outpatient","copay_currency": "AED","copay_percentage": 10,"copay_maximum_scope": null,"copay_maximum_amount": null,"coinsurance_percentage": null},"visit_setting": "Outpatient","copay_currency": "AED","copay_max_scope": null,"copay_max_amount": null,"copay_percentage": "10.0","coinsurance_percentage": null},{"remarks": "Citation: Co-Part: 10% | \n\n ","visit_type": "Radiology","copay_amount": null,"cost_sharing": {"visit_type": "Outpatient","copay_amount": null,"visit_setting": "Outpatient","copay_currency": "AED","copay_percentage": 10,"copay_maximum_scope": null,"copay_maximum_amount": null,"coinsurance_percentage": null},"visit_setting": "Outpatient","copay_currency": "AED","copay_max_scope": null,"copay_max_amount": null,"copay_percentage": "10.0","coinsurance_percentage": null},{"remarks": "Citation: Co-Part: 10% | \n\n ","visit_type": "Pharmacy","copay_amount": null,"cost_sharing": {"visit_type": "Outpatient","copay_amount": null,"visit_setting": "Outpatient","copay_currency": "AED","copay_percentage": 10,"copay_maximum_scope": null,"copay_maximum_amount": null,"coinsurance_percentage": null},"visit_setting": "Outpatient","copay_currency": "AED","copay_max_scope": null,"copay_max_amount": null,"copay_percentage": "10.0","coinsurance_percentage": null},{"remarks": "Citation: Deductible Excess: 50 AED Per Claim | \n\n ","visit_type": "Consultation","copay_amount": 50,"cost_sharing": {"visit_type": "Outpatient","copay_amount": 50,"visit_setting": "Outpatient","copay_currency": "AED","copay_percentage": null,"copay_maximum_scope": "Per Claim","copay_maximum_amount": null,"coinsurance_percentage": null},"visit_setting": "Outpatient","copay_currency": "AED","copay_max_scope": "Per Claim","copay_max_amount": null,"copay_percentage": "None","coinsurance_percentage": null}],"waiting_period": "Not Specified","special_remarks": [],"new_version_of_copay_analysis": {"benefits": [{"limits": null,"remarks": null,"conditions": null,"cost_sharing": [{"visit_type": "Outpatient","copay_amount": null,"visit_setting": "Outpatient","copay_currency": "AED","copay_percentage": 10,"copay_maximum_scope": null,"copay_maximum_amount": null,"coinsurance_percentage": null}],"coverage_status": "Covered","service_category_original": "Laboratory","service_category_standardized": "Laboratory"},{"limits": null,"remarks": null,"conditions": null,"cost_sharing": [{"visit_type": "Outpatient","copay_amount": null,"visit_setting": "Outpatient","copay_currency": "AED","copay_percentage": 10,"copay_maximum_scope": null,"copay_maximum_amount": null,"coinsurance_percentage": null}],"coverage_status": "Covered","service_category_original": "Radiology","service_category_standardized": "Radiology"},{"limits": null,"remarks": null,"conditions": null,"cost_sharing": [{"visit_type": "Outpatient","copay_amount": null,"visit_setting": "Outpatient","copay_currency": "AED","copay_percentage": 10,"copay_maximum_scope": null,"copay_maximum_amount": null,"coinsurance_percentage": null}],"coverage_status": "Covered","service_category_original": "Pharmacy","service_category_standardized": "Pharmacy"},{"limits": null,"remarks": null,"conditions": null,"cost_sharing": [{"visit_type": "Outpatient","copay_amount": 50,"visit_setting": "Outpatient","copay_currency": "AED","copay_percentage": null,"copay_maximum_scope": "Per Claim","copay_maximum_amount": null,"coinsurance_percentage": null}],"coverage_status": "Covered","service_category_original": "Consultation","service_category_standardized": "Consultation"}],"policy_info": {"waiting_period": "Not Specified","policy_period_end": null,"policy_jurisdiction": "Not Specified","policy_period_start": null,"beneficiary_start_date": {"DD": 1,"MM": 1,"YYYY": 2025}},"general_remarks": [],"abbreviations_defined": []}},"failure_reason": null,"policy_network": {"is_vip": "No","payer_name": "DUBAI INSURANCE COMPANY - INS005","sponsor_id": "INS005","start_date": "2026-01-01","valid_upto": "2027-06-30","all_networks": [{"network": "PCP","plan_code": "P267","visit_type": "OP (Out Patient)","network_code": null,"network_value": "PCP","raw_plan_string": "DUBAI INSURANCE COMPANY(NEXTCARE) - SHJ","matched_plan_name": null,"network_name_as_in_text": "OP@PCP"},{"network": "RN3","plan_code": "P267","visit_type": "SP (Specialist Physician) Referral","network_code": null,"network_value": "RN3","raw_plan_string": "DUBAI INSURANCE COMPANY(NEXTCARE) - SHJ","matched_plan_name": null,"network_name_as_in_text": "SpRef@RN3"}],"package_name": null,"is_gatekeeper": "Not Mentioned","waiting_period": null,"policy_authority": "MOH","policy_plan_name": null,"work_site_covered": "Could not determine","policy_holder_name": "Sample Policy Holder","payer_name_as_in_text": "INS005 - Dubai Insurance","is_general_physician_referral_required_for_specialist_referral": true},"screenshot_key": "https://storage.example.com/eligibility/00000000-0000-4000-a000-000000000001/document.png?sig=PLACEHOLDER&se=2026-01-01T00%3A00%3A00Z","warning_messages": [{"message": "WARNING: GP referral is required for specialist referral.\n\"Gatekeeper: Yes\"\n\"This Policy is a Referral Policy* which requires a Referral from the assigned Gatekeeper**.\"","warning": true,"screenshot": null}],"policy_holder_dob": "1990-01-01","policy_holder_name": "Sample Policy Holder","referral_documents": [{"id": "claim_form","tag": "Claim Form","s3_url": "https://storage.example.com/eligibility/00000000-0000-4000-a000-000000000001/document.png?sig=PLACEHOLDER&se=2026-01-01T00%3A00%3A00Z"},{"id": "claim_form_image","tag": "Claim Form Image","s3_url": "https://storage.example.com/eligibility/00000000-0000-4000-a000-000000000001/document.png?sig=PLACEHOLDER&se=2026-01-01T00%3A00%3A00Z"},{"id": "table_of_benefits","tag": "Table of Benefits","s3_url": "https://storage.example.com/eligibility/00000000-0000-4000-a000-000000000001/document.png?sig=PLACEHOLDER&se=2026-01-01T00%3A00%3A00Z"},{"id": "member_eligibility_document","tag": "Member Eligibility Document","s3_url": "https://storage.example.com/eligibility/00000000-0000-4000-a000-000000000001/document.png?sig=PLACEHOLDER&se=2026-01-01T00%3A00%3A00Z"}],"copay_details_to_fill": [{"name": "Outpatient","values_to_fill": {"LAB": {"copay": "10.0","deductible": "0","_copayAmount": "0","_maxDeductible": "0","_copayMaxAmount": "0","should_set_copay": true,"_deductibleLegacy": "0"},"MEDICINES": {"copay": "10.0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true,"_deductibleLegacy": "0"},"PROCEDURE": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"RADIOLOGY": {"copay": "10.0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true,"_deductibleLegacy": "0"},"DIAGNOSTICS": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"CONSULTATION": {"copay": "0","deductible": "50.0","_copayAmount": "50.0","_copayMaxAmount": "0","should_set_copay": true,"_deductibleLegacy": "50.0"},"PHYSIOTHERAPY": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"DENTAL CONSULTATION & PROCEDURE": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true}},"primary_network": {"network": "PCP","network_status": null,"matched_plan_name": null},"available_networks": [{"network": "PCP","plan_code": "P267","visit_type": "OP (Out Patient)","network_code": null,"network_value": "PCP","raw_plan_string": "DUBAI INSURANCE COMPANY(NEXTCARE) - SHJ","matched_plan_name": null,"network_name_as_in_text": "OP@PCP"},{"network": "RN3","plan_code": "P267","visit_type": "SP (Specialist Physician) Referral","network_code": null,"network_value": "RN3","raw_plan_string": "DUBAI INSURANCE COMPANY(NEXTCARE) - SHJ","matched_plan_name": null,"network_name_as_in_text": "SpRef@RN3"}],"has_multiple_networks": true},{"name": "Maternity","values_to_fill": {"LAB": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"MEDICINES": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"PROCEDURE": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"RADIOLOGY": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"DIAGNOSTICS": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"CONSULTATION": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"PHYSIOTHERAPY": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"DENTAL CONSULTATION & PROCEDURE": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true}},"primary_network": {"network": "PCP","network_status": null,"matched_plan_name": null},"available_networks": [{"network": "PCP","plan_code": "P267","visit_type": "OP (Out Patient)","network_code": null,"network_value": "PCP","raw_plan_string": "DUBAI INSURANCE COMPANY(NEXTCARE) - SHJ","matched_plan_name": null,"network_name_as_in_text": "OP@PCP"},{"network": "RN3","plan_code": "P267","visit_type": "SP (Specialist Physician) Referral","network_code": null,"network_value": "RN3","raw_plan_string": "DUBAI INSURANCE COMPANY(NEXTCARE) - SHJ","matched_plan_name": null,"network_name_as_in_text": "SpRef@RN3"}],"has_multiple_networks": true},{"name": "Specialization","values_to_fill": {"LAB": {"copay": "10.0","deductible": "0","_copayAmount": "0","_maxDeductible": "0","_copayMaxAmount": "0","should_set_copay": true,"_deductibleLegacy": "0","_is_outpatient_fallback": true},"MEDICINES": {"copay": "10.0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true,"_deductibleLegacy": "0","_is_outpatient_fallback": true},"PROCEDURE": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true,"_is_outpatient_fallback": true},"RADIOLOGY": {"copay": "10.0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true,"_deductibleLegacy": "0","_is_outpatient_fallback": true},"DIAGNOSTICS": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true,"_is_outpatient_fallback": true},"CONSULTATION": {"copay": "0","deductible": "50.0","_copayAmount": "50.0","_copayMaxAmount": "0","should_set_copay": true,"_deductibleLegacy": "50.0","_is_outpatient_fallback": true},"PHYSIOTHERAPY": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true,"_is_outpatient_fallback": true},"DENTAL CONSULTATION & PROCEDURE": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true,"_is_outpatient_fallback": true}},"primary_network": {"network": "PCP","network_status": null,"matched_plan_name": null},"available_networks": [{"network": "PCP","plan_code": "P267","visit_type": "OP (Out Patient)","network_code": null,"network_value": "PCP","raw_plan_string": "DUBAI INSURANCE COMPANY(NEXTCARE) - SHJ","matched_plan_name": null,"network_name_as_in_text": "OP@PCP"},{"network": "RN3","plan_code": "P267","visit_type": "SP (Specialist Physician) Referral","network_code": null,"network_value": "RN3","raw_plan_string": "DUBAI INSURANCE COMPANY(NEXTCARE) - SHJ","matched_plan_name": null,"network_name_as_in_text": "SpRef@RN3"}],"has_multiple_networks": true},{"name": "Inpatient","values_to_fill": {"LAB": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"MEDICINES": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"PROCEDURE": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"RADIOLOGY": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"DIAGNOSTICS": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"CONSULTATION": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"PHYSIOTHERAPY": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true},"DENTAL CONSULTATION & PROCEDURE": {"copay": "0","deductible": "0","_copayAmount": "0","_copayMaxAmount": "0","should_set_copay": true}},"primary_network": {"network": "PCP","network_status": null,"matched_plan_name": null},"available_networks": [{"network": "PCP","plan_code": "P267","visit_type": "OP (Out Patient)","network_code": null,"network_value": "PCP","raw_plan_string": "DUBAI INSURANCE COMPANY(NEXTCARE) - SHJ","matched_plan_name": null,"network_name_as_in_text": "OP@PCP"},{"network": "RN3","plan_code": "P267","visit_type": "SP (Specialist Physician) Referral","network_code": null,"network_value": "RN3","raw_plan_string": "DUBAI INSURANCE COMPANY(NEXTCARE) - SHJ","matched_plan_name": null,"network_name_as_in_text": "SpRef@RN3"}],"has_multiple_networks": true}],"policy_holder_emirates_id": "784-0000-0000000-0","was_identified_by_aggregator": false},"status": "found"},"search_id": "0000-0000-0000-0000","tpa_name": "TPA002","task_id": "00000000-0000-4000-a000-000000000001","user_id": null,"status": "found"}}
Highlighted: eligibility_result.status. Every other key on the response is documented on Results.
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
784prefix. Rejected at create time with a 400; the check never runs. Send the full784-YYYY-XXXXXXX-D. - Stopping on any status you do not recognise. The set of in-flight
statuses can grow. Stop only on
PROCESS_COMPLETE,CANCELLEDorFAILED. - Treating
PROCESS_COMPLETEas "eligible". It only means the task finished. The member may not have been found at all. - Sending a
visit_typethe 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.