> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embeddables.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How To: Send analytics events to Embeddables

> Sending data server-side to the Embeddables API

Although most user events occur when the user interacts with your Embeddable, meaning Embeddables will automatically capture that event, there are times when user events occur elsewhere.

For example, a user completing a doctor's appointment, or a user completing a purchase that isn't handled by Embeddables' Stripe integration.

In those cases, you can [send data to the Embeddables API using a server-side request](/api-reference/events/create-event).

## How to send data to Embeddables

<Steps>
  <Step title="Generate an Embeddables API key">
    * Contact the Embeddables team to generate an API key for your project.
    * API keys are Restricted Keys, and always start with `rk_` - for example: `rk_myexampleapikey`.
  </Step>

  <Step title="Prepare your event data">
    * Create a JSON object with the following fields.

    ### Required fields

    * `embeddable_id`: The ID of your Embeddable
    * `timestamp`: The time the event occurred (in ISO 8601 format)
    * `custom_event_name`: A name for your custom event (must be snake\_case)
    * `identifiers`: A list of key-value pairs to identify the user (e.g., email)

    ### Optional fields

    * `custom_event_props`: Any custom properties as a JSON string. For events where you want to send structured metrics and dimensions (for example purchase events), we recommend sending an object with `payload_metrics` (numbers) and `payload_dimensions` (strings) as described below.

    <Tip>
      The `identifiers` field is an array of objects, each containing a `key` and `value`. Currently, we only support one identifier per request (i.e. one object in the array).
    </Tip>

    <Warning>
      **Watch out for this:** The `value` field must be a stringified JSON value. E.g. for email addresses, the value must be `"\"test@test.com\""` (note the double quotes).
    </Warning>
  </Step>

  <Step title="Send the event to the API">
    * Make a POST request to `/projects/{projectId}/events`
    * Include your API key in the `X-Api-Key` header
    * Send the event data in the request body

    Example request:

    ```bash theme={null}
    curl -X POST https://api.embeddables.com/projects/pr_myexampleproject/events \
      -H "X-Api-Key: rk_myexampleapikey" \
      -H "Content-Type: application/json" \
      -d '{
        "embeddable_id": "flow_myexampleflow",
        "timestamp": "2022-01-01T00:00:00.000Z",
        "custom_event_name": "my_custom_event",
        "custom_event_props": "{\"my_prop\": \"my_val\"}",
        "identifiers": [
          {
            "key": "email",
            "value": "\"test@test.com\""
          }
        ]
      }'
    ```
  </Step>
</Steps>

## Example: Structured metrics and dimensions payload

For events where you want to send a mix of numeric metrics and categorical dimensions, we recommend structuring `custom_event_props` as a JSON string containing:

* **payload\_metrics**: A key–value object where all values are numbers (for example `order_value`, `revenue`, `subtotal`).
* **payload\_dimensions**: A key–value object where all values are strings (for example `plan`, `bundle`, `purchase_type`).

This follows a metrics-vs-dimensions approach and keeps your data easy to analyze. The same schema applies when tracking [custom client-side events](/features/analytics#custom-client-side-events).

Example request for a purchase event using this schema:

```bash theme={null}
curl -X POST https://api.embeddables.com/projects/pr_myexampleproject/events \
  -H "X-Api-Key: rk_myexampleapikey" \
  -H "Content-Type: application/json" \
  -d '{
    "embeddable_id": "flow_myexampleflow",
    "timestamp": "2022-01-01T00:00:00.000Z",
    "custom_event_name": "purchase_completed",
    "custom_event_props": "{\"payload_metrics\": {\"order_value\": 99.99, \"revenue\": 89.99}, \"payload_dimensions\": {\"plan\": \"premium\", \"bundle\": \"annual\", \"purchase_type\": \"subscription\"}}",
    "identifiers": [
      {
        "key": "email",
        "value": "\"test@test.com\""
      }
    ]
  }'
```

Inside `custom_event_props`, the JSON object has numeric values under `payload_metrics` and string values under `payload_dimensions`. You can add your own keys while respecting those types.

<Note>
  The API will return a 200 status code if the event was successfully created.
  If there are any issues with the request (e.g., invalid API key, missing
  required fields), you'll receive an appropriate error response.
</Note>

## Troubleshooting

### I'm getting a 404 `ENTRY_NOT_FOUND` response

This means that the Embeddables API is trying to find a user that matches the `identifiers` you provided, for the `embeddable_id` you provided, but couldn't find one.

Things to look out for:

1. Check that you are passing the correct `embeddable_id` - this should be the ID of the Embeddable that matches the user you're trying to add an event for.
2. Check that you are passing the correct `key` inside `identifiers` - this should be the key in the User Data that matches the input component that the user typed in, such as `email` or `user_email`.
3. Check that you are passing the correct `value` inside `identifiers` - make sure that this matches the user that you're trying to track, and matches the key and Embeddable ID that you're using.
4. Check that you are formatting `identifiers` correctly - the value must be a stringified JSON value. E.g. for email addresses, the value must be `"\"test@test.com\""` (note the double quotes). This can become double-escaped (e.g. `"\\"test@test.com\\""`) in certain code environments.
5. Check that the user has definitely provided their unique identifier before the track event is triggered - trying to track a user based on an email address that hasn't been captured yet is impossible.