Introduction
Welcome to the Odyssey API documentation. This document gives you all the information you need to get started with getting analyzed data out of Odyssey.
If you want to get your custom data into Odyssey, check out the custom data integration documentation.
The base URI of the Odyssey API is https://api.odysseyattribution.co/api/
.
Authenticating your requests
Authentication with the Odyssey API is done using bearer tokens in the Authorization
API header.
curl -H "Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZXN0IjoidGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUifQ.tRg7qdMaMa7HfLQi3TT8v0BaLiBpqdZz8ZkYLK023Rw" https://api.odysseyattribution.co/api/accounts/list
To obtain a token, you can authenticate with the API using an email address and password (see below).
Token expiration
The bearer tokens used by the API can expire. If your token has expired, you will return a 419 status code from the API.
In this case, you have two options:
Token invalidation
If at any point you receive a 401 status code from the API (including when you are trying to refresh), your token is not valid. You should then attempt to login again.
Authentication
Log in
POST /authentication/login
Attempt to authenticate with Odyssey. If we don't recognize you, we will return a 401 status code.
Parameters
Name | Located in | Description | Type |
---|---|---|---|
request | Your email address | string | |
password | request | Your password | string |
Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZXN0IjoidGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUifQ.tRg7qdMaMa7HfLQi3TT8v0BaLiBpqdZz8ZkYLK023Rw"
}
Refresh an expired authentication token
POST /authentication/refresh
This method uses the token given in the Authorization header.
Returns a 401 if the token can not be refreshed for any reason.
Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZXN0IjoidGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUifQ.tRg7qdMaMa7HfLQi3TT8v0BaLiBpqdZz8ZkYLK023Rw"
}
Validate auth token
POST /authentication/validate
Response
{
"message": "token valid"
}
Send a reset link to the given user.
POST /authentication/password/forgot
Parameters
Name | Located in | Description | Type |
---|---|---|---|
request | the users email address | string |
Response
"Request has been received"
Resets the users password
POST /authentication/password/reset
Parameters
Name | Located in | Description | Type |
---|---|---|---|
request | the users email address | string | |
token | request | token that has been sent by email to the user | string |
password | request | min:6 the new password | string |
password_confirmation | request | repeat the new password | string |
Response
null
Invites
Retrieve an invite
GET /invites/{invite}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
invite | path | \Invite |
Response
{
"email": "you@example.com",
"code": "XXXXXXXXXXXXXXX",
"used": false,
"from": "User name",
"account": {
"id": 2,
"name": "Account name",
"analyse_args": {
"max_days": 90
},
"currency_code": "USD",
"archived": 0,
"encrypted": 0,
"display_settings": "{\"extrapolate\":false}",
"source_rules": {
"root": {
"type": "field",
"field": "channelGrouping"
},
"rules": [
{
"rule": {
"===": [
{
"type": "current"
},
{
"type": "field",
"field": "trafficSource.source"
}
]
},
"child_expression": {
"type": "field",
"field": "trafficSource.campaign"
}
},
{
"rule": {
"===": [
{
"type": "current"
},
{
"type": "field",
"field": "channelGrouping"
}
]
},
"child_expression": {
"type": "field",
"field": "trafficSource.source"
}
}
]
}
},
"view": null,
"publisher": null
}
Accept an invite and register an account using it
POST /invites
This method can be called without authentication. A new user account will be created, and the invite will be accepted on behalf of the new user.
Returns 201 if the action succeeds
Parameters
Name | Located in | Description | Type |
---|---|---|---|
code | request | Invite code | string |
name | request | Name for the new user | string |
request | Email for the new user | string | |
password | request | Password for the new user | string |
Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZXN0IjoidGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUifQ.tRg7qdMaMa7HfLQi3TT8v0BaLiBpqdZz8ZkYLK023Rw"
}
Accept an invite
PUT /invites
This method accepts an invite as the authenticated user. Accepting the invite means that the user will be added to the account or view the invite is for.
Parameters
Name | Located in | Description | Type |
---|---|---|---|
code | request | Invite code | string |
Response
201
Users
Get info about the logged in user
GET /users/me
Response
{
"name": "name",
"email": "example@email.co",
"agency": {
"id": 1,
"name": "Agency Name"
},
"id": "me",
"roles": [
"admin"
]
}
Accounts
List all accounts you have access to
GET /accounts/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
archived | request | (default: 0 (false)) | boolean |
Response
[
{
"id": 2,
"name": "Account name",
"analyse_args": {
"max_days": 90
},
"currency_code": "USD",
"main_view_id": 1,
"archived": 0,
"encrypted": 0,
"display_settings": "{\"extrapolate\":false}",
"source_rules": {
"root": {
"type": "field",
"field": "channelGrouping"
},
"rules": [
{
"rule": {
"===": [
{
"type": "current"
},
{
"type": "field",
"field": "trafficSource.source"
}
]
},
"child_expression": {
"type": "field",
"field": "trafficSource.campaign"
}
},
{
"rule": {
"===": [
{
"type": "current"
},
{
"type": "field",
"field": "channelGrouping"
}
]
},
"child_expression": {
"type": "field",
"field": "trafficSource.source"
}
}
]
},
"canAccessSettings": true,
"views": [
{
"id": 1,
"name": "raw_data",
"account_id": 2,
"is_locked": 0,
"commission_function": "-2 * density.own * maxcom * (position -1)",
"max_com": 0.2
}
]
}
]
Get all available account creation parameters
GET /accounts/parameters
Response
{
"collectors": {
"App\\Analysis\\Collectors\\BigQueryAnalyticsCollector": {
"display_name": "Google Analytics",
"fields": [
{
"name": "dataset",
"display_name": "Data set",
"required": true,
"placeholder": "analytics.01234567",
"explanation": "The name of the BigQuery data set."
}
],
"preprocessing": [
{
"class": "App\\Processing\\Pre\\Tasks\\GoogleAnalyticsRevenueTask",
"settings": []
}
],
"semaphore": "App\\Semaphores\\BigQuerySemaphore",
"default_hierarchy": "{\"root\":{\"type\":\"field\",\"field\":\"channelGrouping\"},\"rules\":[{\"rule\":{\"===\":[{\"type\":\"current\"},{\"type\":\"field\",\"field\":\"trafficSource.source\"}]},\"child_expression\":{\"type\":\"field\",\"field\":\"trafficSource.campaign\"}},{\"rule\":{\"===\":[{\"type\":\"current\"},{\"type\":\"field\",\"field\":\"channelGrouping\"}]},\"child_expression\":{\"type\":\"field\",\"field\":\"trafficSource.source\"}}]}"
}
},
"hierarchical_rules_schema": {
"$schema": "http:\/\/json-schema.org\/draft-07\/schema#",
"title": "Odyssey hierarchical definition",
"type": "object"
}
}
Create a new account
POST /accounts
You can only do this if you have agency access.
Parameters
Name | Located in | Description | Type |
---|---|---|---|
name | request | string | |
collector | request | \enum | |
collector_args | request | \json | |
analyse_args | request | \json | |
currency_code | request | string | |
source_rules | request | (optional) See /account/parameters endpoint for JSON schema to validate against. | \json |
Response
{
"id": 1,
"name": "Account name",
"analyse_args": "{\"max_days\":90}",
"currency_code": "USD",
"main_view_id": 1,
"archived": false,
"encrypted": false,
"canAccessSettings": true
}
Retrieve an account
GET /accounts/{account}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account |
Response
{
"id": 1,
"name": "Account name",
"analyse_args": "{\"max_days\":90}",
"currency_code": "USD",
"main_view_id": 1,
"archived": false,
"encrypted": false,
"canAccessSettings": true
}
Update an account
PUT /accounts/{account}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
name | request | string | |
analyse_args | request | \json | |
main_view_id | request | \id | |
archived | request | boolean |
Response
{
"id": 2,
"name": "adidas US",
"analyse_args": {
"max_days": 90
},
"currency_code": "USD",
"main_view_id": 1,
"archived": 0,
"encrypted": 0,
"display_settings": "{\"extrapolate\":false}",
"source_rules": {
"root": {
"type": "field",
"field": "channelGrouping"
},
"rules": [
{
"rule": {
"===": [
{
"type": "current"
},
{
"type": "field",
"field": "trafficSource.source"
}
]
},
"child_expression": {
"type": "field",
"field": "trafficSource.campaign"
}
},
{
"rule": {
"===": [
{
"type": "current"
},
{
"type": "field",
"field": "channelGrouping"
}
]
},
"child_expression": {
"type": "field",
"field": "trafficSource.source"
}
}
]
},
"canAccessSettings": true
}
Get the range of available data for a given account
GET /accounts/{account}/datarange
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account |
Response
{
"ranges": [
{
"start": "2018-10-10",
"end": "2018-10-10"
}
],
"startDate": "2018-10-10",
"endDate": "2018-10-10"
}
Attempt to trigger data collection for the given account in the given date range
POST /accounts/{account}/collect/{from}/{to}
If the given date range does not make for a continuous segment with the existing data, it will be extended
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
from | path | ||
to | path |
Response
201
Get the job log for a given account
GET /accounts/{account}/jobs/list
TODO: document params and return for pagination
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
page | request | (query)(optional) The number of the requested page. | int |
Response
{
"current_page": 1,
"data": [
{
"id": 30,
"created_at": "2018-10-15 15:24:13",
"updated_at": "2018-10-15 15:24:13",
"state": "finished",
"description": "Calculates data for view TEST on date Oct 10, 2018",
"error": "0",
"progress": 1
}
],
"from": 1,
"last_page": 2,
"next_page_url": "{host}\/api\/accounts\/{account}\/jobs\/list?page=2",
"path": "{host}\/api\/accounts\/{account}\/jobs\/list",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 16
}
Add a user to an account
POST /accounts/{account}/users
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
request | Email for the user to invite | string |
Response
"The invite has been sent"
List all users in an account
GET /accounts/{account}/users/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account |
Response
[
{
"name": "Name",
"email": "example@email.co"
}
]
Remove user from an account
DELETE /accounts/{account}/users/{email}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
path | string |
Response
"The user has been removed"
Get a list of field ids that are available to the specified account
GET /accounts/{account}/datastudio/availablefields
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account |
Response
null
Create a view
POST /accounts/{account}/views
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
name | request | string |
Response
{
"name": "View name",
"account_id": 1,
"id": 1
}
Get the views in an account
GET /accounts/{account}/views/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account |
Response
[
{
"id": 1,
"name": "Raw data",
"account_id": 1,
"is_locked": 0,
"commission_function": "-2 * density.own * maxcom * (position -1)",
"max_com": 0.2
}
]
Get data in a format Google Data Studio can understand
GET /accounts/{account}/views/all/analysis/{from}/{to}/datastudio
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | request | \View | |
from | path | \date | |
to | path | \date | |
parent | request | \TrafficSource |
Response
[
{
"traffic_source": "Source Name",
"volume": 100,
"revenue": 10000,
"incrementality": 0.424242,
"revenue_share": 1234.123,
"attributed_revenue": 678.9999
}
]
Get data in a format Google Data Studio can understand
GET /accounts/{account}/views/all/analysis/{from}/{to}/datastudio/{parent}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | request | \View | |
from | path | \date | |
to | path | \date | |
parent | path | \TrafficSource |
Response
[
{
"traffic_source": "Source Name",
"volume": 100,
"revenue": 10000,
"incrementality": 0.424242,
"revenue_share": 1234.123,
"attributed_revenue": 678.9999
}
]
Get view
GET /accounts/{account}/views/{view}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View |
Response
{
"id": 1,
"name": "Raw data",
"account_id": 1,
"is_locked": 0,
"commission_function": "-2 * density.own * maxcom * (position -1)",
"max_com": 0.2
}
Update a view
PUT /accounts/{account}/views/{view}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
name | request | string | |
commission_function | request | string | |
max_com | request | double |
Response
{
"id": 1,
"name": "Raw data",
"account_id": 1,
"is_locked": 0,
"commission_function": "-2 * density.own * maxcom * (position -1)",
"max_com": 0.2
}
Remove a view
DELETE /accounts/{account}/views/{view}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View |
Response
204
Get a row of sample analysis data for a view
GET /accounts/{account}/views/{view}/sample
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View |
Response
{
"traffic_source_id": 1,
"traffic_source_name": "Direct",
"current_commission": -1,
"channel_grouping": "Direct",
"view_id": 1,
"volume": 1000,
"revenue": 10000,
"total_clicks": 1000,
"position": 0.5,
"length": 2,
"cost": 50.09,
"days": 1.2,
"density": {
"own": 0.5,
"other": [
{
"traffic_source_id": 3,
"traffic_source": "Google",
"channel_grouping": "Organic Search",
"density": 0.2
},
{
"traffic_source_id": 7,
"traffic_source": "Google",
"channel_grouping": "Paid Search",
"density": 0.01
},
{
"traffic_source_id": 5,
"traffic_source": "Newsletter",
"channel_grouping": "Email",
"density": 0.002
}
]
},
"distribution": {
"data": [
1,
0.80845607113291,
0.6703536726046,
0.5605402302315,
0.50917447948189,
0.38197152621337,
0.35740465152519,
0.3270878971298,
0.31724814808399,
0.3
],
"max": 1000,
"step": 8000
},
"suggested_commission": 0.1,
"maxcom": 0.2
}
Get the lock status for a view
GET /accounts/{account}/views/{view}/locked
The lock indicates if any data analysis operations are running for a given view
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View |
Response
0
Get the range of available data for a view
GET /accounts/{account}/views/{view}/datarange
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View |
Response
{
"startDate": "2016-01-01",
"endDate": "2017-01-01"
}
Gets a list of all the segments of the given parameters.
GET /accounts/{account}/views/{view}/segments/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View |
Response
[
{
"id": 1,
"account_id": 1,
"name": "segment_name"
}
]
Gets the segment for the given parameters.
GET /accounts/{account}/views/{view}/segments/{segment}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment | path | \Segment |
Response
{
"id": 1,
"account_id": 1,
"name": "segment_name"
}
List the annotations for the given parameters.
GET /accounts/{account}/views/{view}/segments/{segment}/annotations/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment | path | (optional) | \Segment |
annotation | request | \Annotation |
Response
null
Create an annotation
POST /accounts/{account}/views/{view}/segments/{segment}/annotations
Parameters
Name | Located in | Description | Type |
---|---|---|---|
r | request | \AnnotationCreateRequest | |
account | path | \Account | |
view | path | \View | |
segment | path | (optional) | \Segment |
from_date | request | \date | |
to_date | request | \date | |
text | request | string |
Response
null
Get the annotation for the given parameters.
GET /accounts/{account}/views/{view}/segments/{segment}/annotations/{annotation}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment | path | (optional) | \Segment |
annotation | path | \Annotation |
Response
null
Update an annotation
PUT /accounts/{account}/views/{view}/segments/{segment}/annotations/{annotation}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment | path | (optional) | \Segment |
annotation | path | \Annotation | |
text | request | string | |
from_date | request | \date | |
to_date | request | \date |
Response
null
Destroy an annotation
DELETE /accounts/{account}/views/{view}/segments/{segment}/annotations/{annotation}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment | path | (optional) | \Segment |
annotation | path | \Annotation |
Response
"The annotation has been removed"
Get analysis for a given view with a given daterange
GET /accounts/{account}/views/{view}/analysis/{from}/{to}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
from | path | \date | |
to | path | \date | |
parent | request | \TrafficSource |
Response
null
Get analysis for a given view with a given daterange
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/timeseries
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
from | path | \date | |
to | path | \date | |
parent | request | \TrafficSource |
Response
[
{
"traffic_source": {
"id": 1,
"name": "Paid Search",
"type": "paid",
"has_children": true,
"parent_id": null
},
"volume": [
{
"name": "2019-07-02",
"value": 3050
},
{
"name": "2019-07-03",
"value": 3028
}
],
"revenue": [
{
"name": "2019-07-02",
"value": 176159.256
},
{
"name": "2019-07-03",
"value": 175844.8657
}
],
"position": [
{
"name": "2019-07-02",
"value": 0.4579079
},
{
"name": "2019-07-03",
"value": 0.4491251
}
],
"density": {
"own": [
{
"name": "2019-07-02",
"value": "0.5945420000"
},
{
"name": "2019-07-03",
"value": "0.5658010000"
}
]
}
}
]
Get analysis for a given view with a given daterange
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/parent/{parent}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
from | path | \date | |
to | path | \date | |
parent | path | \TrafficSource |
Response
null
Get analysis for a given view with a given daterange
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/parent/{parent}/timeseries
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
from | path | \date | |
to | path | \date | |
parent | path | \TrafficSource |
Response
[
{
"traffic_source": {
"id": 1,
"name": "Paid Search",
"type": "paid",
"has_children": true,
"parent_id": null
},
"volume": [
{
"name": "2019-07-02",
"value": 3050
},
{
"name": "2019-07-03",
"value": 3028
}
],
"revenue": [
{
"name": "2019-07-02",
"value": 176159.256
},
{
"name": "2019-07-03",
"value": 175844.8657
}
],
"position": [
{
"name": "2019-07-02",
"value": 0.4579079
},
{
"name": "2019-07-03",
"value": 0.4491251
}
],
"density": {
"own": [
{
"name": "2019-07-02",
"value": "0.5945420000"
},
{
"name": "2019-07-03",
"value": "0.5658010000"
}
]
}
}
]
Get the statistics of an analysis for a given view with a given daterange
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/stats
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
from | path | \date | |
to | path | \date |
Response
{
"collected_days": [
"2018-10-01"
],
"total_revenue": 100000,
"analysed_revenue": 75000,
"total_journeys": 1000,
"analysed_journeys": 1100,
"returned_revenue": 35000
}
Get the statistics of an analysis for a given view with a given daterange in timeseries format
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/stats/timeseries
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
from | path | \date | |
to | path |
Response
{
"collected_days": [
"2019-01-01"
],
"total_revenue": [
{
"name": "2019-01-01",
"value": "10000.00"
}
],
"analysed_revenue": [
{
"name": "2019-01-01",
"value": "9000.00"
}
],
"total_journeys": [
{
"name": "2019-01-01",
"value": "1000"
}
],
"analysed_journeys": [
{
"name": "2019-01-01",
"value": "9000"
}
]
}
Gets the search results for the given parameters
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/search
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
from | path | \date | |
to | path | \date |
Response
null
Get analysis of children that are not parent and have a minimum cost of 0.0
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/overspend
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
from | path | \date | |
to | path | \date | |
segment | request | \Segment |
Response
[
{
"traffic_source": {
"id": 2,
"account_id": 1,
"name": "source",
"type": "commissionable",
"has_children": false,
"parent_id": 1
},
"density": {
"own": 0.25,
"other": []
},
"position": 0.75,
"cost": 500,
"volume": 450,
"revenue": 7000,
"returned_revenue": 3000,
"length": 4.7
}
]
Show an annotation
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/annotations
Parameters
Name | Located in | Description | Type |
---|---|---|---|
r | request | \Request | |
account | path | \Account | |
view | path | \View | |
segment | request | (optional) | \Segment |
from | path | \date | |
to | path | \date |
Response
{
"id": 1,
"text": "text",
"from_date": "2020-01-01",
"to_date": "2020-01-01",
"user": {
"id": 1,
"name": "Test User",
"email": "test@test.com"
}
}
Get custom analysis
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/custom
This endpoint will be more customizable in the future.
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment | request | (optional) | \Segment |
sources | request | \TrafficSource[] | |
from | path | \date | |
to | path | \date |
Response
[
{
"view_id": 1,
"volume": 761,
"revenue": 43534.3622,
"total_clicks": 5317,
"position": 0.47862023653088037,
"length": 4.091984231274639,
"days": 2.5448226018396847,
"date": "2018-10-08",
"cost": null,
"density": {
"own": 0.060042614980289094,
"other": [
{
"density": 0.014795939553219447,
"traffic_source_id": 124,
"traffic_source": "Organic Search",
"parent_id": null,
"children": []
}
]
},
"distribution": {
"data": [
0.9922437673130231,
1,
0.9747922437673129,
0.6878116343490257,
0.45318559556786775,
0.8952908587257682,
0.6664819944598388,
0.44542936288088897,
0.4047091412742372,
0.3
],
"max": 311.6999999999996,
"step": 275.5999999999994
},
"suggested_commission": 0.012522001758596206,
"incrementality": 0.06261000879298102,
"traffic_source": {
"id": 122,
"name": "google",
"type": null,
"has_children": true,
"parent_id": 121
}
}
]
Get custom timeseries analysis
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/custom/timeseries
This endpoint will be more customizable in the future.
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment | request | (optional) | \Segment |
sources | request | \TrafficSource[] | |
from | path | \date | |
to | path | \date |
Response
[
[
{
"traffic_source": {
"id": 1,
"account_id": 1,
"name": "Branded",
"parent_id": null,
"type": "paid",
"display_name": null,
"has_children": 1
},
"volume": [
{
"name": "2019-11-01",
"value": 100
},
{
"name": "2019-11-02",
"value": 100
}
],
"revenue": [
{
"name": "2019-11-01",
"value": 10000
},
{
"name": "2019-11-02",
"value": 10000
}
],
"position": [
{
"name": "2019-11-01",
"value": 0.4
},
{
"name": "2019-11-02",
"value": 0.5
}
],
"density": {
"own": [
{
"name": "2019-11-01",
"value": 0.7
},
{
"name": "2019-11-02",
"value": 0.8
}
]
}
}
]
]
Aggregates the unmatched integration data for $parent
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/unmatched
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
from | path | \Carbon | |
to | path | \Carbon | |
parent | request | \TrafficSource |
Response
{
"dates": [
"2020-01-01"
],
"cost": 1000,
"impressions": 1000,
"clicks": 1000,
"integration_id": [
1,
2
]
}
Aggregates the unmatched integration data for $parent
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/parent/{parent}/unmatched
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
from | path | \Carbon | |
to | path | \Carbon | |
parent | path | \TrafficSource |
Response
{
"dates": [
"2020-01-01"
],
"cost": 1000,
"impressions": 1000,
"clicks": 1000,
"integration_id": [
1,
2
]
}
Get data in a format Google Data Studio can understand
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/datastudio
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
from | path | \date | |
to | path | \date | |
parent | request | \TrafficSource |
Response
[
{
"traffic_source": "Source Name",
"volume": 100,
"revenue": 10000,
"incrementality": 0.424242,
"revenue_share": 1234.123,
"attributed_revenue": 678.9999
}
]
Get data in a format Google Data Studio can understand
GET /accounts/{account}/views/{view}/analysis/{from}/{to}/datastudio/{parent}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
from | path | \date | |
to | path | \date | |
parent | path | \TrafficSource |
Response
[
{
"traffic_source": "Source Name",
"volume": 100,
"revenue": 10000,
"incrementality": 0.424242,
"revenue_share": 1234.123,
"attributed_revenue": 678.9999
}
]
List the traffic sources in a view
GET /accounts/{account}/views/{view}/trafficsources/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View |
Response
[
{
"id": 3,
"name": "google",
"type": ""
},
{
"id": 4,
"name": "google",
"type": ""
}
]
Get a traffic source from a view
GET /accounts/{account}/views/{view}/trafficsources/{trafficsource}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
source | request | \TrafficSource | |
trafficsource | path |
Response
{
"id": 1,
"name": "google",
"type": "paid",
"parents": [
{
"id": 2,
"name": "Paid Search"
}
]
}
Get results for a traffic source for given $from and $to dates, with optional metric field filter.
GET /accounts/{account}/views/{view}/trafficsources/{trafficsource}/analysis/{from}/{to}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment | request | (optional) | \Segment |
trafficsource | path | \TrafficSource | |
from | path | \date | |
to | path | \date | |
fields | request | (optional) | array |
Response
{
"view_id": 1,
"volume": 761,
"revenue": 43534.3622,
"total_clicks": 5317,
"position": 0.47862023653088037,
"length": 4.091984231274639,
"days": 2.5448226018396847,
"date": "2018-10-08",
"cost": null,
"density": {
"own": 0.060042614980289094,
"other": [
{
"density": 0.014795939553219447,
"traffic_source_id": 124,
"traffic_source": "Organic Search",
"parent_id": null,
"children": []
}
]
},
"distribution": {
"data": [
0.9922437673130231,
1,
0.9747922437673129,
0.6878116343490257,
0.45318559556786775,
0.8952908587257682,
0.6664819944598388,
0.44542936288088897,
0.4047091412742372,
0.3
],
"max": 311.6999999999996,
"step": 275.5999999999994
},
"suggested_commission": 0.012522001758596206,
"incrementality": 0.06261000879298102,
"traffic_source": {
"id": 122,
"name": "google",
"type": null,
"has_children": true,
"parent_id": 121
}
}
List the users in a view
GET /accounts/{account}/views/{view}/users/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View |
Response
[
{
"name": "Niels",
"email": "example@email.co"
}
]
Invite a user to a view
POST /accounts/{account}/views/{view}/users
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
request | Email address for the user to invite | string |
Response
"The invite has been sent"
Remove a user from a view
DELETE /accounts/{account}/views/{view}/users/{email}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
path | string |
Response
"The user has been removed"
List Targets
GET /accounts/{account}/views/{view}/targets/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View |
Response
[
{
"id": 1,
"view_id": 1,
"segment_id": 1,
"traffic_source_id": null,
"interval": "week",
"start_date": "2019-01-01",
"end_date": "2019-01-01",
"name": "Target",
"metric": "incrementality",
"values": {
"2019-01-01": 0.85
}
}
]
Create Target
POST /accounts/{account}/views/{view}/targets
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment_id | request | (optional) | \Segment |
traffic_source_id | request | (optional) | \TrafficSource |
name | request | string | |
metric | request | string | |
interval | request | string | |
start_date | request | \Date | |
end_date | request | \Date | |
values | request | array |
Response
{
"id": 1,
"view_id": 1,
"segment_id": 1,
"traffic_source_id": null,
"interval": "week",
"start_date": "2019-01-01",
"end_date": "2019-01-01",
"name": "Target",
"metric": "incrementality",
"values": {
"2019-01-01": 0.85
}
}
Get target.
GET /accounts/{account}/views/{view}/targets/{target}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
target | path | \Target |
Response
{
"id": 1,
"view_id": 1,
"segment_id": 1,
"traffic_source_id": null,
"interval": "week",
"start_date": "2019-01-01",
"end_date": "2019-01-01",
"name": "Target",
"metric": "incrementality",
"values": {
"2019-01-01": 0.85
}
}
Update Target
PUT /accounts/{account}/views/{view}/targets/{target}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment_id | request | (optional) | \Segment |
traffic_source_id | request | (optional) | \TrafficSource |
name | request | (optional) | string |
metric | request | (optional) | string |
interval | request | (optional) | string |
start_date | request | (optional) | \Date |
end_date | request | (optional) | \Date |
values | request | (optional) | array |
target | path |
Response
{
"id": 1,
"view_id": 1,
"segment_id": 1,
"traffic_source_id": null,
"interval": "week",
"start_date": "2019-01-01",
"end_date": "2019-01-01",
"name": "Target",
"metric": "incrementality",
"values": {
"2019-01-01": 0.85
}
}
Remove target
DELETE /accounts/{account}/views/{view}/targets/{target}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
target | path | \Target |
Response
null
List the annotations for the given parameters.
GET /accounts/{account}/views/{view}/annotations/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment | request | (optional) | \Segment |
annotation | request | \Annotation |
Response
null
Create an annotation
POST /accounts/{account}/views/{view}/annotations
Parameters
Name | Located in | Description | Type |
---|---|---|---|
r | request | \AnnotationCreateRequest | |
account | path | \Account | |
view | path | \View | |
segment | request | (optional) | \Segment |
from_date | request | \date | |
to_date | request | \date | |
text | request | string |
Response
null
Get the annotation for the given parameters.
GET /accounts/{account}/views/{view}/annotations/{annotation}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment | request | (optional) | \Segment |
annotation | path | \Annotation |
Response
null
Update an annotation
PUT /accounts/{account}/views/{view}/annotations/{annotation}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment | request | (optional) | \Segment |
annotation | path | \Annotation | |
text | request | string | |
from_date | request | \date | |
to_date | request | \date |
Response
null
Destroy an annotation
DELETE /accounts/{account}/views/{view}/annotations/{annotation}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
view | path | \View | |
segment | request | (optional) | \Segment |
annotation | path | \Annotation |
Response
"The annotation has been removed"
Create a trafficSource.
POST /accounts/{account}/trafficsources
Parameters
Name | Located in | Description | Type |
---|---|---|---|
type | request | string | |
name | request | string | |
parent_id | request | (optional) | integer |
account | path | \Account | |
trafficSource | request | \TrafficSource |
Response
{
"name": "Paid Search",
"id": 1
}
Get a list of all the traffic source for one account. Traffic source consists of an ID and a name
GET /accounts/{account}/trafficsources/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account |
Response
[
{
"id": 121,
"name": "Paid Search",
"type": null
},
{
"id": 122,
"name": "google",
"type": null
}
]
Get a list of all the traffic source for one account. Traffic source consists of an ID and a name
GET /accounts/{account}/trafficsources/list/{parent}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
parent | path |
Response
[
{
"id": 121,
"name": "Paid Search",
"type": null
},
{
"id": 122,
"name": "google",
"type": null
}
]
Get available publishers in an account to share data with
GET /accounts/{account}/trafficsources/publishers/available
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account |
Response
[
{
"id": 1,
"name": "Publisher Name"
}
]
Get the sources that have been shared for an account
GET /accounts/{account}/trafficsources/publishers/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account |
Response
[
{
"id": 4,
"name": "Generic Paid Search",
"parent_id": null,
"type": null,
"publishers": [
{
"id": 2,
"name": "Publisher Name",
"permissions": {
"volume": true,
"revenue": true,
"ga_sessions": true,
"ga_bounces": true,
"ga_new_users": true,
"total_clicks": true,
"cost": true,
"position": true,
"length": true,
"days": true,
"density": false,
"distribution": true,
"incrementality": true,
"children": true
}
}
]
}
]
Retrieve a traffic source
GET /accounts/{account}/trafficsources/{trafficsource}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
trafficsource | path | \TrafficSource |
Response
{
"id": 123,
"name": "Trademark-Brand-B-EXACT",
"type": "",
"parents": [
{
"id": 122,
"name": "google"
},
{
"id": 121,
"name": "Paid Search"
}
]
}
Retrieve the children of a traffic source
GET /accounts/{account}/trafficsources/{trafficsource}/children/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
trafficsource | path | \TrafficSource |
Response
null
Update/Set the type of a trafficSource and its children.
PUT /accounts/{account}/trafficsources/{trafficsource}
- > Example body
{
"type": "paid" //(paid, commissionable, organic, null)
}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
type | request | string | |
account | path | \Account | |
trafficSource | request | \TrafficSource | |
trafficsource | path |
Response
Share account data with a publisher and create and invite publiser if publisher does not exists
POST /accounts/{account}/trafficsources/{trafficsource}/publishers
Example body
{
"volume": true,
"length": true,
"density": true,
"distribution": true,
"days": true,
"revenue": true,
"total_clicks": true,
"position": true,
"incrementality": true,
"children": true,
"ga_sessions": true
"ga_bounces": true
"ga_new_users": true
"name": "newPublisher",
"email": "new-publisher@example.com"
}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
trafficsource | path | \TrafficSource | |
publisher | request | \Publisher | |
volume | request | (optional) | boolean |
length | request | (optional) | boolean |
density | request | (optional) | boolean |
distribution | request | (optional) | boolean |
days | request | (optional) | boolean |
position | request | (optional) | boolean |
incrementaltiy | request | (optional) | boolean |
children | request | (optional) | boolean |
ga_sessions | request | (optional) | boolean |
ga_bounces | request | (optional) | boolean |
ga_new_users | request | (optional) | boolean |
name | request | (required) | string |
request | (required) | string |
Response
"Traffic source successfully shared"
Retrieve a publisher
GET /accounts/{account}/trafficsources/{trafficsource}/publishers/{publisher}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
source | request | \TrafficSource | |
publisher | path | \Publisher | |
trafficsource | path |
Response
{
"id": 1,
"name": "Publisher",
"permissions": {
"volume": false,
"revenue": false,
"ga_sessions": false,
"ga_bounces": false,
"ga_new_users": false,
"total_clicks": false,
"cost": false,
"position": false,
"length": true,
"days": false,
"density": false,
"distribution": false,
"incrementality": false,
"children": false
}
}
Unshare data with a publisher
DELETE /accounts/{account}/trafficsources/{trafficsource}/publishers/{publisher}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
trafficsource | path | \TrafficSource | |
publisher | path |
Response
"Traffic source successfully un-shared"
Share account data with a publisher
PUT /accounts/{account}/trafficsources/{trafficsource}/publishers/{publisher}
Example body
{
"volume": true,
"length": true,
"density": true,
"distribution": true,
"days": true,
"position": true,
"revenue": true,
"total_clicks": true,
"incrementality": true,
"children": true,
"ga_sessions": true
"ga_bounces": true
"ga_new_users": true
}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
trafficsource | path | \TrafficSource | |
publisher | path | \Publisher | |
volume | request | (optional) | boolean |
length | request | (optional) | boolean |
density | request | (optional) | boolean |
distribution | request | (optional) | boolean |
days | request | (optional) | boolean |
position | request | (optional) | boolean |
revenue | request | (optional) | boolean |
cost | request | (optional) | boolean |
incrementality | request | (optional) | boolean |
children | request | (optional) | boolean |
ga_sessions | request | (optional) | boolean |
ga_bounces | request | (optional) | boolean |
ga_new_users | request | (optional) | boolean |
Response
"Traffic source successfully shared"
Get the dates for account
GET /accounts/{account}/dates/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account |
Response
[
{
"id": 1,
"account_id": 1,
"date": "2018-01-01",
"filtered": "{\"complete_journeys\":518,\"lost_not_full_journey\":81,\"unique_transactions\":598,\"lost_max_days\":0,\"lost_no_revenue\":0}",
"extra": {
"revenue": 4792.949999999998
},
"collected": 1,
"tries": 0,
"analysed_journeys": 518
}
]
Get the total analyzed journeys
GET /accounts/{account}/dates/journeys
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account |
Response
2000
Get matched integration data
GET /accounts/{account}/integrations/data/{from}/{to}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
from | path | \Carbon | |
to | path | \Carbon | |
parent | request | \TrafficSource |
Response
[{"_id":{"parent_id":1,"id":2},"dates":["2020-04-01"],"cost":0,"impressions":0,"clicks":0},{"_id":{"parent_id":1,"id":2},"dates":["2020-04-01"],"cost":0,"impressions":0,"clicks":0}]
Get matched integration data
GET /accounts/{account}/integrations/data/{from}/{to}/parent/{parent}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
from | path | \Carbon | |
to | path | \Carbon | |
parent | path | \TrafficSource |
Response
[{"_id":{"parent_id":1,"id":2},"dates":["2020-04-01"],"cost":0,"impressions":0,"clicks":0},{"_id":{"parent_id":1,"id":2},"dates":["2020-04-01"],"cost":0,"impressions":0,"clicks":0}]
Get matched integration sources
GET /accounts/{account}/integrations/sources
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
parent | request | \TrafficSource |
Response
[{"integration_id":[1,2],"source":{"id":1000,"name":"Affiliation","parent_id":null,"type":'commissionable',"display_name":null}}]
Get matched integration sources
GET /accounts/{account}/integrations/sources/parent/{parent}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
parent | path | \TrafficSource |
Response
[{"integration_id":[1,2],"source":{"id":1000,"name":"Affiliation","parent_id":null,"type":'commissionable',"display_name":null}}]
List integrations
GET /accounts/{account}/integrations/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account |
Response
[{"type":"App\Integration\Integrations\AwinIntegration","config":{"accounts":[10000]},"enabled":false}]
Create integration
POST /accounts/{account}/integrations
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
request | request | \Request | |
type | request | string |
Response
{"type":"App\Integration\Integrations\AwinIntegration","config":{},"enabled":false}
Get integration
GET /accounts/{account}/integrations/{integration}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration |
Response
{"type":"App\Integration\Integrations\AwinIntegration","config":{"accounts":[10000]},"enabled":false}
Delete integration
DELETE /accounts/{account}/integrations/{integration}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration |
Response
'The integration has been removed'
Update integration
PUT /accounts/{account}/integrations/{integration}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration | |
request | request | \Request |
Response
{"type":"App\Integration\Integrations\AwinIntegration","config":{},"enabled":false}
Get integration options
GET /accounts/{account}/integrations/{integration}/options
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integrable |
Response
{"options":{"accounts":[{"accountId":1,"accountName":"Awin","accountType":"advertiser","userRole":"userOwner"}]}S}
Save integration configuration
POST /accounts/{account}/integrations/{integration}/config
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration | |
config | request | (based on account and integration) | string |
Response
'Successfully saved configuration'
Authenticate integration
POST /accounts/{account}/integrations/{integration}/authenticate
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integrable |
Response
{"authenticated":true}
Authenticated integration
GET /accounts/{account}/integrations/{integration}/authenticated
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integrable |
Response
{"authenticated":true}
Resets authentication
DELETE /accounts/{account}/integrations/{integration}/authentication
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration |
Response
""
Get unmatched traffic sources for a parent source
GET /accounts/{account}/integrations/{integration}/unmatched
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration | |
parent | request | The parent id | \TrafficSource |
search | request | (optional) Search term https://docs.mongodb.com/manual/reference/operator/query/text/#search-field | string |
sort | request | (optional) Sorting, possible to sort on all keys in response. | string |
ascending | request | (optional) Sorting direction. Defaults to false. | string |
page | request | (optional) page. Defaault is 1. | int |
page_size | request | (optional) total items per page. Default is 50. | int |
Response
{"current_page":1,"data":[{"_id":{"$oid":"aabbcc"},"cost":100,"gads_customer_id":8000000000,"gads_campaign_id":9000000000,"gads_adgroup_id":10000000000}],"first_page_url":"api\/accounts\/1\/integrations\/1\/unmatched?sort=impressions&ascending=true&page=1&page_size=1&search=term","from":1,"last_page":100,"last_page_url":"api\/accounts\/1\/integrations\/1\/unmatched?sort=impressions&ascending=true&page=100&page_size=1&search=term","next_page_url":"api\/accounts\/1\/integrations\/1\/unmatched?sort=impressions&ascending=true&page=2&page_size=1&search=term","path":"api\/accounts\/1\/integrations\/1\/unmatched","per_page":1,"prev_page_url":null,"to":1,"total":100}
Get unmatched traffic sources for a parent source
GET /accounts/{account}/integrations/{integration}/unmatched/parent/{trafficsource}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration | |
parent | request | The parent id | \TrafficSource |
search | request | (optional) Search term https://docs.mongodb.com/manual/reference/operator/query/text/#search-field | string |
sort | request | (optional) Sorting, possible to sort on all keys in response. | string |
ascending | request | (optional) Sorting direction. Defaults to false. | string |
page | request | (optional) page. Defaault is 1. | int |
page_size | request | (optional) total items per page. Default is 50. | int |
trafficsource | path |
Response
{"current_page":1,"data":[{"_id":{"$oid":"aabbcc"},"cost":100,"gads_customer_id":8000000000,"gads_campaign_id":9000000000,"gads_adgroup_id":10000000000}],"first_page_url":"api\/accounts\/1\/integrations\/1\/unmatched?sort=impressions&ascending=true&page=1&page_size=1&search=term","from":1,"last_page":100,"last_page_url":"api\/accounts\/1\/integrations\/1\/unmatched?sort=impressions&ascending=true&page=100&page_size=1&search=term","next_page_url":"api\/accounts\/1\/integrations\/1\/unmatched?sort=impressions&ascending=true&page=2&page_size=1&search=term","path":"api\/accounts\/1\/integrations\/1\/unmatched","per_page":1,"prev_page_url":null,"to":1,"total":100}
Get datarange for integration
GET /accounts/{account}/integrations/{integration}/datarange
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration |
Response
{"startDate":"2020-05-12T00:00:00.000000Z","endDate":"2020-10-10T00:00:00.000000Z"}
List integration source
GET /accounts/{account}/integrations/{integration}/sources/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration |
Response
[{"_id":{"$oid":"a1b2c3d4"},"integration_id":1,"source_id":"a1b2c3","sources":[]}]
Find integration sources
GET /accounts/{account}/integrations/{integration}/sources/find
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration | |
request | request | \Request |
Response
[{"_id":{"$oid":"a1b2c3d4"},"integration_id":1,"source_id":"a1b2c3","sources":[]}]
Get integration source
GET /accounts/{account}/integrations/{integration}/sources/{source_id}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration | |
sourceId | request | string | |
source_id | path |
Response
{"_id":{"$oid":"a1b2c3d4"},"integration_id":1,"source_id":"a1b2c3","sources":[]}
Update integration source
POST /accounts/{account}/integrations/{integration}/sources/{source_id}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration | |
sourceId | request | string | |
fields | request | (based on account and integration) | array |
source_id | path |
Response
{"_id":{"$oid":"a1b2c3d4"},"integration_id":1,"source_id":"a1b2c3","sources":[]}
Manually match integration sources to a odyssey traffic source.
POST /accounts/{account}/integrations/{integration}/trafficsources/{trafficsource}/match
Parameters
Name | Located in | Description | Type |
---|---|---|---|
account | path | \Account | |
integration | path | \Integration | |
source | request | \TrafficSource | |
request | request | \Request | |
trafficsource | path |
Response
{"matched_integration_sources": ["1000", "1001"]}
List transactions
GET /accounts/{account}/transactions/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
request | request | \Request | |
account | path | \Account | |
from_date | request | \Carbon | |
to_date | request | \Carbon | |
sources | request | \TrafficSource[] | |
returned | request | (optional) shows by default all | boolean |
page_size | request | (optional) | integer |
order_by | request | (optional) id, order_date, transaction_id, full_visitor_id | string |
direction | request | (optional) asc, desc | string |
Response
{
"current_page": 1,
"data": [
{
"id": 1,
"account_id": 1,
"order_date": "2020-01-01T00:00:00.000000Z",
"transaction_id": "a1b2c3",
"transaction_coupon": null,
"full_visitor_id": "a1b2c3",
"traffic_sources": [
{
"id": 3,
"account_id": 1,
"name": "korting.nl",
"parent_id": 2,
"type": "commissionable",
"display_name": null,
"parent": {
"id": 2,
"account_id": 1,
"name": "awin",
"parent_id": 1,
"type": "commissionable",
"display_name": null,
"parent": {
"id": 1,
"account_id": 1,
"name": "Affiliation",
"parent_id": null,
"type": "commissionable",
"display_name": null
}
}
}
],
"returned_revenue": 0,
"revenue": 200
}
],
"first_page_url": "https:\/\/api.odysseyattribution.co\/api\/accounts\/1\/transactions\/list?page=1",
"from": 1,
"last_page": 2,
"last_page_url": "https:\/\/api.odysseyattribution.co\/api\/accounts\/1\/transactions\/list?page=3",
"next_page_url": "https:\/\/api.odysseyattribution.co\/api\/accounts\/1\/transactions\/list?page=2",
"path": "https:\/\/api.odysseyattribution.co\/api\/accounts\/1\/transactions\/list",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 30
}
List transactions optimized
GET /accounts/{account}/transactions/list-optimized
Parameters
Name | Located in | Description | Type |
---|---|---|---|
request | request | \Request | |
account | path | \Account | |
from_date | request | \Carbon | |
to_date | request | \Carbon | |
sources | request | \TrafficSource[] | |
page_size | request | (optional) | integer |
order_by | request | (optional) id, order_date | string |
direction | request | (optional) asc, desc | string |
Response
{
"current_page": 1,
"data": [
{
"id": 1,
"account_id": 1,
"order_date": "2020-01-01T00:00:00.000000Z",
"transaction_id": "a1b2c3",
"transaction_coupon": null,
"full_visitor_id": "a1b2c3",
"traffic_sources": [
{
"id": 3,
"account_id": 1,
"name": "korting.nl",
"parent_id": 2,
"type": "commissionable",
"display_name": null,
"parent": {
"id": 2,
"account_id": 1,
"name": "awin",
"parent_id": 1,
"type": "commissionable",
"display_name": null,
"parent": {
"id": 1,
"account_id": 1,
"name": "Affiliation",
"parent_id": null,
"type": "commissionable",
"display_name": null
}
}
}
],
"returned_revenue": 0,
"revenue": 200
}
],
"first_page_url": "https:\/\/api.odysseyattribution.co\/api\/accounts\/1\/transactions\/list?page=1",
"from": 1,
"last_page": 2,
"last_page_url": "https:\/\/api.odysseyattribution.co\/api\/accounts\/1\/transactions\/list?page=3",
"next_page_url": "https:\/\/api.odysseyattribution.co\/api\/accounts\/1\/transactions\/list?page=2",
"path": "https:\/\/api.odysseyattribution.co\/api\/accounts\/1\/transactions\/list",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 30
}
List paginated transactions, does not require traffic sources
GET /accounts/{account}/transactions/list-paged
Parameters
Name | Located in | Description | Type |
---|---|---|---|
request | request | \Request | |
account | path | \Account | |
returned | request | (optional) shows by default all | boolean |
page_size | request | (optional) defaults to 5 | integer |
from_date | request | \Carbon | |
to_date | request | \Carbon | |
order_by | request | (optional) order_date, id, transaction_id, full_visitor_id, default is order_date | string |
direction | request | (optional) desc, asc, default is desc | string |
Response
{
"current_page": 1,
"data": [
{
"id": 1,
"account_id": 1,
"order_date": "2020-01-01T00:00:00.000000Z",
"transaction_id": "a1b2c3",
"transaction_coupon": null,
"full_visitor_id": "a1b2c3",
"traffic_sources": [
{
"id": 3,
"account_id": 1,
"name": "korting.nl",
"parent_id": 2,
"type": "commissionable",
"display_name": null,
"parent": {
"id": 2,
"account_id": 1,
"name": "awin",
"parent_id": 1,
"type": "commissionable",
"display_name": null,
"parent": {
"id": 1,
"account_id": 1,
"name": "Affiliation",
"parent_id": null,
"type": "commissionable",
"display_name": null
}
}
}
],
"returned_revenue": 0,
"revenue": 200
}
],
"first_page_url": "https:\/\/api.odysseyattribution.co\/api\/accounts\/1\/transactions\/list?page=1",
"from": 1,
"last_page": 2,
"last_page_url": "https:\/\/api.odysseyattribution.co\/api\/accounts\/1\/transactions\/list?page=3",
"next_page_url": "https:\/\/api.odysseyattribution.co\/api\/accounts\/1\/transactions\/list?page=2",
"path": "https:\/\/api.odysseyattribution.co\/api\/accounts\/1\/transactions\/list",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 30
}
Query transactions
GET /accounts/{account}/transactions/query
Parameters
Name | Located in | Description | Type |
---|---|---|---|
request | request | \Request | |
account | path | \Account | |
transaction_ids | request | \Transaction[] |
Response
[
{
"id": 1,
"account_id": 1,
"order_date": "2020-01-01T00:00:00.000000Z",
"transaction_id": "a1b2c3",
"transaction_coupon": null,
"full_visitor_id": "a1b2c3",
"traffic_sources": [
{
"id": 4,
"account_id": 1,
"name": "(not set)",
"parent_id": 3,
"type": null,
"display_name": null,
"parent": {
"id": 3,
"account_id": 1,
"name": "(direct)",
"parent_id": 2,
"type": null,
"display_name": null,
"parent": {
"id": 2,
"account_id": 1,
"name": "Direct",
"parent_id": null,
"type": null,
"display_name": null
}
}
}
],
"returned_revenue": 0,
"revenue": 123.45
}
]
Get transaction
GET /accounts/{account}/transactions/{transaction}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
request | request | \Request | |
account | path | \Account | |
transactionId | request | string | |
transaction | path |
Response
{
"id": 1,
"account_id": 1,
"order_date": "2020-01-01T00:00:00.000000Z",
"transaction_id": "a1b2c3",
"transaction_coupon": null,
"full_visitor_id": "a1b2c3",
"traffic_sources": [
{
"id": 3,
"account_id": 1,
"name": "korting.nl",
"parent_id": 2,
"type": "commissionable",
"display_name": null,
"parent": {
"id": 2,
"account_id": 1,
"name": "awin",
"parent_id": 1,
"type": "commissionable",
"display_name": null,
"parent": {
"id": 1,
"account_id": 1,
"name": "Affiliation",
"parent_id": null,
"type": "commissionable",
"display_name": null
}
}
}
],
"returned_revenue": 0,
"revenue": 200
}
Publishers
List all publishers of user
GET /publishers/list
Response
[
{
"id": 1,
"name": "Publisher Name"
}
]
Retrieve a publisher
GET /publishers/{publisher}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
publisher | path | \Publisher |
Response
{
"id": 1,
"name": "Publisher Name"
}
Get the range of data available for a publisher
GET /publishers/{publisher}/datarange
Parameters
Name | Located in | Description | Type |
---|---|---|---|
publisher | path | \Publisher |
Response
{
"startDate": "2016-01-01",
"endDate": "2017-01-01"
}
Get analysis results for a publisher
GET /publishers/{publisher}/analysis/{from}/{to}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
publisher | path | \Publisher | |
from | path | ||
to | path |
Response
[
{
"traffic_source": {
"id": 1,
"name": "Publisher",
"type": "paid",
"has_children": true,
"parent_id": null
},
"cost": 24.99,
"distribution": {
"data": [
1,
0.7,
0.3,
0.1,
0,
0.2,
0.2,
0.8,
0,
0
],
"max": 1.4000000000000001
},
"volume": 5,
"revenue": 400,
"returned_revenue": 150,
"ga_sessions": 150,
"ga_bounces": 50,
"ga_new_users": 50,
"position": 0.3,
"length": 4,
"days": 10,
"advertiser": {
"name": "Advertiser",
"currency": "EUR"
}
}
]
Get analysis results for a publisher with parent.
GET /publishers/{publisher}/analysis/{from}/{to}/parent/{parent}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
publisher | path | \Publisher | |
from | path | ||
to | path | ||
parent | path | \TrafficSource |
Response
Add a user to an publisher
POST /publishers/{publisher}/users
Parameters
Name | Located in | Description | Type |
---|---|---|---|
publisher | path | \Publisher | |
request | Email for the user to invite | string |
Response
"The invite has been sent"
List all users associated with publisher
GET /publishers/{publisher}/users/list
Parameters
Name | Located in | Description | Type |
---|---|---|---|
publisher | path | \Publisher |
Response
[
{
"name": "Name",
"email": "example@email.co"
}
]
Remove user from an account
DELETE /publishers/{publisher}/users/{email}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
publisher | path | \Publisher | |
path | string |
Response
"The user has been removed"
Get trafficSource for publishers
GET /publishers/{publisher}/trafficsources/{trafficsource}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
publisher | path | ||
trafficsource | path |
Response
null
Tours
Check whether or not a tour with this name should be started
GET /tours/{name}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
tour | request | Tour to check this for | string |
name | path |
Response
true
Mark a tour as finished
POST /tours/{name}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
tour | request | Tour to mark as finished | string |
name | path |
Response
Mark a tour as skipped
DELETE /tours/{name}
Parameters
Name | Located in | Description | Type |
---|---|---|---|
tour | request | Tour to mark as skipped | string |
name | path |