Switch branches/tags
Nothing to show
Latest commit 14a0d47 May 13, 2017 @lmmendes lmmendes committed on GitHub Update coupon.md

README.md

Passworks API

The Passworks API is based on a REST architecture which makes Passworks API predictable and resource oriented. It uses HTTP built-in features, like HTTP authentication, HTTP verbs (GET, POST, PUT, PATCH, DELETE) and HTTP response codes to allow easy access from any programming language via off-the-shelf libraries and tools.

Last updated at January 11th, 2017 see the CHANGELOG.md for more details.

SDKs

Get started quickly using Passworks with our SDK's. The SDK helps take the complexity out of coding by providing native classes for operating Passworks API.

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.

It's easy peasy!

API Endpoints

  • Assets - Upload images to use in your templates
  • Templates - List templates for use in your campaigns
  • Coupons - Discounts, Special Offers, Ongoing Engagement, Gift Card, Prepaid Cards, Return Credits
  • Store Cards - Loyalty, Membership Card,Photo ID, Monthly Passes
  • Event Tickets - Event admission, Season tickets, Movie Tickets
  • Boarding Passes - Airplane, Bus, Train, Boat and Generic boarding passes
  • Generic - Business cards and anything else
  • Certificates - List certificates for use in your campaigns
  • Registrations - Pass registrations
  • Organizations - Create and manage organizations under your main account (special permissions required)
  • Reports - Reporting and campaign metrics
  • Webhooks - Learn how use Passworks Webhooks

Webhooks

Passworks Platform has the ability to handle webhooks (wikipedia link).

The following events are monitored and sent to the the endpoint via HTTP POST:

Event name Description
created Pass was created
downloaded Pass was downloaded on the user's device
installed Pass was installed on the user's device
fetched User device fetched the pass from the server
redeemed Pass was redeemed
uninstalled Pass was uninstalled from the user's device

Please read more about webhooks here

Reports

In order to see the reports for each kind of campaign (boarding_pass, store_card, generic, event_ticket or coupon) we created a endpoint /reports and /reports/totals.

Please check the Reports pages for a better understanding on the numbers and calculations.

Identify for your account id and api key

To use the API you must provide your username and api_key in each request via Basic Auth.

Your username and api_key can be found here http://www.passworks.io/api_index

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.

curl -u account_id:api_key \
  -H 'Content-Type: application/json' \
  https://api.passworks.io/v2/ping

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&page2

Sorting

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

Example

GET https://api.passworks.io/v2/coupons/?q[name_eq]=Una Salus Victus

Read more about it here sorting campaigns and passes.

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:

$ curl -i https://api.passworks.io/v2/ping

HTTP/1.1 200 OK
Date: Tue, 23 Sep 2014 09:09:54 GMT
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1411459677
Header Name Description
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per hour.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

Note: Unauthenticated requests are associated with your IP address, and not the user making requests. For unauthenticated you have 60 requests per hour.

Using your own Passbook certificates

Adding a Passbook certificate (iOS Pass Type ID) is a rather cumbersome task so at the moment you can't do it via an API call.

You can add your own certificates via our site http://www.passworks.io/certificates

Help us make it better

Please tell us how we can make the API better. If you have a specific feature request or if you found a bug, please use GitHub issues. Fork these docs and send a pull request with improvements.

To talk with us and other developers about the API open a support ticket or mail us at api at passworks.io if you need to talk to us.