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

Records

Create, read, update and delete records in any module, standard or custom.

List records

GET/modules/{module}/records

Returns a page of records the key's user is allowed to see, newest changes first unless you sort.

Path parameters
modulestringrequired
The module's API name, for example leads, contacts, accounts, deals or one of your custom modules.
Query parameters
pageinteger
Page number, starting at 1.
pageSizeinteger
Records per page, 1 to 500. Default 50.
sortstring
name, createdAt, updatedAt or a field API name such as amount. Default updatedAt.
dirstring
asc or desc. Default desc.
qstring
Keep records whose name contains this text.
ownerIduuid
Keep one owner's records.
tagstring
Keep records that have this tag.
filtersJSON array
Rules such as [{"field":"status","op":"eq","value":"new"}]. See Filtering.
  • module.fields describes every field in the module, so one call gives you both the data and how to label it.
Request
curl "https://api.spartivo.com/api/v1/modules/leads/records?pageSize=2&sort=createdAt" \
  -H "Authorization: Bearer wk_your_key"
Response
{
  "items": [
    {
      "id": "a0d3bf2c-688d-42da-83e1-d5e57d3e990d",
      "ownerId": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
      "name": "Aisha Khan",
      "data": {
        "email": "aisha@example.com",
        "company": "Northwind Trading",
        "source": "whatsapp",
        "status": "new"
      },
      "tags": [
        "api"
      ],
      "score": 0,
      "createdAt": "2026-11-18T08:33:18.996Z",
      "updatedAt": "2026-11-18T08:33:18.996Z",
      "deletedAt": null,
      "owner": {
        "id": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
        "fullName": "Sara Khalifa"
      }
    }
  ],
  "total": 90,
  "page": 1,
  "pageSize": 2,
  "module": {
    "apiName": "leads",
    "label": "Lead",
    "pluralLabel": "Leads",
    "fields": [
      "…"
    ]
  }
}

Get a record

GET/records/{id}

Returns one record with its module, its owner and related summaries.

Path parameters
iduuidrequired
The record id.
  • Fields hidden from the key's user by their profile are left out of data.
Request
curl "https://api.spartivo.com/api/v1/records/a0d3bf2c-688d-42da-83e1-d5e57d3e990d" \
  -H "Authorization: Bearer wk_your_key"
Response
{
  "id": "a0d3bf2c-688d-42da-83e1-d5e57d3e990d",
  "ownerId": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
  "name": "Aisha Khan",
  "data": {
    "email": "aisha@example.com",
    "company": "Northwind Trading",
    "source": "whatsapp",
    "status": "new"
  },
  "tags": [
    "api"
  ],
  "score": 0,
  "createdAt": "2026-11-18T08:33:18.996Z",
  "updatedAt": "2026-11-18T08:33:18.996Z",
  "deletedAt": null,
  "module": {
    "apiName": "leads",
    "label": "Lead"
  },
  "owner": {
    "id": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
    "fullName": "Sara Khalifa",
    "email": "sara@example.com"
  },
  "conversations": [],
  "envelopes": [],
  "ui": {
    "…": "layout and permission hints used by the app"
  }
}

Create a record

POST/modules/{module}/records

Creates a record. Workflow, assignment and validation rules run as usual.

Path parameters
modulestringrequired
The module's API name, for example leads, contacts, accounts, deals or one of your custom modules.
Body
namestringrequired
Display name, up to 255 characters.
dataobject
Field values keyed by field API name. Picklist values must be one of the field's options.
ownerIduuid
Owner. Defaults to the key's user, unless an assignment rule picks someone.
tagsstring[]
Tags to add.
Request
curl -X POST "https://api.spartivo.com/api/v1/modules/leads/records" \
  -H "Authorization: Bearer wk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Aisha Khan","data":{"email":"aisha@example.com","company":"Northwind Trading","source":"whatsapp"},"tags":["api"]}'
Response
{
  "id": "a0d3bf2c-688d-42da-83e1-d5e57d3e990d",
  "ownerId": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
  "name": "Aisha Khan",
  "data": {
    "email": "aisha@example.com",
    "company": "Northwind Trading",
    "source": "whatsapp",
    "status": "new"
  },
  "tags": [
    "api"
  ],
  "score": 0,
  "createdAt": "2026-11-18T08:33:18.996Z",
  "updatedAt": "2026-11-18T08:33:18.996Z",
  "deletedAt": null
}

Update a record

PATCH/records/{id}

Changes only what you send. Keys inside data are merged into the existing fields.

Path parameters
iduuidrequired
The record id.
Body
namestring
New display name.
dataobject
Fields to change. Send null to clear a field. Fields you leave out keep their value.
ownerIduuid
New owner.
tagsstring[]
Replaces the full list of tags.
  • Moving a record between pipeline stages follows the stage rules set up in the CRM. A move that is not allowed returns 400 with the reason.
Request
curl -X PATCH "https://api.spartivo.com/api/v1/records/a0d3bf2c-688d-42da-83e1-d5e57d3e990d" \
  -H "Authorization: Bearer wk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"data":{"status":"contacted"}}'
Response
{
  "id": "a0d3bf2c-688d-42da-83e1-d5e57d3e990d",
  "ownerId": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
  "name": "Aisha Khan",
  "data": {
    "email": "aisha@example.com",
    "company": "Northwind Trading",
    "source": "whatsapp",
    "status": "contacted"
  },
  "tags": [
    "api"
  ],
  "score": 0,
  "createdAt": "2026-11-18T08:33:18.996Z",
  "updatedAt": "2026-11-18T08:33:19.227Z",
  "deletedAt": null
}

Delete a record

DELETE/records/{id}

Moves the record to the recycle bin. An administrator can restore it from Setup.

Path parameters
iduuidrequired
The record id.
Request
curl -X DELETE "https://api.spartivo.com/api/v1/records/a0d3bf2c-688d-42da-83e1-d5e57d3e990d" \
  -H "Authorization: Bearer wk_your_key"
Response
{
  "ok": true
}

Search across modules

GET/records/search

Finds records whose name or any field contains the text: an email address, a company, a reference number. Phone numbers match however they are spaced or punctuated. Name matches come first.

Query parameters
qstringrequired
Text to look for.
modulestring
Limit the search to one module.
limitinteger
How many matches to return, 1 to 50. Default 10.
  • match says which field matched and is left out when the name itself matched.
Request
curl "https://api.spartivo.com/api/v1/records/search?q=aisha@example.com" \
  -H "Authorization: Bearer wk_your_key"
Response
[
  {
    "id": "a0d3bf2c-688d-42da-83e1-d5e57d3e990d",
    "name": "Aisha Khan",
    "module": {
      "apiName": "leads",
      "label": "Lead"
    },
    "match": {
      "field": "email",
      "value": "aisha@example.com"
    }
  }
]

Get several records

GET/records/batch

Looks up to 200 records by id in one call. Useful for resolving lookup fields to names.

Query parameters
idsstringrequired
Record ids separated by commas.
Request
curl "https://api.spartivo.com/api/v1/records/batch?ids=a0d3bf2c-688d-42da-83e1-d5e57d3e990d" \
  -H "Authorization: Bearer wk_your_key"
Response
[
  {
    "id": "a0d3bf2c-688d-42da-83e1-d5e57d3e990d",
    "name": "Aisha Khan",
    "module": {
      "apiName": "leads",
      "label": "Lead"
    }
  }
]

Change many records

POST/modules/{module}/records/mass

Applies one action to up to 500 records.

Path parameters
modulestringrequired
The module's API name, for example leads, contacts, accounts, deals or one of your custom modules.
Body
idsuuid[]required
1 to 500 record ids.
actionobjectrequired
One of: {"type":"update","data":{…}}, {"type":"owner","ownerId":"…"}, {"type":"tag","add":[…],"remove":[…]}, {"type":"delete"}.
Request
curl -X POST "https://api.spartivo.com/api/v1/modules/leads/records/mass" \
  -H "Authorization: Bearer wk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"ids":["a0d3bf2c-688d-42da-83e1-d5e57d3e990d"],"action":{"type":"tag","add":["vip"]}}'
Response
{
  "done": 1
}

Import rows

POST/modules/{module}/import

Creates or updates up to 5,000 records from rows of text values, the same way the import screen does.

Path parameters
modulestringrequired
The module's API name, for example leads, contacts, accounts, deals or one of your custom modules.
Body
rowsobject[]required
Each row is a map of column name to text value.
mappingobjectrequired
Column name to field API name. Map a column to name for the record name.
dedupeFieldstring
A field to match on. Rows that match an existing record update it instead of creating a new one.
ownerIduuid
Owner for the new records.
Request
curl -X POST "https://api.spartivo.com/api/v1/modules/leads/import" \
  -H "Authorization: Bearer wk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"rows":[{"Full name":"Omar Said","Email":"omar.said@example.com"}],"mapping":{"Full name":"name","Email":"email"},"dedupeField":"email"}'
Response
{
  "created": 1,
  "updated": 0,
  "skipped": 0,
  "errors": []
}

Add a note

POST/records/{id}/notes

Adds a note to the record's timeline.

Path parameters
iduuidrequired
The record id.
Body
bodystringrequired
The note, up to 5,000 characters.
Request
curl -X POST "https://api.spartivo.com/api/v1/records/a0d3bf2c-688d-42da-83e1-d5e57d3e990d/notes" \
  -H "Authorization: Bearer wk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"body":"Called, asked for a quote"}'
Response
{
  "id": "dca4ecfe-f54e-4e1e-80f3-a88befceb480",
  "recordId": "a0d3bf2c-688d-42da-83e1-d5e57d3e990d",
  "actorId": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
  "type": "note.added",
  "title": "Note",
  "body": "Called, asked for a quote",
  "createdAt": "2026-11-18T08:33:19.238Z"
}

Get the timeline

GET/records/{id}/timeline

Everything that happened on a record, newest first: field changes, notes, messages, calls and documents.

Path parameters
iduuidrequired
The record id.
Request
curl "https://api.spartivo.com/api/v1/records/a0d3bf2c-688d-42da-83e1-d5e57d3e990d/timeline" \
  -H "Authorization: Bearer wk_your_key"
Response
[
  {
    "id": "c7ad70ea-0e02-4f65-b91a-2fb1695726d6",
    "recordId": "a0d3bf2c-688d-42da-83e1-d5e57d3e990d",
    "type": "record.updated",
    "title": "Lead updated",
    "body": null,
    "payload": {
      "changes": {
        "status": {
          "from": "new",
          "to": "contacted"
        }
      }
    },
    "createdAt": "2026-11-18T08:33:19.228Z",
    "actor": {
      "id": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
      "fullName": "Sara Khalifa"
    }
  }
]

Get related records

GET/records/{id}/related

Records in other modules that point to this one through a lookup field, grouped by module.

Path parameters
iduuidrequired
The record id.
Request
curl "https://api.spartivo.com/api/v1/records/a0d3bf2c-688d-42da-83e1-d5e57d3e990d/related" \
  -H "Authorization: Bearer wk_your_key"
Response
[
  {
    "module": {
      "apiName": "tasks",
      "label": "Task",
      "pluralLabel": "Tasks"
    },
    "field": "related_to",
    "items": []
  }
]

Convert a lead

POST/records/{id}/convert

Converts a lead into a contact and, when the lead has a company, an account. The key's user needs the Convert permission on Leads.

Path parameters
iduuidrequired
The record id.
Request
curl -X POST "https://api.spartivo.com/api/v1/records/a0d3bf2c-688d-42da-83e1-d5e57d3e990d/convert" \
  -H "Authorization: Bearer wk_your_key" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "contactId": "7efd90f4-39ad-4cf4-90cf-b5ae9ce47bcc",
  "accountId": "348956d9-c7c8-49c5-b08f-da6fb8d7f66f"
}
Previous← Requests and errorsNextModules and fields →
On this page
GETList recordsGETGet a recordPOSTCreate a recordPATCHUpdate a recordDELETEDelete a recordGETSearch across modulesGETGet several recordsPOSTChange many recordsPOSTImport rowsPOSTAdd a noteGETGet the timelineGETGet related recordsPOSTConvert a lead