Create a Bulk Request

post

/admin/v1/Bulk

Request

Supported Media Types
Header Parameters
Body ()
Root Schema : Bulk
Type: object
Make bulk requests to create, replace, update, delete resources of any type. Enables clients to send a potentially large collection of resource operations in a single request. This REST API is SCIM compliant.
Show Source
  • Operations
    The body of an HTTP PATCH request MUST contain the attribute "Operations", whose value is an array of one or more patch operations.
  • schemas
    SCIM++ Properties:
    • caseExact: false
    • idaasSearchable: false
    • multiValued: true
    • mutability: readWrite
    • required: true
    • returned: default
    • type: string
    • uniqueness: none
    REQUIRED. The schemas attribute is an array of strings which allows introspection of the supported schema version for a SCIM representation as well any schema extensions supported by that representation. Each string value must be a unique URI. This specification defines URIs for the User, Group, and a standard \"enterprise\" extension. All representations of the SCIM schema MUST include a non-zero value array with value(s) of the URIs supported by that representation. Duplicate values MUST NOT be included. Value order is not specified and MUST not impact behavior.
Nested Schema : Operations
Type: array
The body of an HTTP PATCH request MUST contain the attribute "Operations", whose value is an array of one or more patch operations.
Show Source
Nested Schema : schemas
Type: array
SCIM++ Properties:
  • caseExact: false
  • idaasSearchable: false
  • multiValued: true
  • mutability: readWrite
  • required: true
  • returned: default
  • type: string
  • uniqueness: none
REQUIRED. The schemas attribute is an array of strings which allows introspection of the supported schema version for a SCIM representation as well any schema extensions supported by that representation. Each string value must be a unique URI. This specification defines URIs for the User, Group, and a standard \"enterprise\" extension. All representations of the SCIM schema MUST include a non-zero value array with value(s) of the URIs supported by that representation. Duplicate values MUST NOT be included. Value order is not specified and MUST not impact behavior.
Allowed Values: [ "urn:ietf:params:scim:api:messages:2.0:BulkRequest" ]
Show Source
Nested Schema : Bulk-Operations
Type: object
Defines operations within a bulk request. Each operation corresponds to a single HTTP request against a resource endpoint.
Show Source
  • SCIM++ Properties:
    • type: string
    The transient identifier of a newly created resource that is unique within a bulk request and is created by the client. The bulkId serves as a surrogate resource ID that enables clients to uniquely identify newly created resources in the response. It also enables clients to cross reference new resources in and across operations within a bulk request. REQUIRED when the method is POST.
  • data
    SCIM++ Properties:
    • type: object
    The resource data as it would appear for a single POST, PUT, or PATCH resource operation. REQUIRED in a request when the method is POST, PUT, or PATCH.
  • Allowed Values: [ "POST", "PUT", "PATCH", "DELETE" ]
    SCIM++ Properties:
    • required: true
    • type: string
    The HTTP method of the current operation. Possible values are: 'POST', 'PUT', 'PATCH', or 'DELETE'.
  • SCIM++ Properties:
    • required: true
    • type: string
    The resource's relative path to the SCIM service provider's root. If the method is POST, the value must specify a resource type endpoint, such as: /Users or /Groups. All other method values must specify the path to a specific resource, such as /Users/2819c223-7f76-453a-919d-413861904646.
Nested Schema : data
Type: object
SCIM++ Properties:
  • type: object
The resource data as it would appear for a single POST, PUT, or PATCH resource operation. REQUIRED in a request when the method is POST, PUT, or PATCH.
Back to Top

Response

Supported Media Types

201 Response

Request successful. Bulk operations have been processed.
Body ()
Root Schema : Bulk
Type: object
Make bulk requests to create, replace, update, delete resources of any type. Enables clients to send a potentially large collection of resource operations in a single request. This REST API is SCIM compliant.
Show Source
  • Operations
    The body of an HTTP PATCH request MUST contain the attribute "Operations", whose value is an array of one or more patch operations.
  • schemas
    SCIM++ Properties:
    • caseExact: false
    • idaasSearchable: false
    • multiValued: true
    • mutability: readWrite
    • required: true
    • returned: default
    • type: string
    • uniqueness: none
    REQUIRED. The schemas attribute is an array of strings which allows introspection of the supported schema version for a SCIM representation as well any schema extensions supported by that representation. Each string value must be a unique URI. This specification defines URIs for the User, Group, and a standard \"enterprise\" extension. All representations of the SCIM schema MUST include a non-zero value array with value(s) of the URIs supported by that representation. Duplicate values MUST NOT be included. Value order is not specified and MUST not impact behavior.
Nested Schema : Operations
Type: array
The body of an HTTP PATCH request MUST contain the attribute "Operations", whose value is an array of one or more patch operations.
Show Source
Nested Schema : schemas
Type: array
SCIM++ Properties:
  • caseExact: false
  • idaasSearchable: false
  • multiValued: true
  • mutability: readWrite
  • required: true
  • returned: default
  • type: string
  • uniqueness: none
REQUIRED. The schemas attribute is an array of strings which allows introspection of the supported schema version for a SCIM representation as well any schema extensions supported by that representation. Each string value must be a unique URI. This specification defines URIs for the User, Group, and a standard \"enterprise\" extension. All representations of the SCIM schema MUST include a non-zero value array with value(s) of the URIs supported by that representation. Duplicate values MUST NOT be included. Value order is not specified and MUST not impact behavior.
Allowed Values: [ "urn:ietf:params:scim:api:messages:2.0:BulkRequest" ]
Show Source
Nested Schema : Bulk-Operations
Type: object
Defines operations within a bulk request. Each operation corresponds to a single HTTP request against a resource endpoint.
Show Source
  • SCIM++ Properties:
    • type: string
    The transient identifier of a newly created resource that is unique within a bulk request and is created by the client. The bulkId serves as a surrogate resource ID that enables clients to uniquely identify newly created resources in the response. It also enables clients to cross reference new resources in and across operations within a bulk request. REQUIRED when the method is POST.
  • data
    SCIM++ Properties:
    • type: object
    The resource data as it would appear for a single POST, PUT, or PATCH resource operation. REQUIRED in a request when the method is POST, PUT, or PATCH.
  • Allowed Values: [ "POST", "PUT", "PATCH", "DELETE" ]
    SCIM++ Properties:
    • required: true
    • type: string
    The HTTP method of the current operation. Possible values are: 'POST', 'PUT', 'PATCH', or 'DELETE'.
  • SCIM++ Properties:
    • required: true
    • type: string
    The resource's relative path to the SCIM service provider's root. If the method is POST, the value must specify a resource type endpoint, such as: /Users or /Groups. All other method values must specify the path to a specific resource, such as /Users/2819c223-7f76-453a-919d-413861904646.
Nested Schema : data
Type: object
SCIM++ Properties:
  • type: object
The resource data as it would appear for a single POST, PUT, or PATCH resource operation. REQUIRED in a request when the method is POST, PUT, or PATCH.

401 Response

The supplied credentials, if any, are not sufficient to access the resource.

500 Response

We couldn't return the representation due to an internal server error.
Back to Top

Examples

The following example shows how to process a bulk request that consists of one or more operations by submitting a POST request on the REST resource using cURL. For more information about cURL, see Use cURL.

cURL Command

Note:

The command in this example uses the URL structure https://tenant-base-url/resource-path, where tenant-base-url represents the Identity Service URL, and the resource path represents the Identity Service API. See Send Requests for the appropriate URL structure to use.
curl
-X POST
-H "Content-Type:application/scim+json"
-H "Authorization: Bearer <Access Token Value>"
https://tenant-base-url/admin/v1/Bulk

Example of Request Body

The following shows an example of the request body in JSON format:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
    ],
    "Operations": [
        {
            "method": "PUT",
            "path": "/Groups/f876e0326b094da284f10551facf9d79",
            "data": {
                "displayname": "Rol2",
                "members": [
                    {
                        "value": "faa508c8788e4e60aed151248e9a1024",
                        "type": "User"
                    }
                ],
                "schemas": [
                    "urn:ietf:params:scim:schemas:core:2.0:Group",
                    "urn:ietf:params:scim:schemas:oracle:idcs:extension:group:Group"
                ]
            }
        },
        {
            "method": "PUT",
            "path": "/UserStatusChanger/0d831bb391ab455096b7c9e56f77cfb0",
            "data": {
                "active": false,
                "schemas": [
                    "urn:ietf:params:scim:schemas:oracle:idcs:UserStatusChanger"
                ]
            }
        },
        {
            "method": "PATCH",
            "path": "/Groups/a94ff7dac4b94a1697c7fc37f2a661c2",
            "data": {
                "schemas": [
                    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
                ],
                "Operations": [
                    {
                        "op": "replace",
                        "path": "displayName",
                        "value": "Role_Replaced_Name"
                    }
                ]
            }
        },
        {
            "method": "DELETE",
            "path": "/Groups/2ec3ba4c76e241b89f1683a410aec8c6"
        },
        {
            "method": "POST",
            "path": "/Groups",
            "bulkId": "ukid_group",
            "data": {
                "displayname": "Finance Admin",
                "members": [
                    {
                        "value": "72584598d0e44924aefadd4240d1711c",
                        "type": "User"
                    }
                ],
                "urn:ietf:params:scim:schemas:oracle:idcs:extension:group:Group": {
                    "email": "finadmin@example.com",
                    "description": "Finance Administrator Group."
                },
                "schemas": [
                    "urn:ietf:params:scim:schemas:core:2.0:Group",
                    "urn:ietf:params:scim:schemas:oracle:idcs:extension:group:Group"
                ]
            }
        },
        {
            "method": "DELETE",
            "path": "/Users/ee64f86b033447b0afa40b7634a33e7b"
        },
        {
            "method": "POST",
            "path": "/Users",
            "bulkId": "ukid_user",
            "data": {
                "schemas": [
                    "urn:ietf:params:scim:schemas:core:2.0:User",
                    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
                ],
                "userName": "user@example.com",
                "name": {
                    "givenName": "User GN",
                    "familyName": "User FN",
                    "formatted": "Formatted name"
                },
                "displayName": "Dow Jensen",
                "password": "Welc0me@1",
                "active": true,
                "emails": [
                    {
                        "value": "bjensen@example.com",
                        "type": "work",
                        "primary": true
                    },
                    {
                        "value": "Dow@jensen.org",
                        "type": "home"
                    }
                ]
            }
        }
    ]
}

Example of Response Body

The following example shows the contents of the response body in JSON format:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkResponse"
    ],
    "Operations": [
        {
            "location": "http://tenant-base-url/admin/v1/Groups/57c6c6ea3325460e8370f77ffc13a167",
            "method": "POST",
            "bulkId": "ukid_group",
            "status": "201"
        },
        {
            "location": "https://tenant-base-url/admin/v1/Users/c1698026794a4802977f7c23930a493f",
            "method": "POST",
            "bulkId": "ukid_user",
            "status": "201"
        },
        {
            "location": "https://tenant-base-url/admin/v1/Groups/f876e0326b094da284f10551facf9d79",
            "method": "PUT",
            "status": "200"
        },
        {
            "location": "https://tenant-base-url/admin/v1/Groups/a94ff7dac4b94a1697c7fc37f2a661c2",
            "method": "PATCH",
            "status": "200"
        },
        {
            "location": "https://tenant-base-url/admin/v1/Users/ee64f86b033447b0afa40b7634a33e7b",
            "method": "DELETE",
            "status": "204"
        },
        {
            "location": "https://tenant-base-url/admin/v1/UserStatusChanger/0d831bb391ab455096b7c9e56f77cfb0",
            "method": "PUT",
            "status": "200"
        },
        {
            "location": "https://tenant-base-url/admin/v1/Groups/2ec3ba4c76e241b89f1683a410aec8c6",
            "method": "DELETE",
            "status": "204"
        }
    ]
}

Additional Example of Request Body

A client can, within one bulk operation, create a new User, create a new Group, and add the newly created User to the newly created Group. To add the new User to the Group, the client must use the surrogate id attribute, bulkId, to reference the User. The bulkId attribute value must be prepended with the literal bulkId, for example, if the bulkId is qwerty, then the value is bulkId:qwerty. Oracle Identity Cloud Service replaces the string bulkId:qwerty with the permanent resource ID after it is created. To create multiple distinct requests, each with their own bulkId, the client specifies different bulkId values for each separate request. The following example creates a User with the userName of Alice and a Group with displayName with a value of Tour Guides with Alice as a member. Notice that each operation has its own bulkId value. However, the second operation (whose bulkId is ytrewq) refers to the bulkId of qwerty to add Alice to the new Tour Guides group.

Note:

If you create users using bulk request, you can provide unhashed plain text password, hashed format password, or no password in the request body. See Create a User.
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [{
            "method": "POST",
            "path": "/Users",
            "bulkId": "qwerty",
            "data": {
                "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
                "userName": "Alice",
                "emails": [
                    {
                        "verified": false,
                        "type": "recovery",
                        "primary": false,
                        "value": "alice@example.com"
                    }

                    ,
                    {
                        "verified": false,
                        "type": "home",
                        "primary": true,
                        "value": "alice@example.com"
                    }

                ],
                "name":
                        {
                            "honorificPrefix": "dr",
                            "honorificSuffix": "suff",
                            "givenName": "Alice",
                            "middleName": "W",
                            "familyName": "Gold",
                            "formatted": "dr Alice W Gold suff"
                        }
            }
        },
        {
            "method": "POST",
            "path": "/Groups",
            "bulkId": "ytrewq",
            "data": {
                "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
                "displayName": "Tour Guides",
                "members": [
                    {
                        "type": "User",
                        "value": "bulkId:qwerty"
                    }

                ]
            }
        }
    ]
}

Example Response Body

In the example, the Alice User resource has an id of b618a0c8c5954ad384925ce43aabdeef and the Tour Guides Group has an id of 8fb871bd1f1548928ea049911bb0476b.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkResponse"
    ],
    "Operations": [
        {
            "location": "https://tenant-base-url/admin/v1/Users/b618a0c8c5954ad384925ce43aabdeef",
            "method": "POST",
            "bulkId": "qwerty",
            "status": "201"
        }

        ,
        {
            "location": "https://tenant-base-url/admin/v1/Groups/8fb871bd1f1548928ea049911bb0476b",
            "method": "POST",
            "bulkId": "ytrewq",
            "status": "201"
        }

    ]
}

A subsequent GET request on the /Bulk endpoint for the Tour Guides Group (with an id of 8fb871bd1f1548928ea049911bb0476b) returns the following, with Alice's id as the value for the members in the Group Tour Guides:

{
    "displayName": "Tour Guides",
    "id": "8fb871bd1f1548928ea049911bb0476b",
    "members": [
        {
            "value": "b618a0c8c5954ad384925ce43aabdeef",
            "type": "User",
            "display": "Alice Gold",
            "name": "Alice",
            "$ref": "https://<IDCS-Service-Instance>/admin/v1/Users/b618a0c8c5954ad384925ce43aabdeef"
        }

    ]
}

Extensions that include references to other resources MUST be handled in the same way by the service provider. The following example uses the bulkId attribute within the enterprise extension managerId attribute.

Example of Request Body

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [{
            "method": "POST",
            "path": "/Users",
            "bulkId": "qwerty",
            "data": {
                "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
                "userName": "Alice",
                "emails": [
                    {
                        "verified": false,
                        "type": "recovery",
                        "primary": false,
                        "value": "alice@example.com"
                    },
                    {
                        "verified": false,
                        "type": "home",
                        "primary": true,
                        "value": "alice@example.com"
                    }
                ],
                "name":
                        {
                            "honorificPrefix": "dr",
                            "honorificSuffix": "suff",
                            "givenName": "Alice",
                            "middleName": "W",
                            "familyName": "Gold",
                            "formatted": "dr Alice W Gold suff"
                        }
            }
        },
        {
            "method": "POST",
            "path": "/Users",
            "bulkId": "ytrewq",
            "data": {
                "schemas": [
                    "urn:ietf:params:scim:schemas:core:2.0:User",
                    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
                ],
                "userName": "Bob",
                "emails": [
                    {
                        "verified": false,
                        "type": "recovery",
                        "primary": false,
                        "value": "bob@example.com"
                    },
                    {
                        "verified": false,
                        "type": "home",
                        "primary": true,
                        "value": "bob@example.com"
                    }
                ],
                "name":
                        {
                            "honorificPrefix": "dr",
                            "honorificSuffix": "suff",
                            "givenName": "Bob",
                            "middleName": "W",
                            "familyName": "Gold",
                            "formatted": "dr Bob W Gold suff"
                        },
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                    "manager":
                            {
                                "value": "bulkId:qwerty"
                            }
                }
            }
        }
    ]
}

Response Body

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkResponse"
    ],
    "Operations": [
        {
            "location": "https://tenant-base-url/admin/v1/users/ef34981baf154ee381aa7d1d6efac8eb",
            "method": "POST",
            "bulkId": "qwerty",
            "status": "201"
        },
        {
            "location": "https://tenant-base-url/admin/v1/Users/eee80c1fe7c749aab1099d6d513a491e",
            "method": "POST",
            "bulkId": "ytrewq",
            "status": "201"
        }
    ]
}
Back to Top