While the Javascript Library is the preferred mechanism for sending product usage data to Freshsuccess, there are some cases where it is inconvenient or infeasible. For example, if you have already instrumented your product to collect product usage internally, or if your product is not javascript-based (e.g., native apps, mobile apps).
The Event REST API is a way to send raw events directly to Freshsuccess. While using this API, considerations such as client-side caching, batching and compression must be implemented by the user of the API.
The API has a single end-point and operates entirely using HTTP POST requests.
Once the library has been integrated into your product please let us know as we need to setup the workflows to run and process your data. This needs to be completed prior to data becoming visible within the UI.
https://events-us.freshsuccess.com/v1/[yourAuthKey]/[yourApiKey]
OR
EU Datacenter:https://events-eu.freshsuccess.com/v1/[yourAuthKey]/[yourApiKey]If you are not sure of which datacenter to use please contact support@freshsuccess.com.
apiKey - A secret key by which a user's event stream is identified. With this key, anyone can upload events as the user to the matching source.
authKey - A second secret key used to authenticate user. You need both the authentication key and the api key to successfully upload an event to the Freshsuccess servers.
The authentication and api keys are tied together and are unique to a source, both are generated by the website when creating a direct to Freshsuccess source.
An HTTPS POST on the request URL with the body containing a series of JSON objects defining individual events. Multiple events can be batched within a single POST request. Each event must be separated by and end-of-line marker, indicated either by '\r\n' or '\n'. Events MUST NOT be formatted as a JSON array.
The 'Content-Type' header should be set to 'application/json' and the 'Content-Length' header should also be set.
For example, this is the correct format, notice NO [], nor commas between events:
POST /v1/authkey/apikey HTTP/1.1
HOST: events-xx.freshsuccess.com
Content-Length: 593
Content-Type: application/json
{ "accountId": "id", "userId": "id", "createdAt": number, ... }
{ "accountId": "id", "userId": "id", "createdAt": number, ... }
{ "accountId": "id", "userId": "id", "createdAt": number, ... }
You may optionally compress JSON events in the request body using either GZip or Deflate.
If compressing with Gzip, the 'Content-Encoding' header must be set to 'gzip'.
If compressing with Deflate, the 'Content-Encoding' header must be set to 'deflate'.
Any other header values will be regarded as plain text json.
Responses contain no body, only an HTTP response code. The returned code is either 200 (OK) on success or 400 (BAD REQUEST) on failure. Failure is the result of either an invalid request type (e.g., not POST) or an invalid path (guid and/or source). Invalid events are silently dropped by the server.
You can ping the server over https by sending a POST to https://events-us.freshsuccess.com/v1/ping
The server response will return a 200 OK code if the server is reachable and no message body.
The JSON data for events *should* contain the following base properties. These base properties should be sent with every event:
{
// Required
accountId: string, (A unique account ID, required)
userId: string, (A unique user ID, required)
createdAt: number, (event's timestamp in epoch milliseconds, required)
action: string (event string, see below, required)
sessionId: string, (client session id; typically expires in 30 minutes, required),
}
All supported events (actions) are described below along with their associated properties that make up the JSON data object.
The core events that should be implemented are for primary data tracking are:
featuremoduleEndsessionSyncSupporting events that are useful for adding new or updating existing accounts/users:
identifyUseridentifyAccountThe full api follows:
identifyUser - user identification. Report extra details about the user such as email address and name; this is used to update the set of product users and is visible within the product (to show which users are associated with each event).
{
[base properties],
action: "identifyUser",
details: {
email: string, (optional but preferred)
first_name: string, (optional, but preferred)
last_name: string, (optional, but preferred)
phone: string, (optional)
mobile: string, (optional)
salutation: string, (optional)
title: string, (optional)
role: string, (optional)
department: string, (optional)
mailing_street: string, (optional)
mailing_city: string, (optional)
mailing_state: string, (optional)
mailing_postal: string, (optional)
mailing_country: string (optional)
}
}
identifyAccount - account identification. Report extra details about the account such as name, address, industry, etc. This is used to update the account dimensions visible within the product.
{
[base properties],
action: "identifyAccount",
details: {
name: string, (optional for updates, required for insert)
join_date: number, (epoch ms, optional for updates, required for insert)
tier: string, (optional)
industry: string, (optional)
employees: number, (optional)
website: string, (optional)
phone: string, (optional)
billing_street: string, (optional)
billing_city: string, (optional)
billing_state: string, (optional)
billing_postal: string, (optional)
billing_country: string (optional)
}
}
sessionSync - sync session usage. Report time spent within session.
{
[base properties],
action: "sessionSync",
activeDuration: number (time in ms spent in session since last session sync)
}
moduleEnd - usage of current module has completed. Report the timespent within the module
{
[base properties],
action: "moduleEnd",
module: string, (name of the module)
product: string, (optional, product name)
timeSpent: number (time in ms spent within this module)
}
feature - a feature was used. Feature usage typically maps to a click event. Each feature is counted as one usage event unless the total parameter is specified, in which case the 'total' is added to the sum of usage counts.
{
[base properties],
action: "feature",
feature: string, (name of the feature that was used)
module: string (name of the module this feature is within)
product: string, (optional, product name)
total: number (optionally provide the total usage count for this feature)
}
To verify that your app has been properly instrumented, you can use the Freshsuccess Instrumentation Viewer. The steps are detailed in the JS Quickstart Guide.
curl -X POST -T file.json https://events-us.freshsuccess.com/v1/<auth_key>/<api_key>
If your data does not fit with the JSON event format described above, we may still be able to work with your data. Please contact support@freshsuccess.com with a description of your data and you will be connected with one of our engineers who can help you with your integration.