API Documentation

Intro

TrakQR API allows you to build QR Code features into your applications. This technical document outlines the usage of our RESTful API. Our API follows the REST(Representational State Transfer) style utilizing the GET, DELETE, and POST verbs. It responds with appropriate HTTP status codes and supports JSON.

Authentication

The TrakQR API requires clients to be authenticated for all endpoints. A client application may authenticate with the API through two different ways:

Standard HTTPS Basic Auth Simply use your account username and password in standard basic auth fashion. You can use Basic Auth for every request or you may use the supplied "sessionid" cookie as your authentication token.
Basic Auth is quite simple. Just add a header to your request named "HTTP_AUTHORIZATION". The value of this header should be "Basic {base64encoded username:password}". If your username were "Aladdin" and your password were "open sesame", your Basic Auth header should be:
HTTP_AUTHRORIZATION: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Please note that since all requests go over HTTPS your username and password are not sent in plain text. Everything is encrypted and secure.
"sessionid" Cookie If you are logged in through the dashboard or through the API via Basic Auth, you will have a "sessionid" cookie. If you send this cookie with any requests, we will honor that login until the session expires.
The sessionid cookie is passed to you just like any other cookie. On successful login (even Basic Auth logins), the response will contain a header like this:
Set-Cookie: sessionid={sessionidhere}; expires=Sat, 28-Apr-2012 19:33:12 GMT; Max-Age=1209600; Path=/
We will honor the validity of this cookie until the date listed in the expires directive. Please protect this session id. If anybody else gets it, they could use it to masquerade as you.

If not authenticated (or your sessionid has expired) the API will return a 401(Unauthorized) response.

Endpoints

GET: https://trakqr.com/api/code/
Returns a list of codes that meet specified criteria.

Request

GET: https://trakqr.com/api/code/

Response

HTTP 200

[
    {
        "Hash": "AbC",
        "Name": "My AWESOME Website",
        "Destination": "http://mymobilewebsite.com",
        "ShortUrl": "http://trakqr.com/zAbC",
        "Type": "url",
        "ID": 12345
    },
    {
        "Hash": "AbCd",
        "Name": "My cell",
        "Destination": "tel://1235551234",
        "ShortUrl": "http://trakqr.com/zAbCd",
        "Type": "tel",
        "ID": 123456
    }
]

GET: https://trakqr.com/api/code/{codeid}/
Returns detailed information about a specific code.

Request

GET: https://trakqr.com/api/code/12345

Response

HTTP 200

{
    "Hash": "AbC",
    "Name": "My AWESOME Website",
    "LastModified": "2011-07-26T04:22:46",
    "ScansTotal": "21665",
    "ScansThisCycle": "1206",
    "Destination": "http://mymobilewebsite.com",
    "ShortUrl": "http://trakqr.com/zAbC",
    "Type": "url",
    "ID": 12345,
    "Campaign": "",
    "Issue": "",
    "Publication": "",
    "Notifications": {
        "SMS": "1235551234",
        "Email": "firstlast@mywebsite.com"
    },
    "ScheduledChanges": [
        {
            "Id": 2,
            "NewDestination": "http://mymobilewebsite.com/awesomeconference",
            "ChangeScheduled": "2012-06-12T12:00:00",
            "NewType": "url"
        }
    ]
}

DELETE: https://trakqr.com/api/code/{codeid}/
Deletes a specific code.
Request
```
DELETE: https://trakqr.com/api/code/12345
```
Response
```
HTTP 204
```

POST: https://trakqr.com/api/code/{codeid}/
Updates a specific code.

Request

POST: https://trakqr.com/api/code/12345

{
    "Name": "Different Code Name",
    "Type": "url",
    "Destination": "http://mymobilesite.com/pool",
    "Campaign": "Summer",
    "Publication": "New York Times",
    "Issue": "125",
    "Notifications": {
        "SMS": "1235551234",
        "Email": "firstlast@mysite.com"
    }
}

Response

HTTP 200

{
    "Hash": "AbC",
    "Name": "Different Code Name",
    "LastModified": "2011-07-26T04:22:46",
    "ScansTotal": "21665",
    "ScansThisCycle": "1206",
    "Destination": "http://mymobilesite.com/pool",
    "ShortUrl": "http://trakqr.com/zAbC",
    "Type": "url",
    "ID": 12345,
    "Campaign": "Summer",
    "Issue": "125",
    "Publication": "New York Times",
    "Notifications": {
        "SMS": "1235551234",
        "Email": "firstlast@mywebsite.com"
    },
    "ScheduledChanges": [
        {
            "Id": 2,
            "NewDestination": "http://mymobilewebsite.com/awesomeconference",
            "ChangeScheduled": "2012-06-12T12:00:00",
            "NewType": "url"
        }
    ]
}

You only need to specify the variables that you want to update. All others can be left blank.

POST: https://trakqr.com/api/code/
Adds a new code to your account.

Request

POST: https://trakqr.com/api/code/

{
    "Name": "My New Code",
    "Type": "url",
    "Destination": "http://mymobilesite.com/patio",
    "Campaign": "Spring",
    "Publication": "New York Times",
    "Issue": "123",
    "Notifications": {
        "SMS": "1235551234",
        "Email": "firstlast@mysite.com"
    }
}

Response

HTTP 200

{
    "Hash": "AbE",
    "Name": "My New Code",
    "LastModified": "2011-07-26T04:22:46",
    "ScansTotal": "0",
    "ScansThisCycle": "0",
    "Destination": "http://mymobilesite.com/patio",
    "ShortUrl": "http://trakqr.com/zAbE",
    "Type": "url",
    "ID": 12345,
    "Campaign": "Spring",
    "Issue": "123",
    "Publication": "New York Times",
    "Notifications": {
        "SMS": "1235551234",
        "Email": "firstlast@mywebsite.com"
    },
    "ScheduledChanges": []
}

Only "Name", "Type", and "Destination" are required. All others are optional.

GET: https://trakqr.com/api/code/{codeid}.qr.{downloadformat}
Downloads the qr image for a specific code in a specified format.
{downloadformat} can be png, eps, pdf, or svg. The png version is raster. All others are vector. You may also specify these additional optional url parameters:
- size This is the size of the image in pixels. Size may be anywhere between 100 and 1000. The default size is 200px.
- color This is an ARGB hex color specifying the alpha, red, green, and blue options for the generated code. A standard hex RGB color may be substituted in place of the ARGB which creates a default alpha of 100% opaque. Default ARGB is "FF000000" (100% opaque black).
Request
```
GET: https://trakqr.com/api/code/12345.qr.png
```
Response
```
HTTP 200
```

GET: https://trakqr.com/api/scans/
Returns a list of all scans for all codes within a specific time period.

Request

GET: https://trakqr.com/api/scans/

Response

HTTP 200

{
    "start": "2012-01-01T00:00:00",
    "end": "2012-04-01T00:00:00",
    "scans": [
        {
            "IP": "123.123.123.123",
            "Browser": "android",
            "Location": "United States",
            "Time": "2012-03-16T11:42:19"
        },
        {
            "IP": "111.222.111.222",
            "Browser": "android",
            "Location": "United States",
            "Time": "2012-03-16T13:11:18"
        }
    ]
}

This list may alternatively be exported as a CSV or XLS by setting an optional url parameter "format" to "csv" or "xls" respectively.
You may also specify "start" and "end" url parameters in ISO 8601 format. If not specified, "start" defaults to the beginning of your current billing period. "end" will default to the current datetime.

GET: https://trakqr.com/api/scans/{codeid}/
Returns a list of all scans for a specific code within a specific time period.

Request

GET: https://trakqr.com/api/scans/12345

Response

{
    "start": "2012-01-01T00:00:00",
    "end": "2012-04-01T00:00:00",
    "scans": [
        {
            "IP": "123.123.123.123",
            "Browser": "android",
            "Location": "United States",
            "Time": "2012-03-16T11:42:19"
        },
        {
            "IP": "111.222.111.222",
            "Browser": "android",
            "Location": "United States",
            "Time": "2012-03-16T13:11:18"
        }
    ]
}

GET: https://trakqr.com/api/scheduledchange/{codeid}/{scheduledchangeid}
Returns detailed information about a specific change that is scheduled for a specific code.

Request

GET: https://trakqr.com/api/scheduledchange/12345/2

Response

HTTP 200

{
    "Id": 2,
    "NewDestination": "http://mymobilewebsite.com/awesomeconference",
    "ChangeScheduled": "2012-06-12T12:00:00",
    "NewType": "url"
}

DELETE: https://trakqr.com/api/scheduledchange/{codeid}/{scheduledchangeid}
Deletes a specific change that is scheduled for a specific code.
Request
```
DELETE: https://trakqr.com/api/scheduledchange/12345/2
```
Response
```
HTTP 204
```

POST: https://trakqr.com/api/scheduledchange/{codeid}/
Adds a new change to be scheduled for a specific code.

POST https://trakqr.com/api/scheduledchange/12345

{
    "NewDestination": "http://mymobilewebsite.com/otherconference",
    "ChangeScheduled": "2012-07-22T12:00:00",
    "NewType": "url"
}

Response

HTTP 201

{
    "Id": 3,
    "NewDestination": "http://mymobilewebsite.com/otherconference",
    "ChangeScheduled": "2012-07-22T12:00:00",
    "NewType": "url"
}

All fields are required.

All endpoints are required to function over HTTPS. If an HTTP connection is attempted, we will return a 301(redirect) with the location header specifying the HTTPS address for the endpoint requested.
All dates are in ISO 8601 format relative to US/Central timezone.

HTTP Verbs Used

GET Used to retrieve data from the system. A GET only accepts parameters in the querystring.
POST Used to add or update items. A POST to our API accepts data in JSON format through the request body.
DELETE Used to delete items. A DELETE accepts no additional data and offers only headers as it's response.

Any other verbs will result in a 405 method not allowed response.

HTTP Response Codes

200 Everything worked. We have a response for you.
201 We have created what you asked us to create and have a response for you.
204 We did what you asked but don't really have any data to give you back. (typically used on deletes)
301 What you asked for isn't available at this address. Try the address listed in the "Location" header provided. (typically used to let you know when you tried to access HTTP but the endpoint is only available over HTTPS)
400 We couldn't do what you wanted because there was an error in your request. We will return errors explaining what went wrong.
401 You aren't logged in. All endpoints in our api require you to be authenticated. Refer to the Authentication section
404 There is no API endpoint at this address.
405 There is a method at this endpoint but you aren't allowed to use it. (typically used when you try an invalid HTTP Verb - Like using a PUT vs a POST)
500 We screwed up. We're sorry. Our developers have been notified and will be working on fixing the problem. Don't expect an API response.

2xx means it worked. 3xx means your looking at the wrong place. 4xx means you did something wrong. 5xx means we did something wrong.

Additional Notes

Date Format
All dates (request or response) are in ISO 8601 format relative to US/Central time.
ISO 8601 follows the following format:
```
YYYY-MM-DDThh:mm:ss
```
[YYYY] refers to the full four digit year
[MM] refers to a zero-padded two digit month starting with "01" (Janurary = 01)
[DD] refers to a zero-padded two digit day of the month
[hh] refers to a zero-padded hour between 00 and 24.
[mm] refers to a zero-padded minute between 00 and 59.
[ss] refers to a zero-padded second between 00 and 60 (where 60 is only used to notate an added leap second).
Code Types
All codes have a specified type. Possible types are 'email', 'latlong', 'map', 'sms', 'tel', 'tweet', 'url', and 'vcard'.
Codes of each type must follow a specified format.
- email: must follow the format "mailto:username@yourdomain.com?subject=optionalURLEncodedSubject&body=OptonalURLEncodedBody"
- latlong: must be a google maps link with the format "http://maps.google.com/?t=latlong&q=:LatitudeHere,LongitudeHere"
- map: must be a google maps link with the format "http://maps.google.com/?q=YourFullAddressHere"
- sms: must follow the format "sms://YourCellNumberHere"
- tel: must follow the format "tel://YourPhoneNumberHere"
- tweet: must follow the format "http://twitter.com/home?status=URLEncodedTweetTextHere"
- url: may be any valid url
- vcard: must follow the format "vcard:Base64EncodedVcardData"
  Base64EncodedVcardData is just like it sounds. Take a valid vcard, base64 encode it, and append it to "vcard:"