Campaign Management API

Follow

Base API URL is https://api.po.st/shortener/v1

 

Response format could be determined by "Accept" request header. Currently only two types of response format are supported:

1) json -- Accept: application/json
2) jsonp -- Accept: text/javascript

Json response format would be used by default if request doesn't have an Accept header or Accept header is not supported. For jsonp response format it is required to have a callback parameter in request (how to configure jsonp -  http://prntscr.com/3sett6)

 

Each request is authorized by accessToken parameter. It can be found / generated on "My Profile" page of Shortener UI

 

 

 

API methods:

 

List of available accounts

GET https://<base url>/accounts?access-token=<token>[&callback=<callback function>]

 

{
    "accounts" : [
        {
            "id" : 234,
            "name" : "ABC"
        },
        {
            "id" : 235,
            "name" : "XYZ"
        },
        ...
    ]
}

 

 

List of account campaigns

GET https://<base url>/accounts/<Account ID>/campaigns?access-token=<token>[&callback=<callback function>]

where <Account ID> –  ID of an account

Only active campaigns are returned. (Archived campaigns are not presented in result list)

Response format
{
    "campaigns" : [
        {
            "apiKey" : "E8CB563C-7F7E-416E-BCD5-950930B0FF25",
            "date" : "2013-05-01",
            "name" : "ABC",
        },
        {
            "apiKey" : "4D279E5B-3FD0-42E8-BB59-D3264E2DA106"
            "date" : "2013-05-01",
            "customDomain" : 
            "name" : "XYZ"         
        },
        ...
    ]
}

Campaign

GET https://<base url>/accounts/<Account ID>/campaigns/<Campaign Key>?access-token=<token>[&callback=<callback function>]

Response format
{
    "apiKey" : "E8CB563C-7F7E-416E-BCD5-950930B0FF25",
    "date" : "2013-05-01",
    "name" : "ABC",
    "customDomain" : 
}

 

 

Create campaign

POST https://<base url>/accounts/<Account ID>/campaigns?access-token=<token>[&callback=<callback function>]

with header:

Content-Type: application/json

and request body:

{
"name" : "",
"customDomain" : ""
}

*name – required attribute of campaign, cannot be empty.

customDomain -- optional. Max length is 255 characters. If some other account already use this customDomain, you will get an error.

Response format:

201 HTTP

with header:

Location : https://<base url>/accounts/<Account ID>/campaigns/<New Campaign Key>

 

 

Create A Single Tag

POST https://<base url>/tags/<tag>?access-token=<token>&hash=<hash>[&callback=<callback function>]

<hash> - hash of an url received after shortening that url for the first time

*<tag> – required

If the short link already has this tag, you will get an error. If everything is ok, provided tag will be attached to given short link.

Response format:

201 HTTP

with header:

Location : https://<base url>/tags/<tag>

 

 

 

Create Multiple Tags

PUT https://<base url>/tags?access-token=<token>&hash=<hash>[&callback=<callback function>]

with header:

Content-Type: application/json

and request body:

{
  "tags": ["<tag1>", "<tag2>", ...]
}

<hash> - hash of an url received after shortening that url for the first time. Required

tags - list of a tags to attach to a link. Required.

Tag cannot contain commas.

If everything is ok, provided tags will be attached to given short link.

Response format:

200 HTTP

with body

{
  "hash": <hash>,
  "tags": ["<tag1>", "<tag2>", ...]
}

 

 

 

Delete Tag

DELETE https://<base url>/tags/<tag>?access-token=<token>&hash=<hash>[&callback=<callback function>]

<hash> - hash of an url received after shortening that url for the first time

*tag – required

If short link has't had this tag yet, you will get an error. If everything is ok, provided tag will be detached from given short link.

Response format:

200 HTTP

 

 

 

Get Tag

GET https://<base url>/tags/<tag>?access-token=<token>[&callback=<callback function>]

*tag – required

Only checks whether the tag exists among all links of the given partner

Response format:

200 HTTP

Body:

{
"tag": "1d"
}

 

 

 

 

Errors

If API request is successful, the API returns a 200 HTTP status code along with the requested data in the body of the response.

If an error occurs with a request, the API returns an HTTP status code and reason in the response based on the type of error. Additionally, the body of the response contains a description of what caused the error. Here's an example of an error response:

{
 "error" : {
                "status" : 404
                "code" : 1,
                "message" : "Not found",
                "details" : "Resource located at  '/account/651/campaigns' path was requested but it doesn't exists",
                "moreInfo" : "http://support.po.st/issue14",
 }
}
Status Code Message  

400

41

Missing Parameter

Required parameter 'access-token' is missing.

Required parameter 'callback' is missing.

400

42

Invalid Parameter

The domain is already registered to another account. You may provide at most 255 characters for 'name' Attribute 'name' can not be empty. Required attribute 'name' is missing.

400

(429)

43

Rate Limited

You have exceeded the rate limit

400

54

Bad request

Failed to parse request body as json

401

44

Authentication Failed 

The partner with access-token '4fce641b-0cb6-11e3-afe7-2716faa64e93' is not found.

403

46

Blocked

When a Partner Account locked (DB blocked = true flag)

404

45

Not Found

Resource located at '/account/651/campaigns' path was requested but it doesn't exists

500

51

Internal Error

An internal server error has occured

503

52

Service Unavailable

API service is temporarily down for maitenance

46

"Blocked"

 

Account has been suspended for violations

 

 

Throttling

 

100 calls per second - must wait 12 hours

1000 calls per hour - must wait 24 hours

 

Examples

 

Account Campaigns

request:

GET https://<base url>/accounts/74/campaigns?access-token=ABC

 

Answer
{
    "campaigns" : [
        {
            "date" : "2013-05-01",
            "name" : "ABC",
            "apiKey" : "E8CB563C-7F7E-416E-BCD5-950930B0FF25"
        },
        {
            "date" : "2013-05-01",
            "name" : "XYZ",
            "apiKey" : "4D279E5B-3FD0-42E8-BB59-D3264E2DA106"
        }
    ]
}

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk