IMPORTANT: This page only relates to the Affiliate Version 2 API framework, put into effect Nov. 6, 2013, and only affects the APIs found below. You can find information relating to legacy v1 API framework here.
Introduction
This document contains information specific to the Version 2 of the LinkTrust Affiliate API's. It covers the basic information needed to use the APIs and is meant for a technical audience desiring to integrate with the LinkTrust system.
The General Information section should be read prior to reading any of the specific API information.
LinkTrust is in the process of releasing a new API framework: Version 2. These new APIs are built upon RESTful principals. They are designed to be accessible from any HTTP client including in many cases your web browser. Each API has a unique URL along with a list of required and optional parameters.
General Information
Fundamentals
The goal behind the LinkTrust Partner APIs is to provide an easy way for our partners to get data from and put data into the LinkTrust system. We want to make them accessible to the widest range of software clients and have thus built them as “RESTful” web services. As the term “RESTful” has become somewhat of a buzz word with different meanings to different people, this document will serve to explain how we’ve applied the “REST” architecture to the LinkTrust API.
All the APIs are available via any HTTP client. Each element or resource in the LinkTrust system exposed by the APIs will be available via a specific URL. This means resources such as reports, campaigns, creatives etc. will all have their own URL. If you want to get the current configuration of a resource or run a report you make an HTTP get request to that URL. To modify a resource you make an HTTP put request to that URL with the body of the request containing the new configuration of the resource. HTTP post requests are used to append data to resources or to create new resources.
The URL to access Affiliate Center APIs is: affiliateapi.linktrust.com
Authentication
All API access is performed over HTTPS (SSL) connections. To make authentication easy, basic http authentication is used. Any affiliate center user with the right to access APIs can be used. Simply authenticate with the Affiliate ID (NOT affiliate user name) and password. Additionally if you are accessing an API from within your web browser for testing purposes your browser should present a standard login box for you to authenticate.
Content Negotiation
The LinkTrust APIs support content negotiation. You may request the responses as XML or JSON. The system will look at the Accept header for any GET requests. In that header you need to pass the content type you wish returned. For example an Accept header value of text/xml or application/xml will return XML. An Accept header of application/json will return json. For Post/Put requests the content type being posted in determines the format the data will be returned in.
Error Handling and Reporting
In keeping with a REST based architecture the LinkTrust API uses HTTP status codes to communicate when error conditions occur. When an error occurs the details of the error are also exposed via the returned document. When a resource is requested in an XML format the errors will be returned in an XML format, when requested in an alternate format the errors will match that format. Below is a listing of each of the HTTP status codes used by the LinkTrust API and what it is used for by LinkTrust
- 200 – This is the standard HTTP success status code. It is used to communicate that the request was successful.
- 400 – This is the HTTP error code for a bad request. This is used to indicate something about the request as it was sent is invalid. This could be a missing or incorrect query string parameter for a get request. It could mean the data being sent in a put or post request is invalid in some way. The returned document will provide details on exactly what about the request is bad.
- 401 – This is the HTTP error code for an unauthorized request. This indicates the authentication token was not found, is invalid, or is expired. The returned document will provide details on why.
- 404 – This is the HTTP error code used to indicate that a URL cannot be found. This code is returned if the requested URL is invalid. This could indicate the API User ID on the front of the URL is invalid, or some other part of the URL cannot be found or is otherwise invalid. The returned document may return some further clarification.
- 405 – This is the HTTP error code used to indicate the specified HTTP method is not allowed for the given URL. You will get this code if you try and POST or PUT to a resource that doesn’t allow POST or PUT. Check the documentation for the resource you are accessing to ensure you know which methods it allows.
- 50X – Errors in the 500 range indicate a problem with our servers. If you receive an error in the 500 range contact support for further assistance.
Errors will always be returned in a plain text format.
What are the main differences between the old and new APIs?
You can request a demo to see LinkTrust up close and experience how it can help you, or start your free 14-day trial now.
Need help with this feature or have questions? You can contact our support team at support@linktrust.com