Identity Cloud

Create

There are two ways to create a resource: HTTP POST or HTTP PUT.

To create a resource using POST, perform an HTTP POST with the query string parameter _action=create and the JSON resource as a payload. The service creates the identifier if not specified:

POST /users?_action=create HTTP/1.1
Host: example.com
Accept: application/json
Content-Length: ...
Content-Type: application/json
{ JSON resource }

To create a resource using PUT, perform an HTTP PUT with the case-sensitive identifier for the resource in the URL path and the JSON resource as a payload. Optionally, include the If-None-Match: * header to prevent overwriting an existing object:

PUT /users/some-id HTTP/1.1
Host: example.com
Accept: application/json
Content-Length: ...
Content-Type: application/json
If-None-Match: *
{ JSON resource }

The _id and the content of the resource depend on the endpoint. The service is not required to use the _id the client provides. The response to the create request indicates the resource location as the value of the Location header.

  • If you do include the If-None-Match: * header, the request creates the object if it does not exist or fails if the object does exist.

  • If you do not include the If-None-Match: * header, the request creates the object if it does not exist or updates the object if it does exist.

  • If you include the If-None-Match header with any value other than *, the response is an HTTP 400 Bad Request error. For example, creating an object with If-None-Match: revision returns a bad request error.

Parameters

You can use the following query string parameters:

Parameter Description

_fields=field[,field...]

Return only the specified fields in the body of the response.

The field values are JSON pointers. For example, if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value".

If the field is left blank, the endpoint returns all default values.

_prettyPrint=true

Format the body of the response.

Copyright © 2010-2024 ForgeRock, all rights reserved.