Add whitelist entries

Adds one or more users to the onboarding whitelist.

Each user must be identified by exactly one of:

national_id: Saudi national ID (10 digits)

external_reference: Your own reference for the user

Send an optional idempotency-key header to make the request safely
retryable — repeating the same key returns the original result.

How to read the response:

200 OK: your request was processed. Check summary.success and
summary.fail, and review failed_records for any entries that could
not be added (e.g. invalid identifier, already whitelisted). A 200 does
not mean every entry was added — always inspect the summary.

4xx / 5xx: your request could not be processed at all. Common reasons
are an invalid request body, missing permissions, or a temporary service
outage. The body contains error_code, error_message, and details.
You can safely retry 5xx responses.

curl --location --request POST 'https://api.staging.vrtx.sa/whitelist/' \ --header 'idempotency-key;' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "users": [ { "national_id": "1234567890", "external_reference": "ext-ref-001" } ] }'

{ "report_status": "PARTIAL_SUCCESS", "message": "2 of 3 entries added successfully", "summary": { "total": 0, "success": 0, "fail": 0 }, "failed_records": [ { "national_id": "string", "external_reference": "string", "error": "string" } ] }

Add whitelist entries

Request

Responses