Aller au contenu principal
Documentation Powered by Redocly

Webmarketer API (1.0.0)

E-mail: developer@webmarketer.io

Introduction

Webmarketer is a marketing tool allowing to collect interactions, events and attribute them. This API allows you to interact with your data.

Date Specification

Webmarketer API uses the date-time format as specified in RFC3339. RFC3339 is a profile of the ISO 8601 standard for date and time formats which is widely used in Internet protocols and standards.

The API uses this format to represent an instant with any timezone offset.

Note : If a timezone offset is not provided, the API will consider the date-time as UTC.

For example, 2022-04-01Z05:00:00, 2022-04-01T06:00:00+01:00 and 2022-04-01T03:00:00-02:00 represent the same instant in UTC, UTC +1 and UTC -2 respectively.

Events

Everything about events

Create an event

This endpoint allow you to send an event to Webmarketer.

An event is a user interaction with 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 match your declared event-type schema.

Event ingestion is asynchronous, so you will receive a 200 response even if the event is not yet processed or invalid.

Request Body schema: application/json
projectId
required
string (project_id) [ 3 .. 64 ] characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

Your Webmarketer project id

eventType
required
string

Event Type reference of the event to send

eventDate
string <date-time>

Date of the event, see Date Specification section for more information.

trackerId
string

Tracker ID of the user who made the event (if not provided, Webmarketer won't be able to attach the event to user interactions)

nonce
required
string

A unique identifier used to deduplicate event in case of multiple sends

data
required
object

Data of the event (must match the event type schema)

Responses

Request samples

Content type
application/json
{
  • "projectId": "string",
  • "eventType": "purchase",
  • "eventDate": "1955-11-12T22:00:00Z",
  • "trackerId": "23jkfs1ufeuih1fh",
  • "nonce": 123456789,
  • "data": {
    }
}

Response samples

Content type
application/json
"da717cf8-cd33-4a6d-a052-68e2096f06b9"

Gets a Raw Event by ID

This endpoint allow 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 endpoint.
Note: The global event search endpoint is not implemented yet, please contact us if you need it.

Authorizations:
JwtBearer
path Parameters
projectId
required
string (project_id) [ 3 .. 64 ] characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

The queried Webmarketer project id

id
required
string <uuid> (events-event_id)
Example: bbee1c25-8718-4c95-b720-b00567113233

Id of the event

Responses

Response samples

Content type
application/json
{
  • "_id": "e5be5b04-0721-4a6e-87eb-b880f81a12d2",
  • "projectId": "your-project",
  • "nonce": "e5be5b04-0721-4a6e-87eb-b880f81a12d2",
  • "eventType": "complaint",
  • "trackerId": "ru1cc7QHeklGu2_3MOzLkLncu3KJAQ",
  • "createdAt": "2004-09-22 14:15:00Z",
  • "data": {
    }
}

Get Trashed events

This endpoint allow 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.

Authorizations:
JwtBearer
path Parameters
projectId
required
string (project_id) [ 3 .. 64 ] characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

The queried Webmarketer project id

query Parameters
since
string <date-time>
Example: since=2023-08-19T22:00:00.000Z

Allow you to filter by a lower date limit (optional)

until
string <date-time>
Example: until=2023-08-21T21:59:59.999Z

Allow you to filter by a upper date limit (optional)

offset
integer
Example: offset=50

Items to skip (pagination)

limit
integer
Example: limit=10

Max returned items (pagination)

Responses

Response samples

Content type
application/json
{
  • "count": 2,
  • "total": 36,
  • "data": [
    ]
}

Event insights (without attribution)

This endpoint allow 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 allow 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.

Authorizations:
JwtBearer
path Parameters
projectId
required
string (project_id) [ 3 .. 64 ] characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

The queried Webmarketer project id

Request Body schema: application/json
since
required
string <date-time>

Allow you to set a lower date limit (optional)

until
required
string <date-time>

Allow you to set an upper date limit (optional)

metrics
required
Array of strings

List of the metrics you want to retrieve, the keys must be the technical keys of state, statistics or event-count.

⚠️ Note that invalid keys will not generate an error, the returned value will always be 0.

groupBy
required
string

The desired breakdown (project or event-type)

interval
required
string

The desired interval can be: day, week, month, quarter, semester, year, dayOfWeek, dayOfMonth, dayOfYear, weekOfYear, monthOfYear, quarterOfYear, semesterOfYear

filter
any

Only pertinent for event-type breakdown, this parameters restrict the retrieved breakdowns.
The endpoint will only return the event types present in this array.
If absent (or with an empty array), all the breakdown values will be returned.

Responses

Request samples

Content type
application/json
{
  • "since": "2023-08-01T22:00:00.000Z",
  • "until": "2023-08-19T22:00:00.000Z",
  • "metrics": [
    ],
  • "groupBy": "`project` or `event-type`",
  • "interval": "`day`, `week`, `month`, `monthOfYear`, etc.",
  • "filter": null
}

Response samples

Content type
application/json
Example

Project breakdown with day interval

[
  • {
    },
  • {
    }
]

Update an event state

This endpoint allow 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" :

  • 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)

Authorizations:
JwtBearer
path Parameters
projectId
required
string (project_id) [ 3 .. 64 ] characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

The queried Webmarketer project id

id
required
string <uuid> (events-event_id)
Example: bbee1c25-8718-4c95-b720-b00567113233

Id of the event

storageKey
required
string
Example: converted

The storage key of the state you want to update

Request Body schema: application/json
value
required
number

The value of the state (0 or 1)

date
string <date-time>

The date when the state changed, leave it blank if not relevant

Responses

Request samples

Content type
application/json
{
  • "value": 1,
  • "date": "2023-05-04T12:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "statusCode": 401,
  • "message": "Unauthorized"
}

Update an event statistic

This endpoint allow 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" :

  • 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)

Authorizations:
JwtBearer
path Parameters
projectId
required
string (project_id) [ 3 .. 64 ] characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

The queried Webmarketer project id

id
required
string <uuid> (events-event_id)
Example: bbee1c25-8718-4c95-b720-b00567113233

Id of the event

storageKey
required
string
Example: turnover

The storage key of the statistic you want to update

Request Body schema: application/json
value
required
number

The value of the statistic

date
string <date-time>

The date you want the statistic changed, leave it blank if not relevant

Responses

Request samples

Content type
application/json
{
  • "value": 4000,
  • "date": "2023-05-04T12:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "statusCode": 401,
  • "message": "Unauthorized"
}

Event Types

Everything about event-types

Get event types

This endpoint allow you to retrieve the list of your project event-types.

The result is paginated.

Authorizations:
JwtBearer
path Parameters
projectId
required
string (project_id) [ 3 .. 64 ] characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

The queried Webmarketer project id

query Parameters
offset
integer
Example: offset=50

Items to skip (pagination)

limit
integer
Example: limit=10

Max returned items (pagination)

search
string
Example: search=form

Pattern to search (in event type's name or reference)

archived
boolean

if set to true, returns the archived event types

storageKey
string
Example: storageKey=first_name

Return only event types containing one field with the passed storage key

reference
string
Example: reference=contact-form

Return the event types with the passed reference

sort
string
Example: sort=name,-createdAt

Sort the event list by the passed fields.

Ascending sort can be done by specifying the property name you want to sort by (name), to sort by descending order, prefix the property name with a minus sign (-name).

You can specify multiple sort by separating them with a comma (,).

Responses

Response samples

Content type
application/json
{
  • "total": 2,
  • "count": 2,
  • "data": [
    ]
}

Create an event-type

This endpoint allow you to create a new event-type.

Request Body schema: application/json

The event-type to create

reference
string

Technical reference of the event type

name
string

The name of the event type (displayed in Webmarketer)

Array of objects

The fields, states and statistics of the event type

metadata
object

The metadata of the event type, not used for now

object

Responses

Request samples

Content type
application/json
{
  • "reference": "contact-form",
  • "name": "Contact Form",
  • "fields": [
    ],
  • "metadata": { },
  • "expirationPolicy": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "64ea0e9471360401bc438ef6",
  • "createdAt": "2023-07-21T10:57:00Z",
  • "updatedAt": "2023-08-26T14:35:00Z",
  • "archivedAt": null,
  • "projectId": "your-project",
  • "reference": "contact-form",
  • "name": "Generic Contact form",
  • "fields": [
    ],
  • "metadata": {
    },
  • "phoneParsingConfig": [
    ]
}

Get an event type

This endpoint allow you to retrieve a specific event-type

Authorizations:
JwtBearer
path Parameters
projectId
required
string (project_id) [ 3 .. 64 ] characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

The queried Webmarketer project id

id
required
string

The event type reference

Responses

Response samples

Content type
application/json
{
  • "_id": "64ea0e9471360401bc438ef6",
  • "createdAt": "2023-07-21T10:57:00Z",
  • "updatedAt": "2023-08-26T14:35:00Z",
  • "archivedAt": null,
  • "projectId": "your-project",
  • "reference": "contact-form",
  • "name": "Generic Contact form",
  • "fields": [
    ],
  • "metadata": {
    },
  • "phoneParsingConfig": [
    ]
}

Interactions

Create offline interaction

This endpoint allow 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.

Authorizations:
JwtBearer
path Parameters
projectId
required
string (project_id) [ 3 .. 64 ] characters ^[a-z0-9]+(?:-[a-z0-9]+)*$

The queried Webmarketer project id

Request Body schema: application/json
date
string <date-time>

Date of the offline interaction, see Date Specification section for more information.

userData
object

Data used to identify the user

nodeData
object

Data used to identify the advertiser node

Responses

Request samples

Content type
application/json
{
  • "date": "2023-08-01T22:00:00.000Z",
  • "userData": {
    },
  • "nodeData": {
    }
}

Response samples

Content type
application/json
{
  • "statusCode": 400,
  • "message": "wmktId must be present in nodeData",
  • "error": "Bad Request"
}