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

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.

## 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.

## 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:

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.