Claims API

Automate the management of transaction inquiries from your users.

We recently changed the urls for the Claims API. This page contains the updated documentation of the Claims API.

The legacy urls for the Claims API will be supported for some time, but planned to be removed in the near future. You can still find the documentation of the legacy urls here.

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".

Examples in this document use {token} as placeholder. You should replace this with your token when building a request.

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.

XML: Accept: application/xml; charset=utf-8

JSON: Accept: application/json; charset=utf-8

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:

Name Description Type
token Your unique token, identifying you as an advertiser. String

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.

JSON: Content-Type: application/json; charset=utf-8

XML: Content-Type: application/xml; charset=utf-8

Post data

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

Name Description Type Required
affiliateSiteId Publisher site ID Integer Yes
programId Program ID Integer Yes
timeStampEvent Date of transaction Date (YYYY-MM-DD) Yes
eventId Event ID Integer Yes (See note below. Point 1)
orderNumber Order number/reference String Yes (See note below. Point 2)
orderValue Order value Float Yes
epi EPI value String No
epi2 EPI 2 value String No
trackingUrl Tracking URL/click tag used for the transaction String No
productName Product name or description String No
proofOfClaims URL to proof of claim/transaction String No
expectedCommission Expected publisher commission for claim Float Depends on the event ID used (See note below. Point 3)
advertiserInformation Extra information for the advertiser String No
Note:

1. Most markets use a standard event ID for transaction inquiries. In these cases the event ID to use will always be 17. When using event ID 17 you MUST enter the expected commission.

2. The maximum length of an Order number can be 240 characters.

3. Some markets require you to enter the event ID for the specific event that took place (e.g. the ID for 'Hotel + Flight' for a travel client). If this is the case your local Publisher Manager/Publisher Support Team will inform you. When using the actual event ID you MUST NOT enter the expected commission.

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>
Read more about error management and see which errors can occur when using the API.

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:

Name Description Type
token Your unique token, identifying you as a publisher. String

Query keys

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

Name Description Type Multiple
pretty Formatted response (true|false) String No
statusId Status ID for claims (see Status ID List for status IDs). Can be comma separated to include multiple status IDs in one search Integer Yes
minUpdateDate Earliest date of update Date (YYYY-MM-DD) No
maxUpdateDate Latest date of update Date (YYYY-MM-DD) No
programId Program Id String No
claimId Claim Id Integer Yes
tdconnect Flag to identify the API is consuming by TDConnect. Optional parameter tdconnect with the default value is false. With tdconnect=true the claim list pagination returns the currentPage beginning with 0 instead of 1 Boolean No
offset This parameter is used for pagination.These number of rows will be offset from the result set when returning the response. The tdconnect parameter should be true to work this as expected. Integer No
limit This parameter is used for pagination. This is the result count that returns from the response. The tdconnect parameter should be true to work this as expected. Integer No
sortBy This parameter is used to sort the response. It can sort by claim ID, program name, site name, or status change. The default sorting option is by claim ID. String No
sortOrder This parameter determines the order in which things are sorted. You can choose between ascending (asc) and descending (desc) order. The default sorting order is descending (desc). String No

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}

Response

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

Name Description Type Required
claimId Claim identifier Integer Yes
timeStamp Claim created timeStamp Date (YYYY-MM-DD) Yes
statusId Status ID Integer Yes
statusName Status name String Yes
statusState State String Yes
statusMessage Additional status message String No
statusChanged Timestamp for last status change Date (YYYY-MM-DD) No
publisherId Publisher organisationID Integer Yes
affiliateSiteId Publisher site ID Integer Yes
programId Program ID Integer Yes
programName Program name String Yes
timeStampEvent Date of transaction Date (YYYY-MM-DD) Yes
eventId Event ID Integer Yes
orderNumber Order number/reference String Yes
orderValue Order value Float Yes
adjustedOrderValue Order value as adjusted by advertiser Float No
epi EPI value String No
epi2 EPI 2 value String No
trackingUrl Tracking URL/click tag String No
productName Product name or description String No
proofOfClaims URL to proof of claim/transaction String No
advertiserInformation Extra information to advertiser String No
expectedCommission Expected commission for this claim String No
adjustedExpectedCommission Expected commission as adjusted by advertiser String No
siteName Publisher site name String Yes
daysToAutoApprove Number of days till the claim auto-approves Integer No
versionNo Current version of the claim Integer Yes
eventName Event Name String No
Note: Only information set as "required" above is present on 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:

Name Description Type
token Your unique token, identifying you as an advertiser. String

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.

JSON: Content-Type: application/json; charset=utf-8

XML: Content-Type: application/xml; charset=utf-8

Post data

This table shows all data you can send to Tradedoubler to update claims.

Name Description Type Required
claimId Claim identifier Integer Yes
affiliateSiteId Publisher site ID Integer Yes
programId Program ID Integer Yes
timeStampEvent Date of transaction Date (YYYY-MM-DD) Yes
orderNumber Order number/reference String Yes
orderValue Order value Float Yes (See note below. Point 1)
eventId Event ID Integer Yes
epi EPI value String No
epi2 EPI 2 value String No
proofOfClaims URL to proof of claim/transaction String No
advertiserInformation Extra information to advertiser String No
expectedCommission Expected commission for this claim String No
trackingUrl Tracking URL/click tag String No
productName Product name or description String No
versionNo Version of the claim to be updated Integer Yes
Note:

1. The maximum length of an Order number can be 240 characters.

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>
Read more about error management and see which errors can occur when using the API.

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:

Name Description Type
claimId ID of the claim to be deleted. Integer
versionNo The version of the claim to be deleted. Integer
token Your unique token, identifying you as a publisher. String

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:

Name Description Type
token Your unique token, identifying you as a publisher. String

Query keys

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

Name Description Type Multiple
pretty Formatted response (true|false) String No

Response

The response will include the following data:

Name Description Type
statusId Status ID Integer
statusName Status name String
statusState State String
requireStatusMessage Is a status message required? Boolean

Status ID list

All claims will have one of the following status IDs:

ID Name State Status Message Required
1 Reported REPORTED No
2 Awaiting approval PENDING_ADVERTISER No
3 Approved APPROVED No
100 CANNOT_VALIDATE PENDING_TRADEDOUBLER No
101 Missing parameter REJECTED No
102 Program not found REJECTED No
103 Program not active REJECTED No
104 Tariff not found REJECTED No
105 Commission mismatch PENDING_TRADEDOUBLER No
106 Already tracked REJECTED No
107 Already tracked but pending REJECTED No
108 Already tracked but not accepted REJECTED No
109 Already tracked for other site REJECTED No
110 Already tracked for other site but pending REJECTED No
111 Already tracked for other publisher REJECTED Yes
112 Invalid site id REJECTED No
113 Site not approved REJECTED No
114 Advertiser does not accept claims REJECTED No
115 Transaction date in future REJECTED No
116 Invalid event type REJECTED No
201 Attributed to another marketing channel REJECTED Yes
202 Application/credit check denied REJECTED No
204 Fraudulent order/application REJECTED No
205 Insufficient information REJECTED No
206 Invalid order number REJECTED No
207 Order Cancelled or returned REJECTED No
208 Transaction cannot be traced REJECTED No
209 Transaction not fully completed online REJECTED No
210 Voucher/discount code used REJECTED No
211 Claim does not meet Advertiser guidelines REJECTED No
212 Already attributed to another publisher REJECTED No
213 Already tracked REJECTED No
Note: Advertisers only have the ability to update a claim with status ID 3 or 201-211. Only Tradedoubler may set a claim with another status ID.

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:

Error code Error Name Description
UTS_200 MISSING_PARAMETER Missing parameter.
UTS_210 NON_PARSEABLE_JSON_DATA Non-parsable JSON.
UTS_211 NON_PARSEABLE_UNKNOWN_DATA Unknown data has caused a parse exception.
UTS_212 NON_PARSEABLE_CSV_DATA Non-parsable CSV data.
UTS_213 NON_PARSEABLE_DATA_MULTIPLE_ERRORS Multiple errors found in input data.
UTS_230 UNKNOWN_ERROR Unknown error.
UTS_240 MISSING_VALUE_IN_CLAIM_JSON Missing value in JSON for claim.
UTS_260 PARAMETER_IS_NOT_NUMERIC Non-numeric parameter.
UTS_265 PARAMETER_IS_NOT_DATE Non-date parameter.
UTS_270 PARAMETER_IS_NOT_COMMA_SEPERATED Parameter is not comma separated.
UTS_291 XML_FORMAT_NOT_PARSEABLE The XML format could not be parsed.
UTS_300 TOKEN_REQUEST_NOT_VALID Token request was not valid.
UTS_301 TOKEN_REQUEST_FIND_FAILED Token request query failed.
UTS_302 TOKEN_REQUEST_DELETE_FAILED Token request for delete failed.
UTS_303 TOKEN_CREATE_FAILUREREQUEST_NOT_VALID Token request for create new token failed.
UTS_304 INVALID_TOKEN_TYPE Token type not valid.
UTS_306 CLAIM_STATUS_NOT_ALLOWED_FOR_ADVERTISER Advertiser cannot use the status.
UTS_370 ONLY_CONTENT_JSON_OR_XML_ALLOWED Only JSON or XML content is allowed.
UTS_371 ONLY_CONTENT_JSON_ALLOWED Only JSON content is allowed.
UTS_380 CLAIM_EXPORTER_FAILED_PARSING Export of claim/s failed.
UTS_394 CLAIM_UPDATE_INVALID_CLAIM_STATUS_ID Invalid claim status ID.
UTS_395 CLAIM_CREATE_ONLY_ALLOWED_FOR_PUBLISHER Upload or creation of claims only allowed for publishers.
UTS_396 The organization XXXXXX cannot access site XXXXXX The publisher organization's token is trying to upload claims for an affiliate Site ID they do not own.
UTS_397 CLAIM_CREATE_CONSTRAINT_FAILED The combination of timestampEvent, programId, eventId and orderNumber must be unique.
UTS_398 CLAIM_CREATE_PERSISTENCE_EXCEPTION Failed to persist the Claim.
UTS_399 CLAIM_UPDATE_CREATE_PERSISTENCE_EXCEPTION Failed to persist the ClaimUpdate.
UTS_400 BAD_URL Bad URL.
UTS_402 CLAIM_NOT_FOUND Cannot find the claim in the system.
UTS_403 AFFILIATE_PROGRAM_NOT_CONNECT No connection between the affiliate and the program.
UTS_404 ORGANIZATION_CLAIM_ACCESS_NOT_ALLOWED Organization is not allowed to access the claim.
UTS_405 CLAIM_STATUS_NOT_ALLOW_FOR_UPDATE Claim cannot be deleted or updated due to wrong claim status.
UTS_410 ENCODING_OF_SUPPLIED_DATA_NOT_SUPPORTED Encoding of data is not supported.
UTS_420 FAILED_PARSING_HTTP_REQUEST_CONTENT_TYPE Could not parse content type of request.
UTS_430 ILLEGAL_PARAMETER_VALUE Parameter has illegal value.