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 all Boxcar users. Prior to submitting your Provider application for approval, you may test it with up to 10 current Boxcar users. You must know each of the users registered e-mail address, and add those users through the Provider website. All API calls have a base URL of https://boxcar.io.
Authentication
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.
Rate limiting
Currently there is no rate limiting in place.
Example code
Is available on Github
Invitations / Subscriptions
Sending an Invitation to Subscribe
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.
The parameter is:
email— The Boxcar users e-mail address, MD5 hashed.
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=b58996c504c5638798eb6b511e6f49af" \
http://boxcar.io/devices/providers/fKJ9a8x9Q8QXSwzADwhy/subscribe
Notifications
Creating Individual Notifications
POST /devices/providers/#{provider_key}/notifications
The parameters are:
token— The unique token that identifies the service you are sending the notification to. You may also use an 'email' parameter instead.secret— The secret that correlates with the token that you are sending the notification to. You may also use an 'email' parameter instead.email— OPTIONAL - The users MD5'd e-mail address. If using this, your provider must not allow multiple installations and you do not need to pass the token/secret parameters from above.notification[from_screen_name]— The user or application sending the notification. This is matched for the redirect performed by Boxcar (if set by the user). This is a required field.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[redirect_payload]— Optional; The payload to be passed in as part of the redirection URL. Keep this as short as possible. If your redirection URL contains "::user::" in it, this will replace it in the URL. An example payload would be the users username, to take them to the appropriate page when redirecting.notification[source_url]— Optional; This is a URL that may be used for future devices. It will replace the redirect payload.
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 "token=hLG9qymP8d4SK7qhTNoT" \
-d "&secret=9k2lcHom55WwMa7qQzoErftR7fBGpLyLuvrp1LtG" \
-d "¬ification[from_screen_name]=Hello" \
-d "¬ification[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, not an individual services' secret.notification[from_screen_name]— The user or application sending the notification. This is matched for the redirect performed by Boxcar (if set by the user). This is a required field.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[redirect_payload]— Optional; The payload to be passed in as part of the redirection URL. Keep this as short as possible. If your redirection URL contains "::user::" in it, this will replace it in the URL.notification[source_url]— Optional; This is a URL that may be used for future devices. It will replace the redirect payload.
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 "¬ification[from_screen_name]=Hello" \
-d "¬ification[message]=This+is+an+example" \
http://boxcar.io/devices/providers/fKJ9a8x9Q8QXSwzADwhy/notifications/broadcast
Callbacks aka Webhooks
Deleted Subscriber
HTTP DELETE sent to the URL of your choice.
This is what you will receive when a Boxcar user chooses to delete your service.
The parameters you will receive are:
key— Your API key.user_email_hash— The unique reference for the Boxcar user.service[token]— The unique token for the Boxcar users service.
Example Ruby on Rails parameters:
Parameters: {"service"=>{"token"=>"hLG9qymP8d4SK7qhTNoT"}, "user_email_hash"=>"8e9e6c17b40e36a7567b1436dafba4f5", "key"=>"fKJ9a8x9Q8QXSwzADwhy"}
New or Updated Subscriber
HTTP POST sent to the URL of your choice.
This is what you will receive when a Boxcar user first creates your service, a payment is received, or the user chooses to turn off notifications for your service.
The parameters you will receive are:
key— Your API key.user_email_hash— The unique reference for the Boxcar user.service[token]— The unique token for this service.service[secret]— The secret for this service.service[active]— Boolean (0, 1) value for whether or not the service is active.service[needs_payment]— Boolean (0, 1) value for whether or not the service has been paid for.service[allow_redirects]— Boolean (0, 1) value for whether or not the user has chosen to allow your service to redirect them when viewing a push notification.
Example Ruby on Rails parameters:
Parameters: {"service"=>{"token"=>"hLG9qymP8d4SK7qhTNoT", "allow_redirects"=>"false", "needs_payment"=>"false", "secret"=>"9k2lcHom55WwMa7qQzoErftR7fBGpLyLuvrp1LtG", "active"=>"true"}, "user_email_hash"=>"8e9e6c17b40e36a7567b1436dafba4f5", "key"=>"fKJ9a8x9Q8QXSwzADwhy"}
In-app Integration
Boxcar provides two optional web views that are accessible from within the application. These webviews can have a custom label, and a custom URL that they point to for integration with your web application. We recommend that one of these point to any settings you may have, and the second points to a URL which provides help within the application.
The in-app webpage has a width of 280px. For an example page, please reference http://boxcar.io/providers/test_get.
When the user has not yet added your service, but is viewing an in-app webpage, you will be passed a parameter named "user_email_hash". This is a unique MD5 hash of the users e-mail address, and may be used to correlate it with any existing users in your system.
Once the user has added your service, if the user chooses to go back into the in-app webpage, you will receive several additional parameters.
To close the setup or help dialog from within your webpage, link to: "bxconnect://cancel".
The parameters you will receive are:
user_email_hash— The unique reference for the Boxcar user.token— The unique token for this service.secret— The secret for this service.version— The version of Boxcar this user is using.device— The type of device this service is being used on.
Example Ruby on Rails parameters:
Parameters: {"device"=>"touch", "token"=>"hLG9qymP8d4SK7qhTNoT", "user_email_hash"=>"8E9E6C17B40E36A7567B1436DAFBA4F5", "version"=>"2_4", "secret"=>"9k2lcHom55WwMa7qQzoErftR7fBGpLyLuvrp1LtG"}
Integration Screenshots
