Introduction:
TargetSolution's REST-ful API provides access to platform features that enable end-users to retrieve and manipulate their data for use in third party software implementations. This documentation is primarily for developers and third party application providers.
TargetSolution's core functionality primarily takes place within the web-based application. By exposing the data collected from these functions, our customers can easily integrate our system with their own existing systems. Some common use cases are:
- Synching lists of employees/users from an internal system to Targetsolutions
- Retrieving user credentials from TargetSolutions for use in an internal program
Before getting started with the API, developers must first understand how the API is organized and how it works. The following section provides a high level overview of the features of this API. It is recommended that the reader have knowledge of the HTTP protocol as well as a general understanding of web technologies.
Getting Started:
Data from the API is exposed in the form of URIs that represent resources and can be fetched with HTTP clients (like web browsers). Individual development environments may vary according to the customers chosen technology. However, the structure of making requests is the same no matter which technology you choose. While we have made an effort to be as clear as possible regarding the methodology, it is outside the scope of this guide to provide code examples for the variety of programming languages and development environments available.
There are many third party applications that enable fast testing of RESTful request structures. TargetSolutions recommends the following sources for fast development and testing of your API integration:
Authentication:
TargetSolutions has implemented a basic auth over HTTPS scheme that requires an API token to be passed in the header of all requests. This token is specific to each customer and must be requested from your account manager. You will not be able to make any requests to the API without this token. An example of what this token looks like is below.
TqV0rzm+/H6Nrza2j+ofRg==
This token is placed in the header portion of every request. The example below illustrates how this token is used in a request.
GET /sites HTTP/1.1
Host: https://devsandbox.targetsolutions.com/v1
AccessToken: TqV0rzm+/H6Nrza2j+ofRg==
Cache-Control: no-cache
Sites can have more than one token, and each token can have different access levels. You may need a token that has read-only access, or just access to a specific feature. If you require a token with specific access needs, please let your account representative know so that we can create your tokens accordingly.
Formats and Protocols:
Data returned in the response message is provided in JSON format. JSON or JavaScript Object Notation is an open standard format that uses human-readable text to transmit data objects consisting of attribute-value pairs. It is used primarily to transmit data between a server and web application, as an alternative to XML. Please refer to the examples provided with each API route in the routes section for details on each routes returned format.
Error Handling:
Errors are returned as JSON objects that contain an http status code, error code, name, and short description. Please refer to the error codes section provided in the TargetSolutions Dev Portal for detailed information.
Example GET request:
This type of request retrieves data for a given resource. The example below shows a typical request URI when retrieving site information.
GET https://devsandbox.targetsolutions.com/v1/sites
The returned results include, in this case, the site name, login URL and the site's unique ID, along with some helpful links to related resources. These links can be used in subsequent requests to work through the data hierarchy.
{
"sites":[
{
"links":[
{
"resourcelink":"https://devsandbox.targetsolutions.com/v1/sites/1414"
},
{
"profilecategories":"https://devsandbox.targetsolutions.com/v1/sites/1414/categories/profile"
},
{
"credentialcategories":"https://devsandbox.targetsolutions.com/v1/sites/1414/categories/credential"
},
{
"credentials":"https://devsandbox.targetsolutions.com/v1/sites/1414/credentials"
},
{
"users":"https://devsandbox.targetsolutions.com/v1/sites/1414/users"
},
{
"access":"https://devsandbox.targetsolutions.com/v1/sites/1414/access/"
}
],
"sitename":"BCB",
"loginpage":"https://app.targetsolutions.com/bcb",
"siteid":1414
}
],
"pagination":{
"next":"https://devsandbox.targetsolutions.com/v1/sites?startrow=2&limit=1"
}
}
Pagination of Results
In cases where the recordset returned a large number of results, there is a pagination link that will continue the current request with the next set of records. Note that the maximum number of records returned in any single request is 1000. You can manipulate the records returned by using two URI parameters: "startrow" and "limit." The startrow parameter indicates the record number you wish to start at. The limit parameter indicates how many total records from that starting point you wish to retrieve. In the example URI below, we are telling the API to start at the 5th user in our user list, and then to get a maximum of 10 records.
https://devsandbox.targetsolutions.com/v1/sites/1414/users?startrow=5&limit=10
Searching
Some routes within the API allow searching on certain fields that are returned with the dataset. These searchable fields are passed in the URI in a JSON structure format OR as URI parameters. For instance, if you wanted to retrieve a list of "inactive" users for a site, the following URI strings would search on that criteria.
JSON Format
https://devsandbox.targetsolutions.com/v1/sites/1414/users?q={"status":"inactive"}
URI Parameter Format
https://devsandbox.targetsolutions.com/v1/sites/1414/users?status=inactive
https://devsandbox.targetsolutions.com/v1/sites/1414/users?status=inactive
You can search using combinations of searchable fields by separating individual value pairs with commas. Both of the following formats are valid. Note that text entered for search is not case sensitive.
JSON Format
https://devsandbox.targetsolutions.com/v1/sites/1414/users?q={"status":"inactive","firstname":"john","lastname":"doe"}
URI Parameter Format
https://devsandbox.targetsolutions.com/v1/sites/1414/users?status=inactive&firstname=john&lastname=doe
Example PUT request:
PUT requests are used to edit/update a resource. The updated fields are passed as key-value pairs in a JSON structure in the body of the request. Refer to the specific route information on which fields are required and/or optional when using PUT for a resource. The example below shows a typical PUT request and response for a successful update of a user resource.
URI
PUT https://devsandbox.targetsolutions.com/v1/users/828903
Request Body Content
{
"username":"santaclaus@northpole.com",
"firstname":"Santa",
"lastname":"Claus",
"status":"active",
"employeeid":"sclaus1234"
}
Response
{
"httpcode":202,
"moreinfo":"http://developers.targetsolutions.com/v1/responsecodes/702",
"developermessage":"The request has been fulfilled and resulted in a resource being updated.",
"statuscode":702,
"status":"accepted"
}
Example POST request:
POST requests create a new data record for the resource specified. The data used to create the resource is passed as key-value pairs in a JSON structure in the body of the request. Refer to the specific route information on which fields are required and/or optional when using POST to create a new a resource. The example below shows a typical POST request and response for a successful creation of a user resource.
URI
POST https://devsandbox.targetsolutions.com/v1/sites/1414/users/
Request Body Content
{
"username":"santaclaus@northpole.com",
"password":"mypassword",
"firstname":"Newbie",
"lastname":"User"
}
It is important to note that some fields require validation to ensure uniqueness or other system contraints. When integrating with an existing system, ensure you account for these.
Response
{
"httpcode":201,
"moreinfo":"http://developers.targetsolutions.com/v1/responsecodes/701",
"developermessage":"The request has been fulfilled and resulted in a new resource being created. ",
"statuscode":701,
"status":"created"
}
Example DELETE request:
DELETE requests delete a resource. This is a permanent removal of the resource. DELETE requests typically do not contain any data in the body of the request. However, check the specific route documentation for potential special cases. This option is not available to all resources.
URI
DELETE http://devsandbox.targetsolutions.com/v1/users/123/emails/52378
Response
{
"httpcode":202,
"moreinfo":"http://developers.targetsolutions.com/v1/responsecodes/703",
"developermessage":"The request has been fulfilled and resulted in a new resource being deleted. ",
"statuscode":703,
"status":"accepted"
}