Sending credentials

Run a check under portal logins you hold yourself by sending them on create-task, instead of the logins Mantys stores for the clinic.

By default every check runs under the insurance-portal logins Mantys holds for the clinic named by X-Clinic-ID. Those are configured once, during onboarding, and never appear on the wire.

If your system already holds those logins, you can send them on each request instead. Nothing else about the flow changes: the same three headers, the same task_id back, the same polling. This page is the whole contract; the create-task reference carries the same rules in short form, and the walkthrough follows a single-portal request and a search-all from the first call to the answer.

The field

Add a credentials object to the POST /create-task body. It is optional, and when it is absent the stored logins are used exactly as before.

Per request, per portal

The logins you send apply to this task only. They are not saved against the clinic, so the next request without credentials runs under the stored logins again. On a single-portal request, a portal you name uses your login and any other portal the check touches uses the stored one.

A search-all checks only the portals you send

When tpa_name is BOTH, DHPO or RIYATI and the request carries credentials, the sweep covers only the portals you sent logins for, so the task finishes as soon as those have answered. The DHPO lookup still runs first, on the clinic's stored DHPO login, and narrows your portals to the ones it lists the member under; the Riayati lookup is skipped. No other stored login is used. If DHPO lists the member under a payer you sent no login for, that payer comes back as tpa_not_configured, which tells you the login to add. A search-all without credentials sweeps every portal the clinic is configured for, as before.

Shape 1: keyed by TPA code

The general form. Each key is a TPA or INS code from the TPA matrix, and the value is one login, or a list of logins for portals where the clinic has several.

{
  "tpa_name": "BOTH",
  "id_type": "EMIRATESID",
  "id_value": "784-0000-0000000-0",
  "visit_type": "OUTPATIENT",
  "credentials": {
    "TPA004": { "username": "sample.user@sampleclinic.com", "password": "..." },
    "TPA002": { "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" }
    ]
  }
}

A login has three fields:

Field	Required	What it is
`username`	yes	The portal username, exactly as typed on the portal's login page.
`password`	yes	The portal password.
`license_number`	no	The facility or clinician licence some portals ask for at login. Only read by payers that need it; ignored elsewhere.

Keys are case-insensitive and whitespace around every value is trimmed, so a trailing newline from a copy-paste does not turn into a rejected login.

A portal variant is a separate portal with its own login, so key it by its full code. Aafiya's newer portal is TPA026__SALAMA: a login sent under TPA026 is used only for the older Aafiya portal, never for TPA026__SALAMA. To check both, send both keys.

When tpa_name is one portal, you can send the login directly and skip the key. 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": "..." }
}

This shorthand is rejected when tpa_name is BOTH, DHPO or RIYATI, because a search-all fans out to several portals and there is no single one for the login to belong to. Use shape 1 for those.

Sample requests

Set the same variables as in the Quickstart:

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-v3

Every example below uses 784-0000-0000000-0, the placeholder Emirates ID used throughout this site. It is well formed and matches no member, so a request built from one of these runs the whole flow and comes back without a member rather than with someone's coverage. That makes it a safe way to prove your logins work before you send a real member ID. The usernames are placeholders too; put your own in before sending.

These reach the payer

Unlike a test ID, every request on this page logs in to the payer's portal. A wrong password here is a real failed login at the payer, so use test IDs while you are building the client and keep these for checking the credentials themselves.

The single-login shorthand, applied to tpa_name.

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",
        "credentials": {
          "username": "sample.user@sampleclinic.com",
          "password": "REPLACE_ME"
        }
      }'

A wrong password comes back as a completed task whose result is invalid_credentials, and the message names the username that was rejected:

{
  "status": "failed",
  "data": {
    "tpa": "TPA004",
    "status": "invalid_credentials",
    "error_type": "TPAInvalidCredentialsError",
    "message": "Invalid Credentials for TPA `NAS`. Username used: `sample.user@sampleclinic.com`. Please ask your team admin to update the credentials."
  }
}

That message is the quickest way to confirm your login reached the portal: the username in it is the one you sent, not the one Mantys holds.

The response is the ordinary create-task response. Poll it the same way as any other task; see Polling.

Validation

Unlike extra_args, this object is checked before a task is created, and a bad shape returns 400 with success: false and a message naming the key at fault. The rules:

username and password are both required and must be non-empty
license_number is the only other field accepted; an unknown field is rejected rather than ignored, so a typo cannot silently drop a login
keys must be portal codes: BOTH, DHPO and RIYATI are not accepted as keys
a list must contain at least one login
the single-login shorthand needs a single-portal tpa_name

What happens to the logins

They are removed from the body before it is stored. request_dump on /task-status and /eligibility-result does not contain them.
They are not written to logs. The username is recorded so a failed login can be traced to the account that was used; the password never is.
They are used for this task and then discarded. Nothing is updated on the clinic's stored configuration.

A wrong password behaves the way it does for stored logins: the check for that portal fails with an invalid-credentials outcome, and the rest of a search-all carries on. See Failures for the shape. Because the login came from your request, there is nothing for Mantys support to correct on our side; fix it at the source and send the next request.

Bulk requests

POST /bulk/create-tasks accepts the same field on each item of the list, with the same shapes and rules. Each item's logins apply to that item only.

On this page