Raise an access request

Creates one request per person named in requested_for.

Fan-out. One call naming N people becomes N independent requests sharing a bulk_id. Each child has its own id, request_id and requested_for, and each is approved independently — so two people named in one call can get different outcomes.

Idempotent. Replaying the same external_ref returns 200 with idempotent_replay: true and the existing requests. It never creates a second. The replay is checked first, so a retry gets its requests even if the form, the application or a person changed after the first call. A replay must name the same application and the same people (see 400).

Atomic. If any id in requested_for does not resolve, the whole call fails and nothing is created — there is no partial fan-out.

Identity is always a Zluri user id. An email is rejected with USER_ID_REQUIRED; fetch ids from POST /v2/users and store them against your own users.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required
length ≥ 1

The originating ticket id. Idempotency key: replaying it returns the existing request.

string
length ≤ 64

Optional free text naming your system, recorded for audit only, and read back under the same name on GET /ext/access/requests/{id}. It is not the request's source, which this API always stamps as external_api: access control reads source, and a field the caller sets cannot be a field a guard trusts.

string
^[a-fA-F0-9]{24}$

Required unless this is a custom app. An inactive application, which the catalogue does not list, is refused.

string
length ≥ 1

Custom app only. Required with app_url when app_id is absent.

string
length ≥ 1
^([hH][tT][tT][pP][sS]?://|[wW][wW][wW]\.)[^\s]+$

Custom app only, and it must look like a URL — https://example.com or www.example.com.

string
required
^[a-fA-F0-9]{24}$

Zluri user id. Never an email. Must be active: a person who is inactive, suspended or archived gets 400 USER_NOT_ACTIVE.

requested_for
array of strings
required
length between 1 and 50

Zluri user ids. N entries fan out into N independent requests sharing a bulk_id.

requested_for*
field_values
object
required

Keyed by field_id from the form schema. Besides the fields below, only the form's enabled custom fields are kept, each under its field_id; any other key is ignored. A field sent as null counts as not provided, as if it were left out.

Refused with 400 VALIDATION_ERROR: other_subscription_users and requested_for (not_accepted_here; name people in the top-level requested_for), and request_role or license_name on a custom app (not_accepted_here).

Checked against the application's form (the form schema for app_id, or the generic form for a custom app), field by field. Every problem is reported at once, in the same response as any field refused above:

  • a mandatory field must have a value; blank or an empty list counts as missing (required);
  • a select or radio takes one of its options (invalid_option); one with an options_ref is checked against that list instead;
  • a bool takes Yes or No (invalid_option);
  • a date takes YYYY-MM-DD or an ISO 8601 date-time, and must be a real date (invalid_format);
  • a number takes a number (invalid_type);
  • no custom field takes an object or a list (invalid_type); the built-in subscription_duration takes {period, frequency}.

Not checked: licenses_required (it defaults to 1), and requested_for, app_name and app_url, which the body carries.

date-time

The value a form-schema endpoint issued, echoed back unchanged, so a form that changed underneath you is detected before the request is raised.

Compared as an instant, not as text. This is the form config's last-modified stamp, so 2026-09-22T12:19:41.188Z, 2026-09-22T12:19:41.188+00:00, 2026-09-22T12:19:41.188000Z and 2026-09-22T17:49:41.188+05:30 are all the same version and all accepted. Round-tripping it through a datetime type is safe.

⚠ Format is normalized; precision is not. A value truncated to whole seconds names a different instant and is refused as stale — two saves a second apart are two versions. If your platform stores timestamps at second precision (ServiceNow's GlideDateTime does), keep this value as a string instead.

Omitting it means I did not read the form, not I read the current one: the check is skipped entirely and the request is accepted.

integer
1 to 10000

Seat count, and meaningful only for a custom application (app_name + app_url).

For a Zluri app_id it must be 1 or omitted: every entry in requested_for becomes its own single-person request, so the seat count always equals one and anything else is refused with VALIDATION_ERROR.

Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json