Track a custom goal

api-referencePOST

POSThttps://analytics.flowsery.com/api/v1/goals

Record a custom goal event. Only name is required; visitorUid, sessionUid, metadata, and timezone are optional.

Bearer Token (API key)

Request body

Parameter	Type	Description
`visitorUid`	`string`	Optional Flowsery visitor ID, typically sourced from the _fs_vid cookie on your own backend.
`sessionUid`	`string`	Optional Flowsery session ID, typically sourced from the _fs_sid cookie.
`name`REQUIRED	`string`	Goal name (lowercase letters, numbers, underscores, and hyphens; max 64 characters).
`metadata`	`object`	Optional custom key-value pairs. Keep to 10 keys or fewer.

Metadata field rules

Keys: Only lowercase letters, numbers, underscores (_), and hyphens (-). Max 64 characters.

Values: Any string up to 255 characters. HTML and script content is stripped automatically for security.

Limit: Up to 10 custom parameters per event.

No existing pageview required

The backend can create the goal record on demand. This endpoint should not be documented as requiring a previously recorded pageview.

Error responses

400 Bad Request -- Returned when the payload is invalid.

404 Not Found -- Not part of the normal create-goal contract.

Example request (Node.js)

const handler = async (req, res) => {
  const _fs_vid = req.cookies._fs_vid;
  const _fs_sid = req.cookies._fs_sid;

  const response = await fetch(
    "https://analytics.flowsery.com/api/v1/goals",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${FLOWSERY_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        visitorUid: _fs_vid,
        sessionUid: _fs_sid,
        name: "newsletter_signup",
        metadata: {
          name: "Elon Musk",
          email: "musk@x.com",
        },
      }),
    }
  );

  const result = await response.json();
  res.status(200).send("Goal tracked");
};

200

{
  "status": "success",
  "data": [{
    "message": "Goal created successfully"
  }]
}