JourneyStream Events

Base URLs

Encodings

Text: JourneyStream utilizes the utf8 encoding scheme for all of its messages. 
Dates: JourneyStream accepts dates in the ISO 8601 format in the form YYYY-MM-DDTHH:MI:SS.000000Z. This means that your event dates need to be converted to UTC before sending to JourneyStream.

Field Definitions

  • event_type - The type of event being sent to the stream. Accepted values are interaction, conversion, metric, and association. This field is required.
  • organization_uuid -  Your organization’s uuid. This will be provided to you upon activation of the JourneyStream product. In the meantime, you can throw any standard uuid at the sandbox… Just keep it static across your test messages for easy auditing by our customer success team. This field is required.
  • who_uuid - A unique identifier representing a person. While this field has UUID in the name, any string representing a unique person from your system is accepted here. This field is required.
  • who_type - A string representing the type of who_uuid being sent. This can be any text string, but should be consistent in case and space usage (e.g if the who_uuid is a hashed phone number, then always use phone_number not Phone Number, Phone_Number, phone, or Phone # in some places). This field is optional.
  • event_date_time - The datetime that your event occurred at. JourneyStream will add a captured_at to your payload allowing us to see the difference between the event time and the capture time. This field is required.
  • integration - A text field representing the source of your event. This can be any text string, but should be consistent in case and space usage (e.g always use my_crm not My CRM, my_CRM, my crm, etc). This field is required.
  • touchpoint_id - The touchpoint id associated with the event. This can obtained from the Strala TouchPoints app. This field is required for Touchpoint Interaction Events. 
  • conversion_id - Your internal system’s identifier tied to a conversion (e.g. phone system, CRM system, commerce system, etc). This field is required for Conversion Events.
  • conversion_object_type - The high level object associated with the conversion event that happened (e.g. lead, contact, etc.). This field is required for Conversion Events. 
  • conversion_event - The name of the event that happened in connection with the conversion_object_type (e.g. lead_created, contact_created, etc.). This field is required for Conversion Events.
  • metrics - The fields that allow the event to be aggregated
  • "touchpoint_interaction":1 - The numeric indicator of a touchpoint interaction event. This is required.
  • "conversion":1 - The numeric indicator of a conversion event. This is required.
  • "revenue":0 - The amount in USD associated with the conversion event. This is optional.
  • run_time_attributes - These are used by the Strala Journey JS service to populate runtime attributes associated with online touchpoint interaction and conversion events.

Ops Monitoring

JourneyStream provides an endpoint that you can use:
  • to test whether the service is up
  • to evaluate whether our internal timekeeping is matched to an ntp server
  • to determine if we have rolled an update by looking to see if the commit hash has changed.
To use the monitoring endpoint:
  • Issue a GET request to the /pulse endpoint
  • If the cluster is working correctly, you will receive a  200  response with an application/json  encoded body containing a payload like: 
{
    "commit": "72b230775136083aa0bab685cd640c4e2ff8410e",
    "environment": "prod",
    "time": "2019-08-02T14:19:20.783066Z"
}
Feel free to configure any uptime monitoring tool to poll the pulse endpoint as often as once per second.

Event Types

There are four types of events that can be posted to JourneyStream:
  1. Touchpoint Interaction Events (interactions)
  2. Conversion Events (conversions)
  3. Association Events (associations)
  4. Metric Events (metrics)
Touchpoint Interaction Events: Interactions are the events that a conversion event may be attributed to later. Any time someone interacts with your touchpoint, you would fire a touchpoint interaction event. These interactions range from visits on marketing websites to inbound phone calls in a call center.
  • Endpoint: v1/journey/events
  • Headers: {"Content-Type": "application/json"}
  • Actions accepted: POST
  • Sample request body:
{
    "event_type": "touchpoint_interaction",
    "organization_uuid": "7e1a7bcd-6fc8-42ad-b17f-59067fc1a795",
    "who_uuid": "fb2b9154-4a27-4387-ae71-5cd8d9a9b1df",
    "who_type": "strala_who_uuid",
    "touchpoint_id": "124567",
    "event_date_time": "2019-02-10T00:00:00.000Z",
    "integration": "custom",
    "metrics": {"touchpoint_interaction": 1},
    "dimensions": {},
    "run_time_attributes": {}
}
The API will respond with a 201 Created message if the event was accepted. If the event was not accepted, a 400 Bad Request is returned.
Conversion Events: Conversions occur anytime you want to mark a milestone for attribution. A conversion could be something as simple as a lead form filled, a processed order, or a late stage sales opportunity.
  • Endpoint: v1/journey/events
  • Headers: {"Content-Type": "application/json"}
  • Actions accepted: POST
  • Sample request body:
{
  "event_type": "conversion",
  "organization_uuid": "7e1a7bcd-6fc8-42ad-b17f-59067fc1a795",
  "who_uuid": "878617e1-ca74-411b-9f25-e24837d2803d",
  "who_type": "strala_who_uuid",
  "touchpoint_id": "",
  "conversion_id": "006A000000GnGeIAK",
  "event_date_time": "2019-03-30T00:00:00.000Z",
  "integration": "my_custom_crm",
  "metrics": {"conversion": 1, "revenue": 1500.00},
  "dimensions": {
    "conversion_object_type": "annual_subscription",
    "conversion_event": "Subscription"
    },
  "run_time_attributes": {}
}
The API will respond with a 201 Created message if the event was accepted. If the event was not accepted, a 400 Bad Request is returned.
Association Events: Associations are events that tie who_uuid values together. Anytime you want to inform Strala that two identifiers are linked, you would send this event. The typical association event is one that ties an anonymous identifier from a cookie or localstorage to a CRM identifier. Without associations, no chain of events can be formed and attribution will usually end up looking just like last touch. Associations are used in two ways: 1) to link multiple devices to a single person 2) to link multiple people to a single entity/account.
  • Endpoint: v1/journey/associations
  • Headers: {"Content-Type": "application/json"}
  • Actions accepted: POST
  • Sample request body:
{
  "event_date_time":"2019-07-22T16:40:11.073Z",
  "child_type":"strala_who_uuid",
  "child_who_uuid":"cba123",
  "parent_type":"lead_id",
  "parent_who_uuid":"123abc",
  "integration":"my_custom_crm",
  "organization_uuid":"37e1a7bcd-6fc8-42ad-b17f-59067fc1a795",
  "event_type":"association"
}
The parent_type or child_type should match the who_type that is sent via an interaction or a conversion.
The API will respond with a 201 Created message if the event was accepted. If the event was not accepted, a 400 Bad Request is returned.
Metric Events: Metrics are primarily used to factor cost into your attribution models. Send us metric events anytime you want log a measure associated with a particular touchpoint. Typically, metric events are used to increase the accuracy of cost data from ad platforms by overriding the platform reported cost and other aggregates.
  • Endpoint: v1/journey/events
  • Headers: {"Content-Type": "application/json"}
  • Actions accepted: POST
  • Sample request body:
{
  "event_type": "metric",
  "organization_uuid": "7e1a7bcd-6fc8-42ad-b17f-59067fc1a795",
  "touchpoint_id": "fb-1-608036276918008",
  "event_date_time": "2019-02-10T00:00:00.000Z",
  "integration": "facebook",
  "metrics": {
    "cost": 32.00,
    "clicks": 55,
    "impressions": 180
  },
  "dimensions": {
    "time_grain": "daily",
    "device_grain": "mobile"
  }, 
  "run_time_attributes": {}
}
The time_grain dimension tells us what time period the cost is applied to. Acceptable values:
  • daily
  • weekly
  • monthly
  • yearly
Any value that is not in the list above will cause the cost to be applied as a single cost on the event_date_time date.
The device_grain dimension is optional, but necessary if you split cost by TouchPoints for mobile vs desktop.

The API will respond with a 201 Created message if the event was accepted. If the event was not accepted, a 400 Bad Request is returned.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.