Claims API

Automate the management of transaction inquiries from publishers.

We recently changed the urls for the Claims API. This page contains the documentation of the legacy urls for 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 find the updated documentation of the Claims API here.

Please note that there is a slight change in the behavior of the Claim Update Service as mentioned in the Claim version section.

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

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.

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:

Name Description Type
token Your unique token, identifying you as an advertiser. 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 Integer No

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}

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
siteName Publisher site name String 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
expectedCommission Expected commission for this claim String No
adjustedExpectedCommission Expected commission as adjusted by advertiser String No
proofOfClaims URL to proof of claim/transaction String No
advertiserInformation Extra information to advertiser String No
daysToAutoApprove Number of days till the claim auto-approves Integer No
Note: Only information set as "required" above is present on all claims. Other types of information is not mandatory for publishers to provide.

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:

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
statusIdClaim Status ID Integer Yes
statusMessageClaim Additional status message String Depends on statusId (see Status ID List)
orderValue Order value Float No
expectedCommission Expected commission Float No

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"
	}
]
}
Note: Status messages are pre-defined and can be found in Status Message.

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>
Note: Status messages are pre-defined and can be found in Status Message.

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

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:

Name Description Type
token Your unique token, identifying you as an advertiser. 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
Note: You 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 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

Note: The values are case sensitive.

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