Claims API

Overview

The Claims API lets you automate the way you manage requests from your users. Integration will allow you to:

• Create claims in real-time.
• Query claims to find updates (approved or denied).
• Find changes to claims during approval (e.g changes to order value).
• Find reasons for denials (e.g. Tradedoubler pre-validation or attribution to other channels).

Tradedoubler will automatically validate claims in real-time when you create them. We'll check to make sure:

• The site ID on the claim has a valid connection with the program.
• The order reference hasn't been tracked before (by you or another publisher in the network).
• The order refernece isn't tracked and still pending.
• All fields are completed with correct data (e.g. order value format and only claim dates in the past).

This helps you to correct any issues with claims before they are passed to the advertiser, therefore reducing the claim resolution time.

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

This documentation is intended for publishers. If you are an advertiser, go to the corresponding advertiser documentation.

Authentication

In order to access the Claims API, you need an account with Tradedoubler. Once you have an account, you can pick up your unique token by logging in and going to "Settings" > "Account" > "Manage tokens".

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.

Matrix syntax

Generally, all services in Tradedoubler Open API use the matrix syntax .

However, top level and service irrelevant information is sent as regular URL parameters. Usually, these are token and jsonp.

Post Claims Service

The post claims service allows you to create claims individually or in bulk.

The syntax for the service is:

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

There are two required keys in the request:

Request headers

When posting your request, you need to tell the service what type of content you are posting. The service can read JSON and XML. Use application/json if you are posting JSON and application/xml if you are sending XML.

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

Post data

This table shows all data you can send to Tradedoubler when creating a claim.

JSON post data example

This is an example of how to build the data in the JSON format:

{
"claims":[
	{
	"affiliateSiteId":"12345",
	"programId":"12345",
	"timeStampEvent":"2013-12-01",
	"orderNumber":"12345",
	"orderValue":"50.00",
	"eventId":"12345",
	"epi":"EPI 1",
	"epi2":"EPI 2",
	"proofOfClaims":"http://www.mydomain.com/proof1.jpg",
	"advertiserInformation":"email.address@mydomain.com",
	"expectedCommission":"3.75",
	"trackingUrl":"http://www.clk.tradedoubler.com/click?p(12345)a(12345)g(12345)",
	"productName":"Running shoes"
	}
]
}

XML post data example

This is an example of how to build the data in the XML format:

<ns2:claims version="1.0" xmlns:ns2="urn:com:tradedoubler:uts:openapi:parsing:xml:input" xmlns="urn:com:tradedoubler:uts:openapi:parsing:xml:common">
	<ns2:claim>
		<affiliateSiteId>12345</affiliateSiteId>
		<programId>12345</programId>
		<timeStampEvent>2013-12-01</timeStampEvent>
		<orderNumber>12345</orderNumber>
		<orderValue>50.00</orderValue>
		<eventId>12345</eventId>
		<epi>EPI 1</epi>
		<epi2>EPI 2</epi2>
		<proofOfClaims>http://www.mydomain.com/proof1.jpg</proofOfClaims>
		<advertiserInformation>email.address@mydomain.com</advertiserInformation>
		<expectedCommission>3.75</expectedCommission>
		<trackingUrl>http://www.clk.tradedoubler.com/click?p(12345)a(12345)g(12345)</trackingUrl>
		<productName>Running shoes</productName>
	</ns2:claim>
</ns2:claims>

Response

If a claim update is successful you will receive a response without errors.

JSON:

errors[]

XML:

<Response xmlns="http://api.tradedoubler.com/1.0/uts">
	<errors/>
</Response>

However, if the claim update failed we will try to explain why. This is an example of the error reported when a claim contains non-parsable JSON data.

JSON:

{
"errors":[
	{
	"code": "UTS_210",
	"message": "Non parsable json: line: 6, column: 4"
	}
]
}

XML:

<Response xmlns="http://api.tradedoubler.com/1.0/uts">
	<errors>
		<e>
			<code>UTS_210</code>
			<message>Non parsable json: line: 6, column: 4</message>
		</e>
	</errors>
</Response>

List Claims Service

The list claims service allows you to return all claims or filter your results.

The syntax for the service is:

HTTPS GET https://api.tradedoubler.com/1.0/uts/claims[.xml|.json|empty]?token={token}

There is one required key in the request:

Query keys

You can add a query to your request if you want to filter the results.

Example requests

Return all claims with pretty formatting:

HTTPS GET https://api.tradedoubler.com/1.0/uts/claims;pretty=true?token={token}

Return all approved claims:

HTTPS GET https://api.tradedoubler.com/1.0/uts/claims;statusId=3;pretty=true?token={token}

Return all claims with status ID 201 and 202:

HTTPS GET https://api.tradedoubler.com/1.0/uts/claims;statusId=201,202;pretty=true?token={token}

Return all claims updated since 1st December 2013:

HTTPS GET https://api.tradedoubler.com/1.0/uts/claims;minUpdateDate=2013-12-01;pretty=true?token={token}

Return all claims updated between 1st and 3rd December 2013:

HTTPS GET https://api.tradedoubler.com/1.0/uts/claims;minUpdateDate=2013-12-01;maxUpdateDate=2013-12-03;pretty=true?token={token}

Return claims with a last transaction date on or after December 1, 2013:

HTTPS GET https://api.tradedoubler.com/1.0/claims;minTransactionDate=2013-12-01;pretty=true?token={token}

Return claims with a last transaction date between December 1 and December 3, 2013:

HTTPS GET https://api.tradedoubler.com/1.0/claims;minTransactionDate=2013-12-01;maxTransactionDate=2013-12-03;pretty=true?token={token}

Response

The response will include some or all of this data. Please note that not all data is available for all claims.

Claim Status Service

The claim status service allows you to request a list of all possible status IDs.

The syntax for the service is:

HTTPS GET https://api.tradedoubler.com/1.0/uts/claimStatuses[.xml|.json|empty]?token={token}

There is one required key in the request:

Query keys

You can add a query to your request if you want to format the results.

Response

The response will include the following data:

Status ID list

All claims will have one of the following status IDs:

Status message

Claims being updated with status ID 201 will also include a status message. This will state the marketing channel that the transaction was attributed to. This is a list of available status messages for status ID 201:

• "Display"
• "Search"
• "Retargeting"
• "Email"
• "Offline"
• "Other"

Error Management

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