Docs »

API »

Endpoints »

Records

The records API can abstractly create, retrieve, update, upsert, search, and delete all records in Cerb from a single endpoint.

This endpoint target a specific record type as <uri> in the path.

Retrieve

GET /rest/records/<uri>/<id>.json

Retrieve a record dictionary.

Example

$out = $cerb->get($base_url . 'records/asset/1.json');

Create

POST /rest/records/<uri>/create.json

Create a new record.

Parameters

Field Type  
fields[] mixed required This field can be provided multiple times for each field to set. The field names are found on each record type.

Example

$postfields = [
    ['expand','custom_'],
    ['fields[email]','customer@cerb.example'],
    ['fields[is_banned]','0'],
    ['fields[custom_123]','Some value'],
];
$out = $cerb->post($base_url . 'records/address/create.json', $postfields);

Update

PUT /rest/records/<uri>/<id>.json

Update a record object.

Parameters

Field Type  
fields[] mixed required This field can be provided multiple times for each field to set. The field names are found on each record type.

Example

$postfields = [
    ['fields[is_private]','0'],
    ['fields[name]','Support'],
    ['fields[reply_personal]','Example Support Team'],
];
$out = $cerb->put($base_url . 'records/group/1.json', $postfields);

Upsert

PATCH /rest/records/<uri>/upsert.json

Update an existing record if matched, or create a new record otherwise.

Parameters

Field Type  
fields[] mixed required This field can be provided multiple times for each field to set. The field names are found on each record type.
query string The search query for detecting a match. This must return either 0 (create) or 1 (update) results. Anything else returns an error.

Example

$postfields = [
    ['fields[country]','United States'],
    ['fields[name]','Apple, Inc.'],
    ['fields[website]','https://apple.com'],
    ['query', 'name:"Apple, Inc."'],
];
$out = $cerb->patch($base_url . 'records/org/upsert.json', $postfields);

Search

GET /rest/records/<uri>/search.json

Search for matching records.

Parameters

Field Description Type
expand The keys to expand for each object as a comma-separated list string
limit The number of results to display per page integer
page The page of results to display given limit integer
q Filters to add using a search query string
subtotals[] Multiple subtotal sets can be returned string

expand

Includes additional information in the response. These options vary depending on the record type.

Field Description
custom_ Include custom field values for each ticket.
watchers Include watcher records for each ticket.

subtotals[]

Return subtotal results based on the given fields. These options vary depending on the record type.

Example

$query = http_build_query([
  'q' => 'mimetype:"image/png" size:>200kb sort:-size page:1',
]);

$out = $cerb->get($base_url . 
  'records/attachments/search.json?' .
  $query
);

Delete

DELETE /rest/records/<uri>/<id>.json

Delete a record.

Example

$out = $cerb->delete($base_url . 'records/call/1.json');

Links

You can create record links with the links field key in a create, update, or upsert request.

The value must be a context:id tuple identifying the record to link to.

The key can be provided multiple times to link multiple records. Be sure to append [] to the field key, like the example below.

Example

$postfields = [
    ['fields[links][]', 'org:123'],
    ['fields[links][]', 'ticket:456'],
];
$out = $cerb->put($base_url . 'records/task/1.json', $postfields);

You can remove record links by prefixing the tuple with a - (dash).

You may mix link additions and removals in the same request.

Example

$postfields = [
    ['fields[links][]', '-org:123'],
    ['fields[links][]', 'ticket:456'],
];
$out = $cerb->put($base_url . 'records/task/1.json', $postfields);