Requests and errors
How requests are shaped, how lists are paged and filtered, and what errors look like.
Records
Everything in the CRM is a record in a module. Standard modules are leads, contacts, accounts, deals, tasks, calls and meetings; custom modules work the same way. A record has a few fixed properties and a data map holding its fields.
| Property | Type | Description |
|---|---|---|
id | uuid | Set by Spartivo. |
name | string | The record's display name. |
ownerId | uuid or null | The user who owns the record. |
data | object | Field values keyed by field API name. Lookup fields hold the id of the related record. |
tags | string[] | Free-form labels. |
createdAt, updatedAt | date-time | Set by Spartivo. |
deletedAt | date-time or null | Set when the record is in the recycle bin. |
Responses can carry a few more properties than the examples in these docs show, such as tenantId and moduleId. New properties may be added over time, so read the ones you need and ignore the rest.
Paging and sorting
List endpoints take page (starting at 1) and pageSize (1 to 500, default 50) and return items with the total number of matches. Sort with sort and dir (asc or desc). sort accepts name, createdAt, updatedAt or any field API name; number fields sort as numbers, and records with an empty value come last.
curl "https://api.spartivo.com/api/v1/modules/deals/records?page=2&pageSize=100&sort=amount&dir=desc" \
-H "Authorization: Bearer wk_your_key"Filtering
Pass filters as a JSON array, URL-encoded. Every rule must match. Each rule has a field, an op and usually a value.
| Operator | Matches when the field… |
|---|---|
eq, neq | equals, or does not equal, the value |
contains, starts_with | contains, or begins with, the text (capital letters matter) |
gt, gte, lt, lte | is greater or less than the number or date |
in | is one of the values in a list |
is_null, not_null | is empty, or has any value (no value needed) |
curl -G "https://api.spartivo.com/api/v1/modules/deals/records" \
-H "Authorization: Bearer wk_your_key" \
--data-urlencode 'filters=[{"field":"stage","op":"eq","value":"negotiation"},{"field":"amount","op":"gte","value":50000}]'You can also pass q to search by name, ownerId to keep one owner's records, and tag to keep records with a tag.
Errors
Errors use standard HTTP status codes and a JSON body with a message you can show to a person.
| Status | Meaning |
|---|---|
400 | The request is not valid: a required property is missing, a value is not allowed, or a validation rule in the CRM rejected it. |
401 | The API key is missing or not valid. |
403 | The key's user does not have permission. |
404 | The record, module or other item does not exist, or the user cannot see it. |
409 | The request conflicts with existing data, for example a duplicate value in a unique field. |
500 | Something went wrong on our side. Safe to retry after a short wait. |
When the shape of the request is wrong, the body lists each problem with the path of the property.
{
"error": "validation_error",
"issues": [
{
"path": "name",
"message": "Required"
}
]
}