Войти в кабинет
RU
EN
login
RU
EN
API overview
API is implemented as a set of "resources" (domain models) and "methods" (operations with resources) which is somewhat similar to the REST API design. The core difference is that in MyTarget API, many methods can operate with complex resources that may include other resources with various numbers of nesting levels and/or lists of other resources. Many methods also support operations with several resources of the same type.

Every resource has one or more types of URL addresses. Operations with resources are performed by various HTTP methods. For example, the following request retrieves a list of campaigns: 
GET /api/v2/campaigns.json
The following request creates a campaign:
POST /api/v2/campaigns.json
The following request retrieves parameters of a certain campaign:
GET /api/v2/campaigns/1.json
Most methods use the JSON format for both input and output data. Consequently, the HTTP requests and responses are of the application/json type. For the GET and DELETE requests that do not have a request body, specifying the type is optional.

Validation of the input data and generation of the output for each resource is performed according to one or more "data structures". Every method description specifies the structures used by the method.

Authentication

Authentication and authorization in the API is done with the OAuth2 protocol. Its implementation is described in this article. To access the API via OAuth2, you need to submit a corresponding request from the support contact form in the interface. To get access to the API, follow these instructions.

Basic data types

API uses the following basic data types:
Data type
JSON data representation
String
"value"
Integer
"123"
Decimal
"1.23"
Boolean
"true" or "false"
None
null
Date
"2013-08-18", the default format is YYYY-MM-DD, unless specified otherwise.
Datetime
"2013-08-28 16:49:34", the default format is YYYY-MM-DD HH:MM:SS, unless specified otherwise. Timezone is Europe/Moscow, unless specified otherwise.
List
["value1", "value2"], list elements are homogeneous.
Object
{"id": 1, "name": "Name"}, object properties may be heterogeneous.
Complex data types based on the above types are described in the methods and resources documentation.

Basic errors

Error messages have standard HTTP response statuses. The response body contains detailed information about error in the JSON format; the response type is application/json.

  • 400 — the request contains invalid data
  • 401 — the signature used for authentication is invalid or missing (the Authorization heading must contain a valid access_token value)
  • 403 — the operation cannot be performed under the account whose secret key (access_token) was used to sign the request
  • 404 — the requested resource cannot be found
  • 405 — the resource does not support the current HTTP method
  • 413 — the request body is too long
  • 429 — the requests-per-time unit limit was exceeded
  • 500 — unexpected error

Response compression

If your client supports response compression, you can use the following heading in the request:
Accept-Encoding: gzip, deflate

Limits for the number of requests per time unit

The service has limitations for the number of requests user can send during a time interval (calendar day, hour, second).

User limits are calculated for each user individually. For example, if the system has a limit of 10 requests per minute for a particular method, it means that each user can make up to 10 requests in a minute.

Limits may be adjusted for each user or user group. That is why it is recommended to analyse only real-time data.

Current limits are returned in the HTTP headings of every response. Note that values may differ from method to method.
X-RateLimit-RPS-Limit: value     # number of requests per second 
X-RateLimit-Hourly-Limit: value  # number of requests per hour 
X-RateLimit-Daily-Limit: value   # number of requests per day
The responses also contain headings with the number of requests user can send before exceeding the threshold:
X-RateLimit-RPS-Remaining: value    # number of requests user can make within the current second 
X-RateLimit-Hourly-Remaining: value # number of requests user can make within the current hour 
X-RateLimit-Daily-Remaining: value  # number of requests user can make within the current day
You can also get information about the limits for a specific user by request:
GET /api/v2/throttling.json
The response contains the current value of the limits, as well as the number of remaining requests for resources for which the limits are set.
{
    "REMARKETINGUSERSLIST": {
        "v2": {
            "READ": {
                "remaining": {
                    "60": 1
                },
                "limits": {
                    "60": 1
                }
            },
            "CREATE": {
                "remaining": {
                    "60": 0
                },
                "limits": {
                    "60": 0
                }
            }
        },
        "v3": {
            "READ": {
                "remaining": {
                    "3600": 200
                },
                "limits": {
                    "3600": 200
                }
            },
            "CREATE": {
                "remaining": {
                    "3600": 10
                },
                "limits": {
                    "3600": 10
                }
            }
        },
        "all": {
            "READ": {
                "remaining": {
                    "3600": 200
                },
                "limits": {
                    "3600": 200
                }
            },
            "CREATE": {
                "remaining": {
                    "60": 1
                },
                "limits": {
                    "60": 1
                }
            }
        }
    }
For a resource, both general limits and limits for using the method of a specific version can be set. The version corresponds to the namespace.

So, in the above example, using the /api/v2/remarketing/users_lists/<id>.json method, you can make no more than one GET request per minute, and you cannot create a new list, using /api/v2/remarketing/users_lists/<id>.json you can read the information on 200 lists per hour, and create 10 lists per hour. And at the same time, using requests of any versions, in total, it is impossible to read the information on more than 200 lists per hour, and you can create no more than 1 list per hour.

After a new version of the method release, we will gradually reduce the usage limits for previous versions of the same resource.

Testing

There is a stand-alone service instance that is used as a testing environment for testing and debugging the API integration: https://target-sandbox.my.com. To use it, you will need another ID and secret key (not the ones used for accessing the production environment). Follow these instructions to get access to the environment.
Was this article helpful?
Yes
No