15.7Batch operations

Twelve endpoints apply up to 100 changes of one kind in a single request:

{type} is users, groups, organization-units or objects. Each batch needs the same permission as the single-object operation it repeats, for example ad:users:create for a user create batch. The batch endpoints are available only on the machine surface.

The request bodies reuse the single-object bodies:

{ "items": [ { "name": "Jane Doe", "path": "OU=Staff,DC=example,DC=com", "samAccountName": "jdoe" } ] }

{ "items": [ { "id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301", "data": { "replace": { "department": "Finance" } } } ] }

{ "ids": [ "3f2504e0-4f89-11d3-9a0c-0305e82c3301", "9b7c1d0a-2e4f-4c55-8a1b-7f3e6d2c1a09" ] }

How a batch runs

• Each item goes through every control a single request does — validation, permissions, attribute rules, policies, auditing. A batch is not a way around anything.
• Items run one after another, in the order given. Each one writes its own row in the operations log, and the rows share a batch ID so you can find them together. Approvers and notification recipients get one notification for the batch, not one per item.
• A batch is not transactional. If item 50 fails, items 1 to 49 stay applied, and the remaining items are still attempted.

Reading the result

{
  "batchId": "c2a9e7f1-0b3d-4d8e-9a6c-5f1e2b3c4d5e",
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "items": [
    { "index": 0, "succeeded": true, "entityId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301", "distinguishedName": "CN=Jane Doe,OU=Staff,DC=example,DC=com" },
    { "index": 1, "succeeded": true, "entityId": "9b7c1d0a-2e4f-4c55-8a1b-7f3e6d2c1a09", "distinguishedName": "CN=John Roe,OU=Staff,DC=example,DC=com" },
    { "index": 2, "succeeded": false, "errorCode": "AD.Attributes.ValidationError", "errorMessage": "…" }
  ]
}

Important: Never read a 2xx status as "everything was applied". Check failed, or treat 207 as "look inside". index matches the position of the item in your request.

When a batch is refused or queued as a whole

A batch is refused before any item runs when it is empty (DirectoryBatch.Empty), has more than 100 items (DirectoryBatch.TooManyItems), contains an item that fails validation, or repeats an operation that is disabled.

Approval is decided for the batch as a whole, from all of its items: the most sensitive item, any pinned item and every item's targets. If anything in it would have to wait, the whole batch is queued as one operation and answers 202; one approval then runs the whole batch. A batch never runs some items and queues others. A batch that would have to wait and carries passwords (such as a user create batch with passwords) is refused as a whole with 403 Agent.ApprovalImpossible.

Tip: Large batches are a common way to trip the volume brake. If your integration deletes more than about twenty objects an hour, discuss its supervision level and the brake's threshold with your administrator first.