Source: https://datafa.st/docs/api/website/goals/create
Markdown source: https://datafa.st/docs/api/website/goals/create.md
Description: Create a server-side custom goal event for a visitor.

# 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. |

## 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.

## Code examples

### Example request

```bash
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"}}'
```

### Success response

```json
{
  "status": "success",
  "data": [{
    "message": "Custom event created successfully",
    "eventId": "67f8b9b5c320277df9a9d681"
  }]
}
```