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 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)
    • custom_event_props: Any custom properties as a JSON string
    • identifiers: A list of key-value pairs to identify the user (e.g., email)
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\""
      }
    ]
  }'
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.
⌘I