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).
• Update claims before they are handled by the advertiser.
• Delete claims before they are handled by the advertiser.

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.

Response format

The Claims API support response in both XML and JSON formats. In order to choose which response format you want to receive, specify the format in the Accept header when making a request.

We only accept UTF-8 as character set, so please make sure that specify it in the Accept header as well.

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/claims?token={token}

There is one required key 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 claims are created successfully, you will receive a response with HTTP status code 200 OK without response body.

However, in case of failure, 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/claims?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/claims;pretty=true?token={token}

Return all approved claims:

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

Return all claims with status ID 201 and 202:

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

Return all claims updated since 1st December 2013:

HTTPS GET https://api.tradedoubler.com/1.0/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/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 Update Service

The claim update service allows you to update claims that have status ID 2 (pending claims) or 1XX (failing system validation).

The syntax for the service is:

HTTPS POST https://api.tradedoubler.com/1.0/claimUpdates?token={token}

There is one required key 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 to update claims.

JSON post data example

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

{
"claimUpdates":[
	{
	"claimId": "105347",
	"affiliateSiteId":"407311",
	"programId":"202860",
	"timeStampEvent":"2015-06-22",
	"orderNumber":"201506221610",
	"orderValue":"50.00",
	"eventId":"17",
	"epi":"EPI 1",
	"epi2":"EPI 2",
	"proofOfClaims":"http://www.mydomain.com/proof1.jpg",
	"advertiserInformation":"email.address@mydomain.com",
	"expectedCommission":"3",
	"trackingUrl":"http://www.clk.tradedoubler.com/click?p(12345)a(12345)g(12345)",
	"productName":"Running shoes",
	"versionNo": "0"
	}
]
}

XML post data example

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

<ns2:claimUpdates version="1.0" xmlns:ns2="urn:com:tradedoubler:uts:openapi:parsing:xml:input" xmlns="urn:com:tradedoubler:uts:openapi:parsing:xml:common">
	<ns2:claimUpdate>
		<claimId>105347</claimId>
		<affiliateSiteId>407311</affiliateSiteId>
		<programId>202860</programId>
		<timeStampEvent>2015-06-22</timeStampEvent>
		<orderNumber>201506221610</orderNumber>
		<orderValue>40.00</orderValue>
		<eventId>17</eventId>
		<epi>EPI 1</epi>
		<epi2>EPI 2</epi2>
		<proofOfClaims>http://www.mydomain.com/proof1.jpg</proofOfClaims>
		<advertiserInformation>email.address@mydomain.com</advertiserInformation>
		<expectedCommission>2</expectedCommission>
		<trackingUrl>http://www.clk.tradedoubler.com/click?p(12345)a(12345)g(12345)</trackingUrl>
		<productName>Running shoes</productName>
		<versionNo>1</versionNo>
	</ns2:claimUpdate>
</ns2:claimUpdates>

Response

If a claim update is successful you will receive a response with HTTP status code 200 OK without response body.

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>

Claim version

The Claim Update Service requires that you specify the version of the claim to be updated when making a request. The service only allows an update of the latest version of the claim in the system. If the version of the claim in the update request does not match the latest version in the system, the claim update request will be rejected. This is to make sure that your update is based on the latest information.

To find out what is the lastet version of the claim in the system, use the the "versionNo" attribute returned in the response of the List Claims Service.

Claim Delete Service

The Claim Delete Service allows you to delete the previously created claim. The claim deletion is only allowed before the claim has been updated by the advertiser Claim Update Service.

The syntax for the service is:

HTTPS DELETE https://api.tradedoubler.com/1.0/claims/{claimId};versionNo={versionNo}?token={token}

There are three required keys in the request:

Response

If a claim delete request is successful you will receive a response with HTTP status code 200 OK without response body.

However, if the claim delete failed we will try to explain why. This is an example of the error reported when the version of the claim to be deleted is not specified.

JSON:

{
    "errors": [
        {
            "code": "UTS_200",
            "message": "Missing matrix variable 'versionNo' for method parameter type [java.lang.Integer]"
        }
    ]
}

XML:

<errors>
	<error>
		<code>UTS_200</code>
		<message>Missing matrix variable 'versionNo' for method parameter type [java.lang.Integer]</message>
	</error>
</errors>

Claim version

The Claim Delete Service requires that you specify the version of the claim to be deleted when making a request. The service only allows a deletion of the latest version of the claim in the system. If the version of the claim in the delete request does not match the latest version in the system, the claim delete request will be rejected. This is to make sure that the deletion is based on the latest information.

To find out what is the lastet version of the claim in the system, use the the "versionNo" attribute returned in the response of the List Claims Service.

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/claimStatuses?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: