Skip to main content
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.

​
How to send data to Embeddables

1

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

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.
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).
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).
3

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:
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\""
      }
    ]
  }'

​
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. Example request for a purchase event using this schema: 
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.
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.

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