Developer Tools

Be sure to check out all of the great tools that the open source community has created for building Boxcar into your app or service.

Have a Boxcar project of your own to share? Message us on GitHub or send us a link at awesome@boxcar.io

Provider API

The provider API is very simple. There are three RESTful requests. SUBSCRIBE, CREATE and BROADCAST. Really, that's it. SUBSCRIBE will add your service for a user. CREATE sends a message to one user, or a subset of your users. Can you guess what BROADCAST does? Yep, it sends a single message to all of your users.

Ready to get started? Create a provider now.

We also have "generic" providers available for you to use, so that you don't have to necessarily create your own. Instead, use an existing one if it fits with what you'd like to do!

Learn more about generic providers on our blog, or see the current list of generic providers here.

Introduction

The Boxcar provider API is a standard REST API over HTTPS, with JSON responses. The provider API is for websites, companies and users that wish to offer their services to either a select group of Boxcar users, or to all Boxcar users. If you would like to limit your provider to a subset of Boxcar users, you must know each of the users registered e-mail addresses in advance. For providers that are able to serve all Boxcar users, your provider must first be approved prior to appearing in our provider marketplace.

Authentication

All API calls have a base URL of https://boxcar.io. Authentication is performed by using the appropriate provider API URL, your API key, and the Boxcar users registered e-mail address. At no time are you to collect the Boxcar users password.

Responses

All responses are returned using standard JSON arrays or hashes with an HTTP status code of 200 if the request succeeds.

For request failures, you will receive either HTTP status 403 or 401. If you receive an HTTP status code of 400, it is because you failed to send the proper parameters. For HTTP status code 401's, it is because you are passing in either an invalid token, or the user has not added your service.

Example code

Is available on Github

Subscriptions

Subscribing someone to your provider

POST /devices/providers/#{provider_key}/notifications/subscribe

This sends the user with the matching e-mail address a push notification which requests that they add your service. This will ease integration with your website, as you will have already registered them on your system and can identify whom they are based on their Boxcar e-mail address.

Please note, this API call is an exception and will return an HTTP status code of 404 if we are unable to find the registered user by e-mail in our system. If the email address is not found in our system, we'll send an email to it letting the user know where they can download Boxcar.

If the user has already added your service, we'll return an HTTP status code of 401.

The parameter is:

  • email — The Boxcar users e-mail address.

Example using cURL (please note, you will need to replace the provider_key in the URL and use the appropriate token/secret parameters):

curl -d "email=user_email@service.com" \
http://boxcar.io/devices/providers/fKJ9a8x9Q8QXSwzADwhy/notifications/subscribe

Notifications

Creating Individual Notifications

POST /devices/providers/#{provider_key}/notifications

Notifications can be sent to either a single user or a collection of users. The parameters are:

  • email — The users e-mail address.
  • emails — An array of user email addresses to send the notification to. If you provide this field, don't provide the "email" field.
  • notification[from_screen_name] — The user or application sending the notification.
  • notification[message] — The message to display to the user. This message should be at a maximum somewhere around 140 characters in length. Longer messages will be truncated depending on the client receiving it. This is a required field.
  • notification[from_remote_service_id] — An integer value that will uniquely identify the notification, and prevent duplicate notifications about the same event from being created. This is an optional field, but it is strongly recommended that you use it.
  • notification[source_url] — Optional; This is the URL the user will be taken to when they open your message.
  • notification[icon_url] — Optional; This is the URL of the icon that will be shown to the user. Standard size is 57x57.

We'll respond with HTTP status 200 for success. If there's a problem, an array named "errors" will contain an error code and the hashed email that triggered the error: HTTP status 401 if the user doesn't have the service added and HTTP status 404 if the provided email address isn't a Boxcar user.

Example using cURL (please note, you will need to replace the provider_key in the URL and use your e-mail address):

curl -d "email=example@boxcar.io" \
-d "&notification[from_screen_name]=Hello" \
-d "&notification[message]=This+is+an+example" \
http://boxcar.io/devices/providers/fKJ9a8x9Q8QXSwzADwhy/notifications

Broadcasting Notifications to All Services

POST /devices/providers/#{provider_key}/notifications/broadcast

The parameters are:

  • secret — This is your Provider secret.
  • notification[from_screen_name] — The user or application sending the message.
  • notification[message] — The message to display to the user. This message should be at a maximum somewhere around 140 characters in length. Longer messages will be truncated depending on the client receiving it. This is a required field.
  • notification[from_remote_service_id] — An integer value that will uniquely identify the notification, and prevent duplicate notifications about the same event from being created. This is an optional field, but it is strongly recommended that you use it.
  • notification[source_url] — Optional; This is the URL the user will be taken to when they open your message.
  • notification[icon_url] — Optional; This is the URL of the icon that will be shown to the user. Standard size is 57x57.

Note — if you have enabled this as a Generic provider, broadcast functionality will be disabled for security purposes.

Example using cURL (please note, you will need to replace the provider_key in the URL and use the appropriate token/secret parameters):

curl -d "secret=9k2lcHom55WwMa7qQzoErftR7fBGpLyLuvrp1LtG" \
-d "&notification[from_screen_name]=Hello" \
-d "&notification[message]=This+is+an+example" \
http://boxcar.io/devices/providers/fKJ9a8x9Q8QXSwzADwhy/notifications/broadcast

Generic Providers

Distribute your provider key/secret without worry.

Exactly as the name entails, this is for those providers that will be distributing a key/secret as part of their software. This disables broadcast functionality, but still allows individual messages to be created through the use of an email address for authentication.

See the current list of generic providers here.