Docs·Goals
/api/v1/spree/goalCreate a goal
Creates a goal in the audience and returns it. A goal is one thing you want visitors to do: view a page (pageview), send a custom event (event) or scroll far enough down a page (scroll). Read its numbers with the goal analytics endpoints on this page. Goals are matched against your events when the numbers are read, so a new goal counts past conversions straight away.
Needs the Editor or Admin role in the workspace that owns the audience. A Viewer gets 403.
Errors: 400 with the reason when a field is wrong or unknown, 409 when the audience already has a goal with that name, and 410 when the audience does not exist or you are not in its workspace. One person's keys can have at most 10 requests running at once; more answer 429.
Keys: an account key. Getting started explains both kinds.
Parameters
| Prop | In | Type | Notes |
|---|---|---|---|
contactListId | query | string | The audience to add the goal to, a UUID. Your role comes from the workspace that owns it. |
Request body
| Prop | Type | Notes |
|---|---|---|
name | string | Required. 1 to 200 characters after trimming, and unique within the audience. Names are compared exactly, so Signup and signup are two different goals. |
matchType | ``event` \ | pageview \ |
eventName? | string | Required for event, ignored otherwise: the custom event name exactly as you track it (case matters), up to 200 characters. Only custom events count, not page views. |
pagePath? | string | Required for pageview and scroll, ignored for event. Up to 500 characters. The whole path must match, and * matches anything: /pricing is that one page, /blog/* every page under /blog/. A query string, a # fragment and a trailing slash are dropped before matching, as they are when pages are recorded. |
scrollThreshold? | number | Required for scroll: a whole number from 0 to 100, the percentage of the page the visitor must reach. |
propertyFilters? | GoalPropertyFilter[] | Optional, up to 20 conditions on the event's properties, all of which must hold. Each is { key, op, value }, with value a string of up to 500 characters (send numbers as strings too). Text: IS, IS_NOT, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH, where case matters. Numbers: EQ, NEQ, GT, LT. Dates: AFTER, BEFORE, with a YYYY-MM-DD value, compared by UTC day. No value: IS_TRUE, IS_FALSE, IS_SET, IS_NOT_SET. The negative operators also match an event without the property. The app offers these on Custom event goals. |
Response
| Prop | Type | Notes |
|---|---|---|
id | string | The goal id. Use it in a funnel's goalIds and with the goal analytics endpoints. |
contactListId | string | The audience the goal belongs to. |
name | string | The name as saved, trimmed. |
matchType | string | pageview, event or scroll. |
eventName | string | The event name for an event goal, otherwise null. |
pagePath | string | The path pattern for a pageview or scroll goal, as sent (trimmed), otherwise null. |
scrollThreshold | number | The depth for a scroll goal, otherwise null. |
propertyFilters | GoalPropertyFilter[] | The conditions as saved, or null when there are none. Operators that take no value come back with an empty value. |
createdAt | string | When it was created, ISO 8601. |
updatedAt | string | When it last changed, ISO 8601. |
Request
curl -X POST 'https://app.spreelytics.com/api/v1/spree/goal?contactListId=…' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ … }'
const res = await fetch('https://app.spreelytics.com/api/v1/spree/goal', {
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/spree/goal",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={}, # see Request body above
)
data = res.json()
Response
{
"id": "string",
"contactListId": "string",
"name": "string",
"matchType": "string",
"eventName": "string",
"pagePath": "string",
"scrollThreshold": 0,
"propertyFilters": [
{
"key": "string",
"op": "string",
"value": "string"
}
],
"createdAt": "string",
"updatedAt": "string"
}