Docs·Workspace
POST
/api/v1/spreelytics/referencesCreate a reference
Creates a reference and returns it. It shows up on the audience's charts straight away, for everyone in the workspace.
Needs the Editor or Admin role in the workspace that owns the audience. A Viewer gets 403.
Keys: an account key. Getting started explains both kinds.
Parameters
| Prop | In | Type | Notes |
|---|---|---|---|
contactListId | query | string | The audience id, a UUID. With an audience key it must be that key's own audience. |
Request body
| Prop | Type | Notes |
|---|---|---|
title | string | Required. Trimmed, and a blank title answers 400. |
description? | string | Optional note, trimmed. An empty one is stored as null. |
date | string | Required. The moment to mark, as an ISO 8601 date or timestamp such as 2026-09-30T09:00:00Z. A bare date means midnight UTC, and a date that does not parse answers 400. |
color? | string | Optional. A preset token var(--chart-N) (the app's swatches are var(--chart-1) to var(--chart-5)) or a six-digit hex colour such as #e11d48. null or leaving it out uses the default colour. Anything else answers 400. |
Response
| Prop | Type | Notes |
|---|---|---|
id | string | The reference id. |
title | string | The label shown on the marker. |
description | string | The longer note, or null. |
date | string | The marked moment. Create and update calls answer in ISO 8601, the list in the database form (2026-09-30 09:00:00+00). |
color | string | The marker colour: a preset such as var(--chart-1), a #rrggbb hex, or null for the default colour. |
createdAt | string | When it was created. Only the create call answers in ISO 8601 (2026-09-30T09:00:00.000Z). Every other call returns the database form (2026-09-30 09:00:00+00), so parse both. |
updatedAt | string | When it last changed. Create and update calls answer in ISO 8601, lists and reads in the database form, as with createdAt. |
Request
curl -X POST 'https://app.spreelytics.com/api/v1/spreelytics/references?contactListId=…' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ … }'
const res = await fetch('https://app.spreelytics.com/api/v1/spreelytics/references', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({ /* see Request body above */ }),
});
const data = await res.json();
import requests
res = requests.post(
"https://app.spreelytics.com/api/v1/spreelytics/references",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={}, # see Request body above
)
data = res.json()
Response
{
"id": "string",
"title": "string",
"description": "string",
"date": "string",
"color": "string",
"createdAt": "string",
"updatedAt": "string"
}