SpartivoDocs
Open app
Get started
OverviewQuickstartAuthenticationRequests and errors
API reference
RecordsModules and fieldsFilesMessagingDocuments and e-signatureFunctionsWebhooks
Spartivo Script
IntroductionLanguage guideCRM and actionsBuilt-in functionsExamples
Get started

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.

PropertyTypeDescription
iduuidSet by Spartivo.
namestringThe record's display name.
ownerIduuid or nullThe user who owns the record.
dataobjectField values keyed by field API name. Lookup fields hold the id of the related record.
tagsstring[]Free-form labels.
createdAt, updatedAtdate-timeSet by Spartivo.
deletedAtdate-time or nullSet 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
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.

OperatorMatches when the field…
eq, neqequals, or does not equal, the value
contains, starts_withcontains, or begins with, the text (capital letters matter)
gt, gte, lt, lteis greater or less than the number or date
inis one of the values in a list
is_null, not_nullis 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.

StatusMeaning
400The request is not valid: a required property is missing, a value is not allowed, or a validation rule in the CRM rejected it.
401The API key is missing or not valid.
403The key's user does not have permission.
404The record, module or other item does not exist, or the user cannot see it.
409The request conflicts with existing data, for example a duplicate value in a unique field.
500Something 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"
    }
  ]
}
Previous← AuthenticationNextRecords →
On this page
RecordsPaging and sortingFilteringErrors