The Sparkfly Platform provides a full lifecycle for promotions and rewards from creation to distribution to settlement. The platform integrates in real-time at the point-of-sale and provides item level discounting and tracking. The capabilities of the Sparkfly Platform are available through the use of the Sparkfly Platform API.
The Sparkfly Platform API is implemented using a RESTful interface that allows access to all functionality of the Sparkfly Platform. Communication with the API is performed using HTTPS on port 443.
The Sparkfly Platform API supports the JSON data serialization format. The HTTP Content-Type header is used to specify the request format and the HTTP Accept header or a URI extension is used to specify the response format. Content-Type is required if a transaction includes a request body. Either the Accept Header or URI Extension is required if a transaction includes a response body. The URI Extension will take precedence if a conflicting Accept Header and URI Extension are received.
| Format | Content-Type | Accept Header | URI Extension |
|---|---|---|---|
| JSON | application/json | application/json | .json |
We use cURL for demonstration purposes, but you can use any client of your choosing.
$ curl -i --header 'X-Auth-Token: 228b236272b6ffc7be0496a5f8186f4767afa3ade292ea1565831892941bb6cd' \
--header 'Content-Type: application/json' \
https://api.sparkfly.com/v1.0/members/1
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 X-Runtime: 0.042759 Content-Length: 153
The request would work the same way if we had sent .json at the end of the request URI (/v1.0/members/1.json) instead of sending the "application/json" header.
Authentication is performed against the API by providing a specified Account ID and API key within the HTTP x-headers as X-Auth-Identity and X-Auth-Key. Accounts have particular privileges providing various levels of access to resources within the platform.
$ curl -i --header 'X-Auth-Identity: <SPARKFLY_PROVIDED_ID>' \
--header 'X-Auth-Key: <SPARKFLY_PROVIDED_KEY>' \
https://api.sparkfly.com/auth
HTTP/1.1 204 No Content X-Auth-Token: fb598e824fd304af32fe34ed4a1af1210ce226ecf05c5f043a4f388d3ab74b12
Note how the response headers will contain an X-Auth-Token. All future API operations will only need to pass the received X-Auth-Token for authentication. Tokens will be valid for 24 hours. Applications must be developed in order to re-authenticate if an invalid token is used.
The API version is required and is indicated in the first element of the URI and will take the form: v[VERSION]. API version numbers will only be incremented when functionality is added that breaks compatibility with previous API versions.
Example: https://api.sparkfly.com/v1.0/
Please see the main section of the documentation for request/response examples of the actions that are possible.
The purpose of this document is to give you a basic overview of some of the core API features. It assumes you already have API credentials and access to the Admin Portal.
The first thing you will want to do is use your provided API credentials to authenticate and get an authentication token. Please see the documentation concerning authentication for more information. In all the requests below, we will need to send our API token in our request headers.
A typical setup step will be to tell the API about your user database. This way, you can create offers for your members. First let's see if there are any users in the database.
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
https://api-staging.sparkfly.com/v1.0/members.json
HTTP/1.1 200 OK
We can see that there are no members yet. Let's create one.
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
-XPOST -d '{ "member": { "identifier": "unique-member-id" } }' \
https://api-staging.sparkfly.com/v1.0/members.json
HTTP/1.1 201 Created
First, we send a POST to /v1.0/members.json to create our new member. The only thing you need to provide is a unique identifier to relate the member back to your system. You can repeat this any number of times until all of your users are loaded. Notice how in the response body, the newly created member has an ID of 1009. We can use that to request a specific member (or any resource) in the system at a later time by using the ID like so:
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
https://api-staging.sparkfly.com/v1.0/members/1009.json
HTTP/1.1 200 OK
If a member is coming from your application, you may also wish to search for them by your internal identifier. You can do that by querying the member search API endpoint:
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
https://api-staging.sparkfly.com/v1.0/members/search.json?identifier=unique-member-id
HTTP/1.1 200 OK
Next we'll want to setup a offer. You can create and configure a offer using the API if desired, but it it usually easier to do this through the Admin Portal. Follow the instructions in the Portal, and by the end of the process you should have at least one Merchant, and an Offer (this is the minimum setup needed to run an offer and generate codes for your members). It is also important to note that a Offer will be run by one or more Channels. A Channel is linked to a offer in a way that allows the system to track where your members are coming from, so that you can view offer statistics and control the number of members that redeem a offer.
Assuming we're done setting things up, let's query for our offer and make sure everything is working:
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
https://api-staging.sparkfly.com/v1.0/offers.json
HTTP/1.1 200 OK
Great! Now we can see our offer "Buy a Burger, Get Free Medium Fries".
After we release our offer, we will want to generate redeemable codes for our members. We do this by creating a record called a Credential. A Credential includes a code which allows a member to redeem a offer at a given location. A typical scenario might go something like this. A member is in your store and is using your Cool Mobile App (Channel ID 456), they click a button that says "Redeem Now", and you app triggers a backend query to the Sparkfly Platform to generate a credential like so:
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
-X POST \
https://api-staging.sparkfly.com/v1.0/credentials.json?member_id=1009&offer_id=1701&channel_id=456
HTTP/1.1 201 Created
Congratulations! You now have a Credential that you can display for your user. The key thing to look for here is the identifier field, "3540". This code is what can be entered in at the point of sale to trigger a redemption in Sparkfly's system!
Check out the section entitled Credentials In Depth if you run into any problems, or need more information on generating credentials.
Sparkfly provides a web-based landing page for any offer that you would like to have take advantage of this capability. The landing page provides additional tracking information in the form of Impressions, as well as the option of additional security. The following section explains how to setup an offer to use the landing page via the API.
First, make sure you are authenticated with the API and have at least one created offer.
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
https://api-staging.sparkfly.com/v1.0/offers.json
Since we don't have any offers yet we will create one now. All we need is a name.
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
-X POST -d '{ "offer": { "name": "Test offer" } }' \
https://api-staging.sparkfly.com/v1.0/offers.json
We have created an offer with ID 1290. We also need to approve the offer by sending a PUT request to the approve URL before it will appear correctly on the landing page:
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
-X PUT \
https://api-staging.sparkfly.com/v1.0/offers/1290/actions/approve.json
Next, make sure you have at least one Channel on which to publish your offer.
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
https://api-staging.sparkfly.com/v1.0/channels.json
If the total_entries field is 0, we will need to create a channel as well. For demonstration purposes, we'll create a landing page for an email campaign. Again, only a name is required here.
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
-X POST -d '{ "channel": { "name": "Email" } }' \
https://api-staging.sparkfly.com/v1.0/channels.json
Now we also have a channel with an ID of 5, meaning we now have at least one offer and one channel. Now we will need to associate the two. To associate the channel to the offer, we will need to POST to the following URL using your offer ID and a body containing an array with your channel ID.
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
-X POST -d '{ "offer": { "channel_ids": [5] } }' \
https://api-staging.sparkfly.com/v1.0/offers/1290/channels.json
We should get a 201 Created response code and something like:
Now if we perform a GET request on the offer, we should see that the channel is associated. The section we are interested in is the field called "channels" on the offer.
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
https://api-staging.sparkfly.com/v1.0/offers/1290.json
In particular, pay attention to the "xid" field. This is an identifier that links your offer to your channel, and it will act as the landing page URL. I should now be able to visit the landing page, with the xid as the path, and see my offer. For example, in the staging environment, our landing page would be: https://mp-staging.sparkfly.com/Z7nnWs6
Landing pages are cached for performance, and are re-cached every hour. If you go to a landing page, and get a 404 or do not see your changes, you may need to wait up to an hour for the page to be updated.
So at this point, we should be able to see a relatively plain offer page. Let's add a banner image to show up at the top of the landing page. To add an image, we will need to update the offer field called "formatting" on the offer, by sending a PUT request. Formatting is a nested object which contains a field called "bg_image". If we update bg_image, it should show up on the landing page:
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
-X PUT -d '{ "offer": { "formatting": { "bg_image": "https://my-domain/banner_image.png" } } }' \
https://api-staging.sparkfly.com/v1.0/offers/1290.json
We should get a 200 response that shows our bg_image in the response.
The recommended size for a banner image is 1200x600px. You can also set a background color for the header by setting "bg_color" in the formatting options, like so:
$ curl -i --header 'X-Auth-Token: <YOUR-AUTH_TOKEN>' \
-X PUT -d '{ "offer": { "formatting": { "bg_image": "https://my-domain/banner_image.png", "bg_color": "#FF00AA" } } }' \
https://api-staging.sparkfly.com/v1.0/offers/1290.json
For security purposes, the landing page is served over SSL. In order to maintain this security, any image you link to should also be served over https.
If you're testing a landing page from a desktop or laptop computer, the default behavior is to show a static, printable code. If you would like to preview what the landing page will look like on a mobile device, you can attach the parameter printable=false to the landing page URL. For example https://mp-staging.sparkfly.com/TRYstCR?printable=false