Create a custom goal

POST https://datafa.st/api/v1/goals

Create a server-side custom goal event for a visitor.

Request

Authentication

df_ website API key for one website.
dft_ account token with goals:write. Pass websiteId as a query parameter.

Body parameters

Field	Type	Required	Description
`datafast_visitor_id`	string	Yes	DataFast visitor UUID from the browser cookie or client SDK. Used to attach server-side events to a visitor journey.
`visitorId`	string	No	Alias for `datafast_visitor_id` on endpoints that accept both names.
`name`	string	Yes	Human-readable name for the resource or event. The exact meaning depends on the endpoint. Goal name. Spaces become underscores; allowed chars are lowercase letters, numbers, underscores, hyphens, and colons. Max 64.
`description`	string	No	Optional goal description.
`metadata`	object	No	Custom metadata stored with the event or profile. Use this to enrich reporting and visitor profiles. Up to 10 custom properties. Keys max 64 chars; values max 255 chars.

Try on Playground

Response

Returns a JSON object with status and endpoint-specific fields.

Response fields

Field	Type	Description
`status`	string	`success`.
`data[].message`	string	Human-readable confirmation or status message for the operation.
`data[].eventId`	string	ObjectId of the event created by DataFast.

Errors

Common errors include 400 for invalid input, 401 for missing or invalid tokens, 403 for missing permission or suspended tracking, 404 for missing resources, and 500 for server errors.

✍️ Something missing? Suggest features.

🤖 AI agent or LLM? Read this page as markdown

curl -X POST "https://datafa.st/api/v1/goals" \ -H "Authorization: Bearer df_xxx" \ -H "Content-Type: application/json" \ -d '{"datafast_visitor_id":"a3ab2331-989f-4cfa-91c6-2461c9e3c6bd","name":"newsletter_signup","metadata":{"plan":"pro"}}'