Understanding the API workflow

Just before you start creating things using our API it's important that you understand the API flow.

There are 3 inherent concepts that are at work here:

The first is the concept of a campaign. A campaign, as viewed in the API, is simply seen as the aggregator for all of the generated passes for a given context.
A campaign can be, in pratical terms, a collection of "Membership or Loyalty" passes, a "Bus Boarding" pass, and several others. The type of campaign dictates what sort of data and purpose it can serve.

Then there's the concept of a pass. A pass, by itself, is simply a representation of all the information that your target consumer will see when he installs it on his mobile device, it's the "boarding pass" the "event ticket" or simply a discount "coupon".

Finally, there's the concept of an asset. All of the passes support the insertion of at least 1 or more images, being one of them the 'icon', which is required on all passes, regardless of campaign type. Therefore, in order to start creating any type of campaign, you need to have uploaded at least one asset, which you supply to the campaign upon creation.

Identify for your account id and api key

No XML, just JSON

We only support JSON for serialization of data. This means that you have to send Content-Type: application/json; charset=utf-8 when you're POSTing, or PATCHing data into Passworks.

Authentication

As stated previously, Passworks uses Basic Auth for authentication, this is secure since all requests made to https://api.passworks.io use SSL.

Making a request

All URLs start with https://api.passworks.io/v2/. SSL only. The path is prefixed with the API version. If we change the API in backward-incompatible ways, we'll bump the version number and maintain stable support for the old URLs.

To create objects using the API each request must include the Content-Type header with the value application/json and the body must contain data in the JSON format.

Pagination

Most collection call's on our API paginate their results. The first request returns up to
25 records. Check the next page for more results by adding &page=2, then
&page=3, and so on until you get an empty response.

Each page returns a maximum of 25 objects you can increase (up to 50 items per page) or decrease (to 1 per item page) this value adding the &per_page=50 .

If a given resource is paginated the API will emit the following headers:

Header Name

Description

X-Total: 42

Total number of items found

X-Total-Pages: 5

Total number of pages

X-Page: 3

The current page

X-Per-Page: 10

Amount of items displayed per page

X-Next-Page: 4

The number of the next page

X-Prev-Page: 2

The number of the previews page

X-Offset: 10

The offset to start from

Example

GET https://api.passworks.io/v2/coupons?per_page=10&page=2

Sorting

Passworks API supports sorting for the most common attributes via query string.

Example

Handling errors

If Passworks is having trouble, you might see a 5xx error. 500 means that the app is entirely down, but you might also see 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout. It's your responsibility in all of these cases to retry your request later.

Rate limiting

The rate limit and api throttling are not yet implemented.

Authenticated users can make up to 5000 requests per hour, each request is associated with the username.

You can check the returned HTTP headers of any API request to see your current rate limit status: