Credentials are the backbone of the Sparkfly API. When issued correctly, they allow a member to redeem one or more offers. Sparkfly will properly handle the creation, expiration and redemption of identifiers that can be used to link a member to a purchase at the point of sale.
Credentials can exist that allow for more than one offer to be redeemed at a time. We're assuming you have already authenticated an have a valid auth token at this time (see the authentication section for an example). Below is an example of multiple offers on a credential:
First we can create a new credential for our member with id #123. After that is successful, we can attempt to attach our offers.
$ curl -i -XPOST --header 'X-Auth-Token: d47bfec9446fbe92ee9f7a7da3d1ab973ec0802c28b15f6d9a95ada41937b07d' \
'https://api.sparkfly.com/v1.0/credentials.json?member_id=123'
1
2
3
{"error": "channel_id is required"
}
Oops! We can see here that the request failed, because we forgot to include a channel_id. If you don't yet have a channel, see the channel API under main to see how to create one. Let's assume we have a working channel, add the ID to the request, and try again.
$ curl -i -XPOST --header 'X-Auth-Token: d47bfec9446fbe92ee9f7a7da3d1ab973ec0802c28b15f6d9a95ada41937b07d' \
'https://api.sparkfly.com/v1.0/credentials.json?member_id=123&channel_id=456'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{ "credential": {"id": 1009,
"account_id": 5,
"created_at": "2013-09-16T18:41:13Z",
"updated_at": "2013-09-16T18:41:13Z",
"identifier": null,
"member_id": 123,
"store_id": null,
"channel_id": 456,
"offer_ids": [], "annotations": {},"code_lifetime": null,
"supports_barcode": false,
"merchant_id": null,
"offer_name": null,
"merchant_name": null,
"location_address": null,
"url": null
},
"errors": {}}
Great! Now we get a 201 (Created) response, with associated member and channel IDs. The credential comes back with an ID of 1009. You'll notice that the identifier is "null", because there are no associated offers yet (offer_ids is an empty set).
Next we'll want to associate offers so we can get an identifier generated. We can do this by issuing a PUT request to the newly created credential. The first offer we want to associate has an ID of 1011
$ curl -i -XPUT --header 'X-Auth-Token: d47bfec9446fbe92ee9f7a7da3d1ab973ec0802c28b15f6d9a95ada41937b07d' \
'https://api.sparkfly.com/v1.0/credentials/1009.json?channel_id=456&offer_ids=1011'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{ "credential": {"id": 1009,
"account_id": 5,
"created_at": "2013-09-16T18:41:13Z",
"updated_at": "2013-09-16T18:51:23Z",
"identifier": "3345",
"member_id": 1,
"store_id": null,
"channel_id": 456,
"offer_ids": [ 1011],
"annotations": {},"code_lifetime": null,
"supports_barcode": false,
"merchant_id": null,
"offer_name": "First Offer",
"merchant_name": null,
"location_address": null,
"url": null
},
"errors": {}}
Once the credential is updated, we should see our offer ID in the offer_ids of the response, as well as our newly generated identifier (3345). At this point, the credential is valid and ready to redeem the single offer, with id 1011.
$ curl -i -XPUT --header 'X-Auth-Token: d47bfec9446fbe92ee9f7a7da3d1ab973ec0802c28b15f6d9a95ada41937b07d' \
'https://api.sparkfly.com/v1.0/credentials/1009.json?channel_id=456&offer_ids=1011'
We can repeat this process to add as many offers as needed like so:
$ curl -i -XPUT --header 'X-Auth-Token: d47bfec9446fbe92ee9f7a7da3d1ab973ec0802c28b15f6d9a95ada41937b07d' \
'https://api.sparkfly.com/v1.0/credentials/1.json?channel_id=456&offer_ids=1011,1116'
Assuming both offers are valid, the JSON response will now show both offer_ids associated with the credential.
There are several requirements for a credential to be considered valid. When issuing a POST request to create a credential, the "errors" field on the returned object should be blank. If you receive anything but a 200 status code, make sure to check this "errors" field for more information. Below is a list of some of the more common errors encountered when trying to create a valid credential.
| Validation | Error | Solution |
|---|---|---|
| Channel ID is not present | Channel can't be blank and must be associated with your account and offer | Make sure you send channel_id=<your-channel-id> on every request to create or update a credential. You will also need to make sure that the offers you are associating with the credential are also eligible for that same channel (shows up under the offer's eligibility). |
| Member ID is not present | Member can't be blank | Make sure you send member_id=<sparkfly-member-id> on every request to create a credential. |
| Associated offer(s) are not approved | offer <offer-name> must be approved to generate a credential | When you request an offer by id, the status should show up as approved. (See the Approve Offer action under Offers). |
| Member is not eligible for offer(s) | Member must be eligible for offer: <offer-name> | If you have a member list defined for the offer, make sure the member in question is on that list. Additionally, a member may not be eligible for an offer if you have redemption limits set. That is, an offer may have reached the total number of redemptions allowed as a whole, by channel, per member, or you may have hit the daily limit per member per day as defined on the offer itself. |
| One or more offers is not longer active | Offer with ID <offer-id> is no longer active | An offer must have an activates_at datetime field that is before the current date, and an expires_at datetime field that is after the current date. |
| Store is not eligible for offer(s) | Store must be eligible for offer: <offer-name> | If you have an eligible store list defined for the offer, make sure the store in question is on that list. Remember, store id is optional, and not needed to create a credential. |
| Credential is locked | This credential is currently locked for processing. Please try again later. | You had a member who went through the process of attempting to redeem an offer with this credential. In some cases, there may be a slight delay in processing. If a member attempts to immediately re-use a credential before it can be processed, this error may be returned. This shouldn't ever really be seen, but it is something to be aware of during testing. |
| Requested offers not found | Offer not found or not eligible by channel, with id: <one-or-more-requested-ids> | You are trying to associate one or more offers that either can't be found because the ids are not correct, or the offers are not eligible to be run under the channel id you are requesting. Make sure the offers exist and are eligible to appear on the requested channel. |
If you see the last message that offers were not found, remember that you need to attach eligible channels with each offer that you run. This can be done in the admin portal under the Publishing Channels section of the offer. If you do not see any channels listed at all, you can enable them when creating a merchant account. You will not be able to generate a credential code without at least one channel attached to your offer.
When a redemption (conversion) event occurs, it is sometimes desired to get a realtime callback posted to your system for real-time tracking purposes. This can be achieved by specifying a conversion_callback_url on a channel that you control. The Sparkfly system can send data to the conversion_callback_url every time an offer is redeemed.
| Field | Description |
|---|---|
| credential_id | The Sparkfly ID of the credential that was redeemed. |
| xid | The XID for the offer that was redeemed (XID is a unique GUID for offer and channel) |
| offer_id | The offer that was redeemed on this channel |
| offer_ids | All offers associated with the redeemed credential |
| store_id | The Sparkfly ID for the store where the credential was redeemed |
| redeemed_at | When the credential was redeemed |
| status | The status of the redeemed credential |
| sf_uid | The external identifier of the member who redeemed the credential (for promotions that use Sparkfly's landing page) |
| sf_ac | The name of the creative that was viewed to generate the credential (for promotions that use Sparkfly's landing page) |
You can substitute any of the above values in your conversion_callback_url by using the %{} notation like so:
http://my_server.com/callback/%{credential_id}?time_of_redemption=%{redeemed_at}
You would then receive a callback on redemption, with the specific values in place of each %{}.
In addition the the parameters named above, any attributes under the "conv_ids" key of the credential's annotations will also be available for selection. See the credential creation documentation for examples of how to set the credential's annotations. Any keys that cannot be resolved will result in blank parameters in the final URL.