Claims API

Overview

The Claims API lets you automate the way you handle requests from publishers. Integration will allow you to:

• Query claims to find new, pending, changed or resolved claims.
• Approve or deny claims and update details (e.g. order value).
• Use support services to show valid reason IDs, claim statuses, etc.

Tradedoubler will automatically validate claims in real-time when created by publishers. We'll check to make sure:

• The publisher has a valid connection with your program.
• The order reference hasn't been tracked before (to the claiming publisher or another in the network).
• The order reference 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 ensures you will only receive valid claims and can manage them in an efficient manner.

Do not have an affiliate program with Tradedoubler? Contact us

This documentation is intended for advertisers. If you are a publisher, go to the publisher 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" > "Management" > "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.

List Claims Service

The list claims service allows you to return all claims or filter your results. Use it to manage your pending claims or to review handled claims.

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 Update Service

The claim update service allows you to update claims that have status ID 2 (pending claims).

The syntax for the service is:

HTTPS POST https://api.tradedoubler.com/1.0/uts/claimUpdates[.xml|.json]?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":"8274",
	"statusIdClaim":"202"
	}
]
}

Some status IDs require a status message to be included (see Status ID List). Here is an example of how to include a status message:

{
"claimUpdates":[
	{
	"claimId":"8275",
	"statusIdClaim":"201",
	"statusMessageClaim":"Retargeting"
	}
]
}

If the user has entered the wrong order value or expected commission (e.g. because some items were returned) you can update these values when accepting the claim like this:

{
"claimUpdates":[
	{
	"claimId":"8276",
	"statusIdClaim":"3",
	"orderValue":"5.00",
	"expectedCommission":"1.00"
	}
]
}

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>8274</claimId>
		<statusIdClaim>202</statusIdClaim>
	</ns2:claimUpdate>
</ns2:claimUpdates>

Some status IDs require a status message to be included (see Status ID List). Here is an example of how to include a status message:

<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>8275</claimId>
		<statusIdClaim>201</statusIdClaim>
		<statusMessageClaim>Retargeting</statusMessageClaim>
	</ns2:claimUpdate>
</ns2:claimUpdates>

If the user has entered the wrong order value or expected commission (e.g. because some items were returned) you can update these values when accepting the claim like this:

<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>8276</claimId>
		<statusIdClaim>3</statusIdClaim>
		<orderValue>5.00</orderValue>
		<expectedCommission>1.00</expectedCommission>
	</ns2:claimUpdate>
</ns2:claimUpdates>

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>

Claim version

Claim version is introduced since the launch of the new urls for the Claims API. This means that the system only allows to update the latest version of the claim in the system. The legacy Claim Update Service specified in this document does not include the "versionNo" attribute in the request. Therefore, it assumes that the update request is for the initial version of the claim ("versionNo" = "0"). This has the implication that, if the claim has been updated by the publisher, it is NOT possible to use the legacy Claim Update Service to make another update. In such scenario, you have to use the new Claim Update Service with the right "versionNo" if you want to update the claim.

Claim Status Service

The claim status service allows you to request a list of all possible status IDs to use when updating claims.

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 require a status message to be included. If this is not included the claim update will fail.

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: