curl --request POST \
--url 'https://api.scanova.io/multi-users/access-levels/' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"name": "Regional Support",
"permissions": [23, 24, 31]
}'
{
"id": 42,
"name": "Regional Support",
"slug": null,
"permissions": [
{ "id": 23, "code": "QR_CODE_CAN_VIEW", "name": "Can view QR Code", "description": "Allows viewing QR code details.", "is_boolean": true },
{ "id": 24, "code": "ANALYTICS_CAN_VIEW", "name": "Can view Analytics", "description": "Allows viewing analytics.", "is_boolean": true },
{ "id": 31, "code": "LEAD_GENERATION_CAN_VIEW", "name": "Can view Lead Lists", "description": "Allows viewing lead lists.", "is_boolean": true }
],
"is_custom": true
}
Shared Users & Roles
Create a custom role
POST /multi-users/access-levels/
POST
/
multi-users
/
access-levels
/
curl --request POST \
--url 'https://api.scanova.io/multi-users/access-levels/' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"name": "Regional Support",
"permissions": [23, 24, 31]
}'
{
"id": 42,
"name": "Regional Support",
"slug": null,
"permissions": [
{ "id": 23, "code": "QR_CODE_CAN_VIEW", "name": "Can view QR Code", "description": "Allows viewing QR code details.", "is_boolean": true },
{ "id": 24, "code": "ANALYTICS_CAN_VIEW", "name": "Can view Analytics", "description": "Allows viewing analytics.", "is_boolean": true },
{ "id": 31, "code": "LEAD_GENERATION_CAN_VIEW", "name": "Can view Lead Lists", "description": "Allows viewing lead lists.", "is_boolean": true }
],
"is_custom": true
}
Every shared user is assigned a role — Scanova’s dashboard calls these “access levels” internally, and the same term appears throughout this endpoint. Use this endpoint to look up available roles before inviting a teammate via
POST /multi-users/, or to create a custom role from your own systems.
This endpoint was not previously documented. It requires an API key with
MANAGEMENT_API (or MANAGEMENT_API_SANDBOX) quota — see the API overview. For what each role actually grants a teammate, see the human-facing Roles & permissions guide — this page only documents the wire format.Creating custom roles requires a dedicated quota on the account’s plan (the same gate that hides the dashboard’s Roles tab on unsupported plans — see Custom roles are plan-gated). A 403 here means the plan doesn’t include it.
curl --request POST \
--url 'https://api.scanova.io/multi-users/access-levels/' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"name": "Regional Support",
"permissions": [23, 24, 31]
}'
{
"id": 42,
"name": "Regional Support",
"slug": null,
"permissions": [
{ "id": 23, "code": "QR_CODE_CAN_VIEW", "name": "Can view QR Code", "description": "Allows viewing QR code details.", "is_boolean": true },
{ "id": 24, "code": "ANALYTICS_CAN_VIEW", "name": "Can view Analytics", "description": "Allows viewing analytics.", "is_boolean": true },
{ "id": 31, "code": "LEAD_GENERATION_CAN_VIEW", "name": "Can view Lead Lists", "description": "Allows viewing lead lists.", "is_boolean": true }
],
"is_custom": true
}
string
required
Role name. Must be unique among this account’s roles — a duplicate returns a 400 with
{"name": ["Can not create another user role with the same name."]}.array
required
Permission IDs to grant, from the
permissions[].id values in the list response above.To discover permission IDs, either read them off an existing role’s
permissions array (every account has at least the 6 system roles to inspect), or use List permission categories for the full, category-grouped catalog independent of any one role.Related
- List roles — the other operation on this same endpoint.
- Retrieve a role — look up a single role by id.
- List permission categories — the full permission catalog, independent of any one role.
- Invite a shared user — assign a role ID from this list when inviting or updating a teammate.
- Update a shared user — assign a role ID from this list when inviting or updating a teammate.
- Roles & permissions — the human-facing explanation of what each role grants, including the custom-roles plan gate.
- Shared users — the dashboard’s Users table where these roles are assigned via the UI.
Authorizations
Send your Management API key as the raw value of the Authorization header — no "Bearer " or "Token " prefix, and no other characters. Example: Authorization: YOUR_API_KEY. A header containing more than one space-separated part is rejected outright. Requests also require the request's Host header to be the management API host (e.g. api.scanova.io) — the same key sent to the regular API host will not authenticate.
Body
application/json
Response
201 - application/json
Custom role created. Requires the account's custom-roles plan quota.
Was this page helpful?