POST-ing to Create Objects

You create objects in the Buzz API using the POST method. Buzz will automatically restrict you to objects in your Account and for which you have permission to write. POST requests will be validated for presence of required fields, field validity, referential integrity, etc.

📘

Migration Notes from 0.5 API

• Object duplication is not yet supported in the 2.0 API
• Error feedback is now available at the field level, and multiple errors field validation errors will be returned in a single response.
• Bulk POST for multiple object creation is now supported

Most problems that occur when POSTing are the result of missing fields or field validation, so make sure to read the error messages if your API call is failing.

Basic POST syntax

curl -X POST "[host]/rest/v2/[resource]" -b cookies.txt -d '{"field_name":"foo", "active":1}' -H "Content-Type: application/json"

After a successful POST, the Buzz API response will include the entire object that was created including automatic fields id, create_date, update_date and account_id. A pseudo example is shown below.

{
	"id": 2868,
	"field_name": "foo",
	"create_date": "2020-08-28 08:29:22",
	"update_date": "2020-08-28 08:29:22",
	"active": true,
	"alternative_id": null,
	"notes": null,
	"name": null,
	"account_id": 1
}

Error responses

In the case of field validation errors the API will return an http 400 code and a JSON error object keyed by the field(s) that encountered the errors and including one or more error strings in a list. This is helpful if you would like to indicate in a UI which fields need attention from the user. In the pseudo-example below the error within the modules field is shown nested within that object's hierarchy, whereas the alternative_id error is unnested.

{
	"modules": {
		"geo": {
			"all": {
				"foo": ["\"foo\" is not a valid choice."]
			}
		}
	},
	"alternative_id": ["Not a valid string."]
}

Bulk POST

For certain objects, you can create multiple objects in a single POST by using the dedicated /bulk resource corresponding to the object you wish to create. For example, to create multiple Roles in a single transaction, you can POST to /roles/bulk.

The syntax is simply a list of objects POSTed to the respective bulk endpoint as shown below:

curl -X POST "[host]/rest/v2/[resource]/bulk" -b cookies.txt 
    -d '[{"field_name":"foo1", "active":1},{"field_name":"foo2", "active":1}]' 
    -H "Content-Type: application/json"

On a successful bulk POST the API will respond with a list of all the objects created. If any errors are encountered the entire operation will fail and the response will provide feedback.