API Reference

Create Goal

Name: Flowsery
Author: Flowsery

Record a custom goal event for a visitor

POSThttps://analytics.flowsery.com/goals

Record a custom goal event for a given visitor.

Bearer Token (API key)

Request body

Parameter	Type	Description
`visitorUid`	`string`	The Flowsery Analytics visitor ID. This value is stored in the _fs_vid browser cookie, making it accessible from your server-side endpoints.
`name`REQUIRED	`string`	Goal name (lowercase letters, numbers, underscores, and hyphens; max 64 characters).
`metadata`	`object`	Custom key-value pairs to enrich the event. Up to 10 parameters per event.

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.

Visitor must have a pageview

The visitor must have at least one recorded pageview before a goal can be created. A 404 is returned when no pageview exists for the visitor.

Error responses

400 Bad Request -- Returned when the visitor is identified as a bot.

404 Not Found -- Returned when no pageview exists for the given visitor.

Example request (Node.js)

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

  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,
        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": "Custom event created successfully",
    "eventId": "67f8b9b5c320277df9a9d681"
  }]
}