Create whitelistings in a batch

POST /organizations/{organizationId}/contexts/sign-in/{contextId}/whitelistings/batch-create

Permission: Sign In › Sign In Modules › Whitelisting (Write). See API permissions.

The response has one result per device, in the order sent. Each device gets one of three outcomes:

• CREATED: the device had no active whitelisting and got a new one.
• UPDATED: the device already had an active whitelisting. It keeps it, with the new name, description and tags. Its end date changes only when the item has a validUntil.
• REJECTED: the rules for whitelistings of the context refuse the device. reason carries the errorCode SIGN_IN_WHITELISTING_REFUSED.

If one item breaks a validation rule, or a MAC address is listed twice, the whole request returns 400 and nothing is created. Repeating a request updates what the first run created.

Request

Parameter	In	Type	Required	Description
organizationId	Path	string	Yes	The Organization ID of the API key. Any other ID returns 404.
contextId	Path	string	Yes	The ID of a Sign-In Context of the Organization. Any other ID returns 404.
whitelistings	Body	object[]	Yes	The whitelistings, 1 to 500, each MAC address once.
whitelistings[].mac	Body	string	Yes	The MAC address of the device, aa:bb:cc:dd:ee:ff, in upper or lower case.
whitelistings[].name	Body	string	Yes	A name that describes the device, 2 to 100 characters.
whitelistings[].description	Body	string	No	The description, up to 200 characters.
whitelistings[].tags	Body	string[]	No	Up to 50 tags, each 2 to 30 characters. Stored in lower case.
whitelistings[].validUntil	Body	string (date)	No	The last day the whitelisting is valid, YYYY-MM-DD, today or later and before 2099-12-31. Left out, a new whitelisting does not expire, and an existing one keeps its end date.
tagsFromDescription	Body	boolean	No	true to also tag each whitelisting with the words of its description, in lower case; otherwise false. Default false.
batchTimeTag	Body	boolean	No	true to also tag each whitelisting with the date and time of the batch in the time zone of the platform, for example 2026-09-28 15:33:36; otherwise false. Default false.

Each item follows the Validation rules of a single whitelisting.

With tagsFromDescription, the description is split at each space. The characters ( ) " + are removed from each word, and words shorter than 2 characters are skipped.

Request example

cURL

curl -X POST "$API_BASE_URL/organizations/$ORGANIZATION_ID/contexts/sign-in/$CONTEXT_ID/whitelistings/batch-create" \
  -H "Authorization: Bearer $NCP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "whitelistings": [
      { "mac": "02:00:5E:10:AB:01", "name": "Lobby display", "description": "Signage lobby" },
      { "mac": "02:00:5E:10:AB:02", "name": "Reception printer", "validUntil": "2027-06-30" }
    ],
    "tagsFromDescription": true,
    "batchTimeTag": true
  }'

Response

200 with one result per device.

Field	Type	Description
results	object[]	One entry per device sent, in the order sent.
results[].mac	string	The MAC address of the device, in lower case.
results[].outcome	string	CREATED, UPDATED or REJECTED. New values can be added within v2.
results[].reason	object or null	Why the device was rejected: the errorCode SIGN_IN_WHITELISTING_REFUSED and a detail. null for CREATED and UPDATED.

Response example

200

{
  "results": [
    { "mac": "02:00:5e:10:ab:01", "outcome": "UPDATED", "reason": null },
    { "mac": "02:00:5e:10:ab:02", "outcome": "CREATED", "reason": null }
  ]
}

Errors

Status	errorCode	When
400	VALIDATION_FAILED	The list is empty or has more than 500 items, or an item breaks a validation rule. errors names each field, for example whitelistings[3].mac. Nothing is created.
400	VALIDATION_FAILED	A MAC address is listed twice, in any case: errors names the second one with the code DUPLICATE. Nothing is created.
404	RESOURCE_NOT_FOUND	organizationId is not the Organization of the API key, or contextId is not one of its Sign-In Contexts.

Errors common to all operations are in Errors.