Cancel a check | Mantys Eligibility API

POST /v4/eligibility-checks/{id}/cancellation cancels the eligibility request we raised at the payer for this check. Use it when the patient leaves or the visit is not going ahead.

You send only the check id. We look up the payer and the payer's own request id from the check itself. You no longer send eligibility_id or tpa_name; sending them returns 422.

Body (optional)

{ "reason": "Patient left before the visit" }

reason is up to 500 characters. With no body, the reason is "User requested cancellation".

Response: 202

{
  "check_id": "3f6c2a9e-...",
  "status": "COMPLETE",
  "reason": "Patient left before the visit",
  "cancellations": [
    {
      "tpa_name": "INS026",
      "eligibility_id": "eElig-...",
      "card_index": null,
      "cancellation_task_id": "8b1d..."
    }
  ]
}

202 means the cancellation was sent to the payer. Poll GET /v4/eligibility-checks/{id}; its status becomes CANCELLED once the payer confirms, or FAILED if the payer refuses or cannot be reached.
status in this response is the check's status before the cancel.
eligibility_id is the payer's own reference, so you can match it in their portal.
A patient with several cards under one payer request gets one cancellation, not one per card.

Which checks can be cancelled

Check	Result
Running, `COMPLETE` or `FAILED`, with a Daman request	202
Already `CANCELLED`	409 `CHECK_NOT_CANCELLABLE`
No row carries a payer reference: the check has not reached the payer yet, or the payer's answer has no request id (the `TPA002` test check `990-01` is one)	409 `NOT_SUBMITTED_TO_PAYER`
A payer reference exists, but only from payers that cannot be cancelled	400 `CANCELLATION_NOT_SUPPORTED`
Not your clinic's check, or unknown id	404 `CHECK_NOT_FOUND`

Cancellation is supported for Daman: INS026, TPA023 (Thiqa), D002, D004 and INS078.

Send each cancel once. Repeating it before the first one finishes sends a second request to the payer.