Conversions API

Overview

Tradedoubler's Conversions API lets you create automated notifications for all of your conversions (leads and sales), which you will receive in real-time. You can:

• Receive data for all lead and sale events automatically rather than running reports.
• Receive notifications when transactions change status (e.g. from pending to approved).
• Access dozens of transaction attributes available in Tradedoubler's database.
• Format the messages including what attributes to include and how to name them.
• Configure currency conversions and map Tradedoubler attributes to your own custom parameters.
• Configure as many subscriptions, filters and data receivers as you need.

The Conversions API enables you to work more efficiently by receiving transaction notifications in real-time rather than having to run static reports from an interface.

Do not have a publisher account? Register with Tradedoubler and get started today!

Authentication

In order to access the Conversions API you need an account with Tradedoubler. Once you have an account, you can pick up your unique token by logging on and going to "Settings" > "Tokens". The token for the Conversions API is under the system "CONVERSIONS".

Tokens are 40 character hexadecimal SHA-1 strings.

CORS

The domain api.tradedoubler.com is CORS enabled, meaning that you can use client side XMLHttpRequest without getting cross-domain security issues, even when posting or deleting!

Please note however that CORS is not yet fully implemented in all browsers, so you may want to go for JSONP for client side requests.

Request headers

When posting your request you need to tell the service what type of content you are posting. The service can read JSON so use application/json.

We only accept UTF-8 as the character set so please make sure that you use that and specify it in the Content-Type header.

Create service

The create service allows you to add new subscriptions.

The syntax for the service is:

HTTPS POST https://api.tradedoubler.com/1.0/conversions/subscriptions[.xml|.json|empty]?token={token}

There is one required key in the request:

Features

The table below explains the features of the create service.

Post data

This tables shows all the attributes you can use when creating a subscription.

JSON post data example

This is an example of how to create a subscription with every option included.

{
	"subscriptionName":"My first real time postback",
	"filter": {
		"programIds": [1234,5678],
		"siteIds": [1234,5678],
		"eventIds": [1234,5678],
		"eventTypeIds": [5],
		"messageTypeIds": [1]
	},
	"receivers": [
		{
			"httpMethod": "GET",
			"receiverUrl": "http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}&goalId=${goalId}",
			"disabled":false
		},
		{
			"httpMethod": "POST",
			"receiverUrl": "http://mysite1.com",
			"receiverBody": "eventId=${eventId}, programId=${programId}, goalId=${goalId}",
			"receiverFormat": "custom",
			"disabled":false
		}
	],
	"currencyConversion": {
		"to": "USD"
	},
	"customAttribute" : {
		"tdAttributes": ["programId", "eventId"],
		"userAttribute": "goalId",
		"rules": [
			{"inputs": ["123", "456"], "output": "10"},
			{"inputs": ["12345", "67890"], "output": "20"}
		]
	},
	"disabled":false
}

The example above structured the receiverUrl with name:value pairs. You can also choose to include only the values like so:

{
	"receivers": [
		{
			"httpMethod": "GET",
			"receiverUrl": "http://mysite1.com/${orderNumber}/${orderValue}"
		}
	]
}

Filters are optional and can be included or excluded as needed. If you wish to receive data for all programs and events you can exclude all filters. This is a GET subscription that will send data for all programs and events associated with the publisher to one receiver.

{
	"receivers": [
		{
			"httpMethod": "GET",
			"receiverUrl": "http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}"
		}
	]
}

You can also subscribe to event types (i.e. clicks, leads and sales) rather than specific event IDs. This will send data for all events of the defined type. This is an example of a GET subscription for all post-click sales events (event type ID 5) to be sent to a single receiver.

{
	"filter": {
		"eventTypeIds": [5]
	},
	"receivers": [
		{
			"httpMethod": "GET",
			"receiverUrl": "http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}"
		}
	]
}

Create response

If the subscription creation is successful you will receive a 'HTTP Created 201' response code and a copy of the subscription settings in the response body. It will also include the subscriptionId assigned to the new subscription. Here is an example of a response body:

JSON:

{
	"subscriptionId": "5485d003af4be0f76fbdddc8",
	"filter": {
		"eventTypeIds": [5]
	},
	"receivers": [
		{
			"httpMethod": "GET",
			"receiverUrl": "http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}",
			"disabled":false
		}
	]
}

XML:

<?xml version="1.0" encoding="UTF-8"?>
<subscription>
	<subscriptionId>5485d003af4be0f76fbdddc8</subscriptionId>
	<filter>
		<eventTypeIds>
		<id>5</id>
		</eventTypeIds>
	</filter>
	<receivers>
		<receiver>
			<httpMethod>GET</httpMethod>
			<receiverUrl>http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}</receiverUrl>
            		<disabled>false</disabled>
		</receiver>
	</receivers>
   	<disabled>false</disabled>
</subscription>

If something goes wrong we will attempt to explain the problem. See error management for details on error messages.

Update service

The update service allows you to edit existing subscriptions.

The syntax for the service is:

HTTPS PUT https://api.tradedoubler.com/1.0/conversions/subscriptions/{subscriptionId}?token={token}

There are two required keys in the request:

Post data

You can use the same attributes as in the create service (see Message attributes for more information).

The information you include in the update request will overwrite all existing settings in the subscription. For this reason you must include all elements for the subscription, not just the ones you want to change.

Take the following example as an existing subscription:

{
	"filter": {
		"programIds": [1234,5678],
		"eventIds": [1234,5678]
	},
	"receivers": [
		{
			"httpMethod": "GET",
			"receiverUrl": "http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}",
			"disabled":false
		}
	]
}

If you want to update the subscription by removing the programId 1234, you would use this request:

{
	"filter": {
		"programIds": [5678],
		"eventIds": [1234,5678]
	},
	"receivers": [
		{
			"httpMethod": "GET",
			"receiverUrl": "http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}",
			"disabled":false
		}
	]
}

Update response

If the update is successful you will receive a 'HTTP OK 200' response code and a copy of the new subscription settings in the response body as follows:

{
	"subscriptionId": "5485d003af4be0f76fbdddc8",
	"filter": {
		"programIds": [5678],
		"eventIds": [1234,5678]
	},
	"receivers": [
		{
			"httpMethod": "GET",
			"receiverUrl": "http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}",
			"disabled":false
		}
	]
}

XML:

<?xml version="1.0" encoding="UTF-8"?>
<subscription>
	<subscriptionId>5485d003af4be0f76fbdddc8</subscriptionId>
	<filter>
		<programIds>
			<id>5678</id>
		</programIds>
		<eventIds>
			<id>1234</id>
			<id>5678</id>
		</eventIds>
	</filter>
	<receivers>
		<receiver>
			<httpMethod>GET</httpMethod>
			<receiverUrl>http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}</receiverUrl>
			<disabled>false</disabled>
		</receiver>
	</receivers>
	<disabled>false</disabled>
</subscription>

Delete service

When you no longer need a subscription you can delete it using the delete service.

The syntax for this service is:

HTTPS DELETE https://api.tradedoubler.com/1.0/conversions/subscriptions/{subscriptionId}?token={token}

There are two required keys in the request:

If the update is successful you will receive a 'HTTP OK 200' response code. There will be no response body.

List service

You can search for subscriptions you already have set up using the list service.

The syntax for this service is:

HTTPS GET https://api.tradedoubler.com/1.0/conversions/subscriptions?token={token}

There is one required key in the request:

This request will return the details for all of your subscriptions.

You can receive details of specific subscriptions by adding the subscriptionId parameter to the request as follows:

HTTPS GET https://api.tradedoubler.com/1.0/conversions/subscriptions/{subscriptionId}?token={token}

List response

If the list request is successful you will receive a 'HTTP OK 200' response code and the search results in the response body. Full details will be returned for each subscription matching the search terms.

This is an example of a request for all subscriptions:

JSON:

[
	{
		"subscriptionId": "5485d003af4be0f76fbdddc8",
		"filter": {
			"programIds": [5678],
			"eventIds": [1234,5678]
		},
		"receivers": [
			{
				"httpMethod": "GET",
				"receiverUrl": "http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}",
				"disabled":false
			}
		]
	},
	{
		"subscriptionId": "54c8dd9caf4bf61a0abb9466",
		"filter": {
			"programIds": [1234],
			"eventIds": [5678]
		},
		"receivers": [
			{
				"httpMethod": "GET",
				"receiverUrl": "http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}",
				"disabled":false
			}
		]
	}
]

XML:

<?xml version="1.0" encoding="UTF-8"?>
<subscriptions>
	<subscription>
		<subscriptionId>5485d003af4be0f76fbdddc8</subscriptionId>
		<filter>
			<programIds>
				<id>5678</id>
			</programIds>
			<eventIds>
				<id>1234</id>
				<id>5678</id>
			</eventIds>
		</filter>
		<receivers>
			<receiver>
				<httpMethod>GET</httpMethod>
				<receiverUrl>http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}</receiverUrl>
				<disabled>false</disabled>
			</receiver>
		</receivers>
		<disabled>false</disabled>
	</subscription>
	<subscription>
		<subscriptionId>54c8dd9caf4bf61a0abb9466</subscriptionId>
		<filter>
			<programIds>
				<id>1234</id>
			</programIds>
			<eventIds>
				<id>5678</id>
			</eventIds>
		</filter>
		<receivers>
			<receiver>
				<httpMethod>GET</httpMethod>
				<receiverUrl>http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}</receiverUrl>
				<disabled>false</disabled>
			</receiver>
		</receivers>
		<disabled>false</disabled>
	</subscription>
</subscriptions>

This is an example of a request for a specific subscription

JSON:

{
	"subscriptionId": "5485d003af4be0f76fbdddc8",
	"filter": {
		"programIds": [5678],
		"eventIds": [1234,5678]
	},
	"receivers": [
		{
			"httpMethod": "GET",
			"receiverUrl": "http://mysite1.com?orderNum={orderNumber}&orderVal={orderValue}",
			"disabled": false
		}
	]
}

XML:

<?xml version="1.0" encoding="UTF-8"?>
<subscription>
	<subscriptionId>5485d003af4be0f76fbdddc8</subscriptionId>
	<filter>
		<programIds>
			<id>5678</id>
		</programIds>
		<eventIds>
			<id>1234</id>
			<id>5678</id>
		</eventIds>
	</filter>
	<receivers>
		<receiver>
			<httpMethod>GET</httpMethod>
			<receiverUrl>http://mysite1.com?orderNum=${orderNumber}&orderVal=${orderValue}</receiverUrl>
			<disabled>false</disabled>
		</receiver>
	</receivers>
	<disabled>false</disabled>
</subscription>

Error management

If an error occurs we will try to explain it using these error codes:

Other than the above, you can get generic HTTP errors. These are described here by W3C

The most common HTTP errors are:

Supporting Material

This section includes supporting material for you to use during implementation. Please get in touch with your Tradedoubler contact if you need anything else.

Message types

A transaction will move through different states during it's lifetime (e.g. tracked, pending and approved). Tradedoubler can send automated messages for each state and you can choose which ones you want to receive for each subscription. For example, you may wish to receive a message when a transaction is tracked and then when it becomes approved. Or you may wish to receive a message for every state so you can track every step of the journey. The table below provides an explanation of each message type.

Message attributes

Event type IDs

Status change IDs