Introduction

The PixelMe API allow access to you account information, creation, modification and deletion of redirects.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl -H "Authorization: Bearer <your_token>"

Make sure to replace <your_token> with your API key.

PixelMe uses API tokens to allow access to the API. You can get your API Token here.

PixelMe API expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <your_token>

You must replace <your_token> with your personal API key.

Account

Get your account info

curl -H "Authorization: Bearer <your_token>" \
"https://api.pixelme.me/accounts"

The above command returns JSON structured like this:

{
  "id": "5a009698f4dc87ec28804a6e",
  "name": "My awesome company",
  "pixels": [
    {
      "id": "nxs_3344",
      "name": "NS",
      "key": "3344",
      "provider_key": "nxs",
      "created_at": "2017-11-18T14:50:29Z"
    },
    {
      "id": "fb_109138409374",
      "name": "FB 1",
      "key": "109138409374",
      "provider_key": "fb",
      "created_at": "2017-11-13T19:53:12Z"
    },
    {
      "id": "fb_2038378409377",
      "name": "FB 2",
      "key": "2038378409377",
      "provider_key": "fb",
      "created_at": "2017-11-11T08:12:12Z"
    }
  ],
  "domains": ["rocks.awesome.me", "pix.rocks.me"],
  "campaigns": [
    {
      "id": "59a82a9966f87423ec16adbe",
      "name": "Twitter",
      "sub_campaigns": [
        {
          "id": "59a92c2966f8747eed6ee4ea",
          "name": "BF1"
        },
        {
          "id": "59a92cc266f8747eed6ee4ec",
          "name": "BF2"
        }
      ]
    },
    {
      "id": "5ba653f466f8747210bf5372",
      "name": "FB",
      "sub_campaigns": [
        {
          "id": "5ca6560266f87472f71424ed",
          "name": "social"
        }
      ]
    }
  ],
  "utms": {
    "utms_campaign": ["backfriday", "spring_sale"],
    "utms_medium": ["twitter", "facebook"],
    "utms_source": ["blog", "website"]
  }
}

This endpoint retrieves your account details.

HTTP Request

GET https://api.pixelme.me/accounts

Redirect

Create a new redirect

curl -H "Authorization: Bearer <your_token>" \
-d '{"url": "http://blog.intercom.com/how-to", "pixels_ids": ["nxs_3344", "fb_109138409374"], "domain": "rocks.awesome.me", "key": "black-friday"
  "dynamic_urls": [ {"url": "http://google.fr", "rule": "Referrer == \"google.fr\""}]}' \
"https://api.pixelme.me/redirects"

The above command returns JSON structured like this:

{
  "id": "5a396ae58943663aa6a53038",
  "url": "http://blog.intercom.com/how-to",
  "pixels": [
    {
      "id": "nxs_3344",
      "name": "NS",
      "key": "3344",
      "provider_key": "nxs",
      "created_at": "2017-11-18T14:50:29Z"
    },
    {
      "id": "fb_109138409374",
      "name": "FB 1",
      "key": "109138409374",
      "provider_key": "fb",
      "created_at": "2017-11-13T19:53:12Z"
    }
  ],
  "domain": "rocks.awesome.me",
  "key": "black-friday",
  "shorten": "http://rocks.awesome.me/black-friday",
  "campaign_id": "59a653f466f8747210bf5372",
  "sub_campaign_id": "59a6854f466f8747210bf5372"
}

This endpoint creates a new redirect.

HTTP Request

POST https://api.pixelme.me/redirects

JSON Parameters

Parameter	Description
url	URL to shorten (mandatory)
pixels_ids	array of pixels ids retrive from account details (optional)
domain	custom domain to use (optional)
key	key (slug) to use (optional)
tags	array of tags to add to this redirect (optional)
campaign_id	campaign id (optional)
sub_campaign_id	sub campaign id (optional)
dynamic_urls	routing rules for dynamic urls (optional)

Dynamic URL Routing

Parameter	Description
url: string	url to use if the rule is validated
rule: DynamicRule	rule to check before routing to the url

Examples :

"dynamic_urls": [
    {
      "url": "http://google.fr",
      "rule": "Referrer == \"1211565454\" and Date <= 1627794240"
    }

Dynamic Rule

All the operations can be written capitalized or lowercase (ex: AND or and can be used)

Operators are :

Parameter	Description
==	equals to
<=	less than equal to
>=	greater than equal to
co	contains
sw	starts with
ew	ends with

Logical Conjunctions are :

Operators	Description
AND	and
OR	or

Left Fields are :

Fields	Description
Date: number	current Date unix epoch format
Referrer: string	request Referrer as string
UserAgent: string	request UserAgent as string

Patch a redirect

curl -H "Authorization: Bearer <your_token>" \
-XPATCH \
-d '{"key": "new-black-friday"}' \
"https://api.pixelme.me/redirects/<id>"

The above command returns JSON structured like this:

{
  "id": "5a396ae58943663aa6a53038",
  "url": "http://blog.intercom.com/how-to",
  "pixels": [
    {
      "id": "nxs_3344",
      "name": "NS",
      "key": "3344",
      "provider_key": "nxs",
      "created_at": "2017-11-18T14:50:29Z"
    },
    {
      "id": "fb_109138409374",
      "name": "FB 1",
      "key": "109138409374",
      "provider_key": "fb",
      "created_at": "2017-11-13T19:53:12Z"
    }
  ],
  "domain": "rocks.awesome.me",
  "key": "new-black-friday",
  "shorten": "http://rocks.awesome.me/new-black-friday",
  "campaign_id": "59a653f466f8747210bf5372",
  "sub_campaign_id": "59a6854f466f8747210bf5372"
}

This endpoint updates a redirect.

HTTP Request

PATCH https://api.pixelme.me/redirects/<id>

URL Parameters

Parameter	Description
id	redirect ID (mandatory)

JSON Parameters

Parameter	Description
key	key (slug) to use (mandatory)
tags	array of tags to add to this redirect (optional)

List redirects

curl -H "Authorization: Bearer <your_token>" \
-XGET "https://api.pixelme.me/redirects"

The above command returns JSON structured like this:

{
  "redirects": [
    {
      "id": "5971291324b014fd1229de68",
      "url": "https://blog.elpassion.com/how-remarketing-can-help-you-get-more-users-with-infographic-786a838b5b9e",
      "domain": "pxlme.me",
      "key": "YuwOebig",
      "shorten": "https://pxlme.me/YuwOebig",
      "title": "",
      "created_at": "2019-05-21T14:48:52.446Z",
      "tags": [],
      "pixels": []
    },
    {
      "id": "5971291435b014dd1218de38",
      "url": "https://medium.com/@mytiyoapp/re-engaging-visitors-to-your-website-through-remarketing-85ccd44045dd",
      "domain": "pxlme.me",
      "key": "Wb9zv6mL",
      "shorten": "https://pxlme.me/Wb9zv6mL",
      "title": "",
      "created_at": "2019-05-20T04:23:12.562Z",
      "tags": [],
      "pixels": []
    }
  ],
  "total": 2,
  "start": 0,
  "length": 20
}

This endpoint list redirects.

HTTP Request

GET https://api.pixelme.me/redirects

URL Parameters

Parameter	Description
length	max redirects returned (max 20)
start	cursor start
url	list redirects matching this url

Delete a redirect

curl -H "Authorization: Bearer <your_token>" \
-XDELETE \
"https://api.pixelme.me/redirects/<id>"

The above command returns a 204 response code with no content.

This endpoint deletes a redirect.

HTTP Request

DELETE https://api.pixelme.me/redirects/<id>

URL Parameters

Parameter	Description
id	redirect ID (mandatory)

Errors

The PixelMe API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The specified entity could not be found.
405	Method Not Allowed -- You tried to access an entity with an invalid method.
429	Too Many Requests -- You're sending too many queries! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.