Records
Create, read, update and delete records in any module, standard or custom.
List records
/modules/{module}/recordsReturns a page of records the key's user is allowed to see, newest changes first unless you sort.
modulestringrequiredleads, contacts, accounts, deals or one of your custom modules.pageintegerpageSizeintegersortstringname, createdAt, updatedAt or a field API name such as amount. Default updatedAt.dirstringasc or desc. Default desc.qstringownerIduuidtagstringfiltersJSON array[{"field":"status","op":"eq","value":"new"}]. See Filtering.module.fieldsdescribes every field in the module, so one call gives you both the data and how to label it.
curl "https://api.spartivo.com/api/v1/modules/leads/records?pageSize=2&sort=createdAt" \
-H "Authorization: Bearer wk_your_key"{
"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
/records/{id}Returns one record with its module, its owner and related summaries.
iduuidrequired- Fields hidden from the key's user by their profile are left out of
data.
curl "https://api.spartivo.com/api/v1/records/a0d3bf2c-688d-42da-83e1-d5e57d3e990d" \
-H "Authorization: Bearer wk_your_key"{
"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
/modules/{module}/recordsCreates a record. Workflow, assignment and validation rules run as usual.
modulestringrequiredleads, contacts, accounts, deals or one of your custom modules.namestringrequireddataobjectownerIduuidtagsstring[]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"]}'{
"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
/records/{id}Changes only what you send. Keys inside data are merged into the existing fields.
iduuidrequirednamestringdataobjectnull to clear a field. Fields you leave out keep their value.ownerIduuidtagsstring[]- Moving a record between pipeline stages follows the stage rules set up in the CRM. A move that is not allowed returns
400with the reason.
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"}}'{
"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
/records/{id}Moves the record to the recycle bin. An administrator can restore it from Setup.
iduuidrequiredcurl -X DELETE "https://api.spartivo.com/api/v1/records/a0d3bf2c-688d-42da-83e1-d5e57d3e990d" \
-H "Authorization: Bearer wk_your_key"{
"ok": true
}Search across modules
/records/searchFinds 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.
qstringrequiredmodulestringlimitintegermatchsays which field matched and is left out when the name itself matched.
curl "https://api.spartivo.com/api/v1/records/search?q=aisha@example.com" \
-H "Authorization: Bearer wk_your_key"[
{
"id": "a0d3bf2c-688d-42da-83e1-d5e57d3e990d",
"name": "Aisha Khan",
"module": {
"apiName": "leads",
"label": "Lead"
},
"match": {
"field": "email",
"value": "aisha@example.com"
}
}
]Get several records
/records/batchLooks up to 200 records by id in one call. Useful for resolving lookup fields to names.
idsstringrequiredcurl "https://api.spartivo.com/api/v1/records/batch?ids=a0d3bf2c-688d-42da-83e1-d5e57d3e990d" \
-H "Authorization: Bearer wk_your_key"[
{
"id": "a0d3bf2c-688d-42da-83e1-d5e57d3e990d",
"name": "Aisha Khan",
"module": {
"apiName": "leads",
"label": "Lead"
}
}
]Change many records
/modules/{module}/records/massApplies one action to up to 500 records.
modulestringrequiredleads, contacts, accounts, deals or one of your custom modules.idsuuid[]requiredactionobjectrequired{"type":"update","data":{…}}, {"type":"owner","ownerId":"…"}, {"type":"tag","add":[…],"remove":[…]}, {"type":"delete"}.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"]}}'{
"done": 1
}Import rows
/modules/{module}/importCreates or updates up to 5,000 records from rows of text values, the same way the import screen does.
modulestringrequiredleads, contacts, accounts, deals or one of your custom modules.rowsobject[]requiredmappingobjectrequiredname for the record name.dedupeFieldstringownerIduuidcurl -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"}'{
"created": 1,
"updated": 0,
"skipped": 0,
"errors": []
}Add a note
/records/{id}/notesAdds a note to the record's timeline.
iduuidrequiredbodystringrequiredcurl -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"}'{
"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
/records/{id}/timelineEverything that happened on a record, newest first: field changes, notes, messages, calls and documents.
iduuidrequiredcurl "https://api.spartivo.com/api/v1/records/a0d3bf2c-688d-42da-83e1-d5e57d3e990d/timeline" \
-H "Authorization: Bearer wk_your_key"[
{
"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"
}
}
]Convert a lead
/records/{id}/convertConverts a lead into a contact and, when the lead has a company, an account. The key's user needs the Convert permission on Leads.
iduuidrequiredcurl -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 '{}'{
"contactId": "7efd90f4-39ad-4cf4-90cf-b5ae9ce47bcc",
"accountId": "348956d9-c7c8-49c5-b08f-da6fb8d7f66f"
}