Webmarketer API (1.0.0)

This endpoint allows you to retrieve the interactions of a project.

The result is paginated and every property of the request body is optional: an empty body returns the whole project history, most recent ingestion order first is not guaranteed, so pass sort when order matters.

Two parameters select the population the endpoint looks at, each on three states: filtered for the traffic captured by one of the project's traffic filters, isBot for bot traffic. Both default to false, so an ordinary request answers on real traffic only. true restricts the response to that population, null leaves both in.

/interactions/insights takes the same two parameters with the same defaults, so a search and an insight on identical criteria cover the same interactions.

Both online (session) and offline (offline) interactions are returned. The two types do not carry the same properties: fields such as firstPage, hitCount or userAgent only exist on a session.

This endpoint allows you to retrieve a single interaction by its id.

Every property of the interaction is returned, userData included.

This endpoint allows you to retrieve the hits (page views) of an online interaction, ordered by ingestion date, oldest first.

The interaction is addressed by its firstHitId, the id of the hit that opened the session, and not by its _id. That value is returned by the search endpoint on every session interaction.

Offline interactions have no hits and no firstHitId. An unknown firstHitId returns an empty array, not a 404.

This endpoint aggregates interactions into counters instead of returning them one by one: how many interactions, how many hits and how much time they represent, optionally broken down by a property (group) and/or by a time bucket (interval).

The response is an array with one record per combination of group and interval. Without either, it holds a single record covering the whole selection.

Default selection. filtered and isBot select the population the counters cover, each on three states, exactly as on /interactions/search. Both default to false, so an ordinary request counts real traffic only. Offline interactions are part of the counts: this is why sessionCount is a count of interactions, online and offline alike, despite its name.

This endpoint allows you to create offline interaction.

An offline interaction is a user interaction with your brand out of your website that you want to track with Webmarketer.

Offline interaction can/should be only associated to a custom integration (eg: Google Spreadsheet) according to nodeData property.

nodeData property is used to identify the targeted advertiser node, you must provide a wmktId to allow Webmarketer to identify the integration and the advertiser needed properties (eg: cid for campaign ID).

userData property is used to identify the user, you must only provide identity field according to the project's user schema (eg: email, phone...).

Offline interaction ingestion is synchronous, so you will receive a 400 response if the interaction payload is invalid.

This endpoint allows you to send an event to Webmarketer.

An event represent an user action on your website or application that you want to track with Webmarketer.

Ensure you have properly configured your event types in Webmarketer before sending events and the event data you are sending matches your declared event-type schema.

With this enpoint, event ingestion is asynchronous, so you will receive a 200 response even if the event is not yet processed or invalid. You can consult the trashed events in the Webmarketer interface.

This endpoint allows you to send an event to Webmarketer.

An event represent an user action on your website or application that you want to track with Webmarketer. Ensure you have properly configured your event types in Webmarketer before sending events and the event data you are sending matches your declared event-type schema.

Event ingestion is synchronous on this endpoint, so you will receive a 200 response when the event is fully processed.

This endpoint allows you to retrieve a raw event by its id (Event ids are generated by Webmarketer and are globally unique)

The raw event is the event as it was sent to the Webmarketer API, without any transformation, this endpoint does not allow to get the data computed by Webmarketer. If your want to get the computed data, please use the /projects/{projectId}/users/{id}/events or /projects/{projectId}/events/{id} endpoint.

This endpoint allows you to fetch the trashed events.
When an event cannot be processed by Webmarketer (when a mandatory field is missing, or when some fields values are invalid) the event will be stored in the "trash collection", allowing you to investigate and debug.

⚠️ Note: the field key in the errors array will be removed in a near future, the field will be changed to a string.

This endpoint allows you to generate the insight about event.

⚠️ Note that this endpoint get data from the event without using the attribution, if you want insights about attributed data, please refer to TODO.

This endpoint allows you to retrieve multiple metrics and aggregate them by a date dimension and by event-type if needed.

The metrics can be :

• Your statistics technical keys (ie: turnover if you used the e-commerce project bootstrap)
• Your states technical keys (ie: rdv or converted if you declared theses offline states)
• event-count this one is a built-in metric that count the number of events

The classic date dimension can be :

• day
• week
• month
• quarter
• semester
• year

If needed you can use a non-linear date dimension, allowing you to identify seasonality in your data.

• dayOfWeek
• dayOfMonth
• dayOfYear
• weekOfYear
• monthOfYear
• quarterOfYear
• semesterOfYear

You can also use the event-type breakdown, this option will generate an output entry for each couple date interval/event-type.

This endpoint is designed to generate graphs so it is not paginated.

This endpoint allows you to update a state of an event.
After being generated, an event state can evolve. It is common to see a call-me-back event pass to a qualified state after having been qualified by your sales team, then set the converted state when the user order.

If in this example, the event seems to only have one state at a time, this is not how Webmarketer models your events.

For the example above, Webmarketer will store :

• qualified on 2023-08-10T14:30:00Z
• converted on 2023-08-18T17:30:00Z

Each event state is described with a date.

In the future, this modeling will allow you to analyze the transients between theses states (e.g. how long does it take to get a lead from qualified to converted when it comes from Facebook).

Troubleshooting
If you encounter 404 response telling that "No storageKey matching field in this eventType" (the service names storageKey what an event type calls the key of the field it uses) :

• You may have a typo in the state name
• The state did not exists at the time the event you trying to update where created

In the second case, if you need to update state of past events for which a state did not exists, our team can manually add them to allow historical updates : please contact us.

Even if we love giving you the autonomy to manage your data, we prefer to be cautious about this kind of update, backdating the states can cause inconsistencies (e.g. when renaming states over time), our experts will ensure that "backdating" will not cause side effects)

This endpoint allows you to update a statistic of an event.
Event statistic allow you to inform Webmarketer about your event metrics (like turnover, or quoted amount).

A classical situation is when an event leads to a sale of 4 000€.

By updating the "turnover" stat, you allow Webmarketer to affect this amount to the campaigns that led to this event (according to your attribution models).

E.g. : with a linear model and two interactions : 50% google (2000€), 50% facebook (2000€)

As for event state, a statistic can also be set to a specific date.

In the future, this modeling will allow you to analyze the transients between theses states (e.g. how long does it take to get a lead from qualified to converted when it comes from Facebook).

Troubleshooting
If you encounter 404 response telling that "No storageKey matching field in this eventType" (the service names storageKey what an event type calls the key of the field it uses) :

• You may have a typo in the state name
• The state did not exists at the time the event you trying to update where created

In the second case, if you need to update state of past events for which a state did not exists, our team can manually add them to allow historical updates : please contact us.

Even if we love giving you the autonomy to manage your data, we prefer to be cautious about this kind of update, backdating the states can cause inconsistencies (e.g. when renaming states over time), our experts will ensure that "backdating" will not cause side effects)

This endpoint allows you to retrieve an event by its id (Event ids are generated by Webmarketer and are globally unique)

The event is the computed event from the raw event which was sent to the Webmarketer API (linked user, passed data parsed).

This endpoint allows you to retrieve the users of a project.

It is served on /api/v2, not on the /api/v1 base URL shown > elsewhere in this reference. The full path is > https://api.webmarketer.io/api/v2/projects/{projectId}/users/search.

Unlike the other list endpoints, fields decides what the response holds. A user carries an open set of fields and counters, most of them specific to the project, so nothing is returned by default: name what you need and the response carries that, and only that. An empty array falls back to _id alone.

Three vocabularies share the same namespace, and they are the same in fields, in sort and in the export endpoint:

• fields.{fieldKey} for a user field, as declared in the project's user schema, for instance fields.email;

• eventTypesCount.{eventTypeReference} for the number of events of one type, for instance eventTypesCount.contact-form;

• metrics.{metricKey}.{aggregation} for an aggregated metric, where the aggregation is sum, max, min, count or average, for instance metrics.revenue.sum;

• any counter of the user itself, used as is: eventCount, interactionCount, hitCount, firstEventDate, audienceIds…

An unknown key is rejected with a 400, so the response never silently drops what you asked for.

The result is paginated. On large projects, prefer keyset pagination (sort: "_id" with idAfter) over a growing offset.

This endpoint allows you to retrieve a single user by their id.

Everything Webmarketer holds about them is returned: their fields, their counters and their audiences. There is no projection here, unlike the search endpoint.

This endpoint exports the users of a project as a CSV or an XLSX file, and answers with the file itself rather than with JSON.

The selection works like the search endpoint, with two differences: the columns are named columns instead of fields, and an audience is designated by its id (or by a raw condition) through audience rather than audienceCondition.

transformerConfig shapes the columns of the file: flattening a currency or a location into plain columns, formatting a date, or reducing a multi-value field to one value. Each entry names the key it applies to and the level it applies at.

This endpoint allows you to retrieve the events of one user, that is the events Webmarketer attached to that visitor. It is the timeline behind their customer journey.

The result is paginated, and the events are the computed ones, as returned by /projects/{projectId}/events/{id}.