Introduction

Welcome to the Odyssey Partnerships Data API documentation. This document gives you all the information you need to get started with getting analyzed data and partner performance out of Odyssey Partnerships.

The base URI of the Odyssey Partnerships Data API is https://partnerships.odysseyattribution.co/data-api/.

Authenticating your requests

Authentication with the Odyssey Partnerships Data API is done using bearer tokens in the Authorization API header.

Advertisers

Get the date range for available data for an account

GET /advertisers/{advertiser}/datarange

Parameters

Name	Located in	Description	Type
advertiser	path	The advertiser to get the daterange for	\AdvertiserAccount

{
    "min": "2020-01-01",
    "max": "2020-12-01",
    "collection_failure": false
}

Get publisher data for a given period and account

GET /advertisers/{advertiser}/publisherdata

Parameters

Name	Located in	Description	Type
advertiser	path	The advertiser to get the daterange for	\AdvertiserAccount
from	request	the starting date	\Carbon
to	request	the ending date 2020-12-01	\Carbon

[
    {
        "id": 1,
        "publisher": "Sparwelt",
        "type": "Other",
        "incrementality": 0.123123123,
        "volume": 1000,
        "total_sessions": 500,
        "conversion_rate": 123.123123123,
        "returns": 0,
        "returned_revenue": 0,
        "participated_revenue": 123123.12312312,
        "attributed_revenue": 12312.312312312,
        "current_commission": [
            {
                "method": "CPS",
                "value": 10,
                "value-type": "percentage"
            }
        ],
        "suggested_commission": 5.1234567891234,
        "current_ad_spend": 123456,
        "net_commission": 123456,
        "suggested_ad_spend": 123456.12345678,
        "over_under_spend": -12345.123567891,
        "aov": 123.1234567891
    }
]

Get contracts with publishers

GET /advertisers/{advertiser}/contracts

Parameters

Name	Located in	Description	Type
account	request		\AdvertiserAccount
advertiser	path

[
    {
        "id": 1,
        "name": "Sports Cashback 2019",
        "website": "https:\/\/odysseyattribution.co\/",
        "country": "NL",
        "type": "Other",
        "contract": {
            "id": 1,
            "odyssey_traffic_source_id": 3265820,
            "created_at": "2021-10-22T12:17:32.000000Z",
            "artemis": false,
            "monthly_cap": null,
            "all_terms": [
                {
                    "start_date": "1990-01-01T00:00:00.000000Z",
                    "end_date": null,
                    "rewards": [
                        {
                            "method": "CPS",
                            "value": 10,
                            "value-type": "percentage",
                            "currency": "EUR"
                        }
                    ]
                }
            ]
        }
    }
]

Publishers

Search for an advertiser account with Shopsuite enabled by the provided url.

POST /publishers/{publisher}/advertisers/detect

Parameters

Name	Located in	Description	Type
url	request		string
publisher	path

{
    "id": 1,
    "name": "Demo Account",
    "website": "https:\/\/www.example.com"
}

Get publisher data for a given period and account

GET /publishers/{publisher}/advertisers/{advertiser}

Parameters

Name	Located in	Description	Type
publisher	path	The publisher to get the data for	\PublisherAccount
advertiser	path	The advertiser to get the data for	\AdvertiserAccount
from	request	the starting date dd-mm-yyyy	\Carbon
to	request	the ending date dd-mm-yyyy	\Carbon

[
    {
        "advertiser": "Advertiser 1",
        "incrementality": 0,
        "total_sessions": 0,
        "commission": [
            {
                "method": "CPS",
                "value": 15,
                "value-type": "percentage",
                "currency": "EUR"
            }
        ],
        "net_earned_commission": 0,
        "ecpc": 0,
        "revenue": 0,
        "returned_revenue": 0,
        "conversions": 0,
        "returned_transactions": 0,
        "accepted_commission": 0,
        "pending_commission": 0,
        "rejected_commission": 0,
        "gross_commission": 0
    }
]

Get publisher data for each utm_content traffic source

GET /publishers/{publisher}/advertisers/{advertiser}/per-content

Parameters

Name	Located in	Description	Type
publisher	path	The publisher to get the data for	\PublisherAccount
advertiser	path	The advertiser to get the data for	\AdvertiserAccount
from	request	the starting date dd-mm-yyyy	\Carbon
to	request	the ending date dd-mm-yyyy	\Carbon

{
    "UTM content label": {
        "advertiser": "Advertiser 1",
        "incrementality": 0,
        "total_sessions": 0,
        "commission": [
            {
                "method": "CPS",
                "value": 0,
                "value-type": "percentage",
                "currency": "EUR"
            }
        ],
        "net_earned_commission": 0,
        "ecpc": 0,
        "revenue": 0,
        "returned_revenue": 0,
        "conversions": 0,
        "returned_transactions": 0,
        "accepted_commission": 0,
        "pending_commission": 0,
        "rejected_commission": 0,
        "gross_commission": 0
    }
}

Generate tracking link for a given advertiser.

POST /publishers/{publisher}/advertisers/{advertiser}/link

Parameters

Name	Located in	Type
publisher	path	\PublisherAccount
advertiser	path	\AdvertiserAccount
link	request	string
utm_content	request	string

{
    "link": "https:\/\/www.example.com\/?utm_source=Odyssey_Partnerships&utm_medium=affiliate&utm_campaign=8&utm_content=example-content"
}

Get product metadata for a specific URL

POST /publishers/{publisher}/advertisers/{advertiser}/product

Parameters

Name	Located in	Description	Type
link	request	Link to get metadata from	string
publisher	path		\PublisherAccount
advertiser	path		\AdvertiserAccount

null

Get a list of affiliate clicks for period

GET /publishers/{publisher}/clicks

Parameters

Name	Located in	Description	Type
publisher	path		\PublisherAccount
advertiser	request		\AdvertiserAccount
from	request	the starting date dd-mm-yyyy	\Carbon
to	request	the ending date dd-mm-yyyy	\Carbon

null

Get contracts with advertisers

GET /publishers/{publisher}/contracts

Parameters

Name	Located in	Description	Type
account	request		\PublisherAccount
publisher	path

null

Admin

Get publisher data for a given period and account

GET /admin/advertisers/{advertiser}/publisherdata

Parameters

Name	Located in	Description	Type
advertiser	path	The advertiser to get the daterange for	\AdvertiserAccount
from	request	the starting date	\Carbon
to	request	the ending date 2020-12-01	\Carbon

[
    {
        "id": 1,
        "publisher": "Sparwelt",
        "type": "Other",
        "incrementality": 0.123123123,
        "volume": 1000,
        "total_sessions": 500,
        "conversion_rate": 123.123123123,
        "returns": 0,
        "returned_revenue": 0,
        "participated_revenue": 123123.12312312,
        "attributed_revenue": 12312.312312312,
        "current_commission": [
            {
                "method": "CPS",
                "value": 10,
                "value-type": "percentage"
            }
        ],
        "suggested_commission": 5.1234567891234,
        "current_ad_spend": 123456,
        "net_commission": 123456,
        "suggested_ad_spend": 123456.12345678,
        "over_under_spend": -12345.123567891,
        "aov": 123.1234567891
    }
]

Tracking links

In this section you can find information and examples about how tracking links work, and how to build one.

How it works

A tracking link wraps contract information and destination. The destination link should contain UTM tags if you want to include them. When a user clicks the tracking link, we log the click and redirect the user to the destination link. Everything in the original desitnation will be preserved when building a tracking link. Contract information must present for the logging of clicks.

Building tracking links

const baseUri = {
    base_uri: 'https://artemis.odysseyattribution.co',
    base_uri_shopsuite: 'https://artemis.shopsuite.com'
}

function toPubId(id) {
    return (id * 1000 + 57).toString(16).toUpperCase();
}

function wrapUrl(base_uri, publisher_id, advertiser_id, contract_id, destination) {
    let publisher_pub = toPubId(publisher_id),
        advertiser_pub = toPubId(advertiser_id),
        contract_pub = toPubId(contract_id);
    let encoded = btoa(`/${publisher_pub}/${advertiser_pub}/${contract_pub}/${destination}`)
        .replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '$');
    return `${base_uri}/l/${encoded}`;
}

let publisher_id = [publisher ID integer],
    advertiser_id = [advertiser ID integer],
    contract_id = [contract ID integer],
    destination = [destination link];

let base_uri = baseUri.base_uri;
// Or if you're using Shopsuite, change base_uri to base_uri_shopsuite:
// let base_uri = baseUri.base_uri_shopsuite;

console.log(wrapUrl(base_uri, publisher_id, advertiser_id, contract_id, destination));

<?php
const BASEURI = [
    'base_uri' => 'https://artemis.odysseyattribution.co',
    'base_uri_shopsuite' => 'https://artemis.shopsuite.com'
];

function toPubId($id) {
    return strtoupper(dechex(($id * 1000) + 57));
}

function wrap($base_uri, $publisher_id, $advertiser_id, $contract_id, $destination) {
    $publisher_pub = toPubId($publisher_id);
    $advertiser_pub = toPubId($advertiser_id);
    $contract_pub = toPubId($contract_id);
    $encoded = base64_encode("/$publisher_pub/$advertiser_pub/$contract_pub/$destination");
    $encoded = str_replace(['+', '/', '='], ['-', '_', '$'], $encoded);
    return "$base_uri/l/$encoded";
}

$publisher_id = [publisher ID integer];
$advertiser_id = [advertiser ID integer];
$contract_id = [contract ID integer];
$destination = [destination link];
$base_uri = BASEURI['base_uri'];
// Or for Shopsuite:
// $base_uri = BASEURI['base_uri_shopsuite'];

var_dump(wrap($base_uri, $publisher_id, $advertiser_id, $contract_id, $destination));
?>

require 'base64'

def toPubId(id)
    return (id * 1000 + 57).to_s(16).upcase
end

def wrap(base_uri, publisher_id, advertiser_id, contract_id, destination) 
    p_pub = toPubId(publisher_id)
    a_pub = toPubId(advertiser_id)
    c_pub = toPubId(contract_id)
    encoded = Base64.encode64('/%{p_pub}/%{a_pub}/%{c_pub}/%{d}' % {p_pub: p_pub, a_pub: a_pub, c_pub: c_pub, d: destination})
        .gsub('+', '-').gsub('/', '_').gsub('=', '$')
    return '%{base_uri}/l/%{encoded}' % {base_uri: base_uri, encoded: encoded}
end

publisher_id = [publisher ID integer]
advertiser_id = [advertiser ID integer]
contract_id = [contract ID integer]
destination = [destination link]

base_uri = 'https://artemis.odysseyattribution.co'
# Or for Shopsuite
# base_uri = 'https://artemis.shopsuite.com'

puts wrap(base_uri, publisher_id, advertiser_id, contract_id, destination)

import java.util.Base64;

public class BuildTrackingLink {

    public static void main(String[] args) {
        Integer publisher_id = [publisher ID integer];
        Integer advertiser_id = [advertiser ID integer];
        Integer contract_id = [contract ID integer];
        String destination = [destination link];
        String base_uri = "https://artemis.odysseyattribution.co";
        // Or for Shopsuite:
        // String base_uri = "https://artemis.shopsuite.com";

        System.out.println(wrap(base_uri, publisher_id, advertiser_id, contract_id, destination));
    }

    public static String toPubId(int id) {
        return Integer.toHexString(id * 1000 + 57).toUpperCase();
    }

    public static String wrap(String base_uri, int publisher_id, int advertiser_id, int contract_id, String destination) {
        String p_pub = toPubId(publisher_id);
        String a_pub = toPubId(advertiser_id);
        String c_pub = toPubId(contract_id);
        String encoded = Base64.getEncoder().encodeToString(("/" + p_pub + "/" + a_pub + "/" + c_pub + "/" + destination).getBytes());
        String payload = encoded.replace('+', '-').replace('/', '_').replace('=', '$');
        return base_uri + "/l/" + payload;
    }
}

To build a link, prepare the destination link:

https://example.com

You should add UTM tags to the destination link for the platform.

https://example.com?utm_source=Odyssey_Partnerships&utm_medium=affiliate&utm_campaign=[your campaign]

Prepare three IDs:

the ID of contract
the ID of publisher in the contract
the ID of advertiser in the contract

Next, obfuscate IDs. You can find the algorithm for this in examples.

After that, concatenate the IDs and the destination link in the following format:

/[obfuscated_publisher_id]/[obfuscated_advertiser_id]/[obfuscated_contract_id]/[destination_link]

Encode the concatenated string with base64. The encoded string will be a part of the final tracking link, so for correct logging please replace all URL-unsafe characters with specific replacements according to the table below.

Character	Replacement
`+`	`-`
`/`	`_`
`=`	`$`

Finally, append the encoded string to one of the tracking link base URLs in the following format:

[tracking_link_base]/l/[encoded_string]

Brand	Tracking link base
Odyssey Partnerships	`https://artemis.odysseyattribution.co`
Shopsuite	`https://artemis.shopsuite.com`

Example tracking link:

https://artemis.odysseyattribution.co/l/[encoded_string]