This page details how the SCIM component supports bulk requests, including the expected format of requests and details of the responses returned.
Format of request data
A request to the bulk endpoint has the schema urn:ietf:params:scim:api:messages:2.0:BulkRequest. The request must include an array of operations to be processed by the endpoint. The request can optionally include a failOnErrors property stating the maximum number of errors that can occur before the endpoint stops processing the operations.
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"failOnErrors": 1,
"operations": [
...
{
"method": "DELETE",
"path": "/Users/b7c14771-226c-4d05-8860-134711653041",
}
...
]
}
An item in the operations array follows the structure of the individual requests that can be made to other SCIM endpoints. The BULK endpoint supports PATCH, DELETE, POST and PUT operations.
Example operation data
{
"method": "DELETE",
"path": "/Users/b7c14771-226c-4d05-8860-134711653041",
}
{
"method": "PUT",
"path": "/Users/b7c14771-226c-4d05-8860-134711653041",
"data": {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "b7c14771-226c-4d05-8860-134711653041",
"userName": "Bob"
}
}
{
"method": "POST",
"path": "/Users",
"bulkId": "qwerty",
"data": {
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "HR"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userName": "Alice"
}
}
{
"method": "PATCH",
"path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"data": {
"schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
"operations": [
{
"op": "remove",
"path": "nickName"
},
{
"op": "add",
"path": "userName",
"value": "Dave"
}
]}
}
Response format
A response from the BULK endpoint will return individual responses for each operation processed. If the endpoint processed the operations successfully then the status code of the response will be 200 OK. This is true even if there were errors in the individual operations (e.g 400 Bad Request).
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [
{
"location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
"method": "POST",
"bulkId": "qwerty",
"status": "201"
},
{
"location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT",
"status": "200"
},
{
"location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH",
"status": "200"
},
{
"location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE",
"status": "204"
}
]
}
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
"Operations": [
{
"method": "POST",
"bulkId": "qwerty",
"status": "400",
"response": {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType": "invalidSyntax"
"detail": "Request is unparsable, syntactically incorrect, or violates schema.",
"status": "400"
}
},
{
"location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
"method": "PUT",
"status": "404",
"response": {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":
"...",
"status": "405"
}
},
{
"location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"method": "PATCH",
"status": "404",
"response": {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "...",
"status": "409"
}
},
{
"location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
"method": "DELETE",
"status": "404",
"response": {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "Resource does not exist.",
"status": "404"
}
}
]
}
BULK endpoint configuration
The BULK endpoint supports configuration to restrict the load on the server by limiting the requests the endpoint will accept. To update the max request size and max operation count, set the BulkOptions in the ScimServiceProviderConfigOptions passed in to the AddScimServiceProvider call. The default limits are 1000 max operations and maximum payload size of 1MB.
Using BulkIds
BulkIds are supported within the SCIM component. In the following example the POST operation has the property bulkId with a value of qwerty, and the PATCH operation data refers to that BulkId by using the syntax bulkId:qwerty. Once the POST operation is processed, the PATCH operation's reference to the bulkId will be replaced with the id generated from the operation.
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"operations": [
{
"method": "POST",
"path": "/Users",
"bulkId": "qwerty",
"data": {
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "HR"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userName": "Alice"
}
},
{
"method": "PATCH",
"path": "/Groups/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
"data": {
"schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
"operations": [
{
"op": "add",
"path": "members",
"value": [{
"value": "bulkId:qwerty",
"type": "User"
}]
}
]
}
}
]
}
Circular references
The SCIM component doesn't currently support circular references within bulk requests.