How to use Upscribe via API

In this guide you'll learn how to recreate the Upscribe experience (showing recommendations and allowing your users to subscribe to them) using the SparkLoop APIs.

SparkLoop API Key

To access the SparkLoop APIs you will need your API key. You can find your API key under your Integration settings.

Activating Upscribe

To generate recommendations you'll need an active Upscribe.

If you haven't activated Upscribe yet, you can do so by going to this page and following the checklist.

Note: if you want to generate paid recommendations you will need to submit your application as a partner first. If you haven't done that yet, you can do so by going to this page.

Once your Upscribe is active you can find its ID in the header of the Upscribe page.

Alternatively, you can hit this API endpoint to retrieve your Upscribe ID.

Generating recommendations

To generate recommendations simply hit this API endpoint.

Make sure to use your Upscribe ID from the previous step as the identifier.

You can pass three parameters to this endpoint:

• country_code

• region_code

• limit

country_code is the ISO3166 Alpha2 country code (eg: US, IT, DE) of the person you're generating the recommendations for. It should always correspond to the country this person is at the moment you generate the recommendations.

Note: while technically this parameter is optional, it's EXTREMELY important to send it. Without it, SparkLoop won't be able to generate paid recommendations for the correct location and you'll earn less money.

region_code is the ISO 3166-2 state or region code (eg: TX, CA) of the person you're generating recommendations for.

This is definitely less important than the country code but some of our advertisers only target specific US states and if you don’t pass the state_code parameter our system will not generate recommendations for those advertisers.

limit is the number of recommendations you want to generate. To avoid inflating metrics, which then negatively impact your performance, always generate the number of recommendations you're going to display.

If no limit is passed 1 recommendation will be returned.

SparkLoop will return a response like this:

{
 "recommendations": [
   {
  "uuid": "partner_campaign_23ac0811bfff",
  "type": "paid",
  "status": "active",
  "ref_code": "14ea515235",
  "publication_name": "Create&Sell",
  "publication_logo": "https://dash.sparkloop.app/rails/active_storage/image.png",
  "partner_program_uuid": "partner_program_83ba92h24",
  "description": "Weekly, in-depth email marketing advice for creators by email genius Brennan Dunn.",
  "cpa": 300,
  "max_payout": 150000,
  "referral_pending_duration": 10,
  "last_30_days_confirmation_rate": 1,
  "can_be_recommended_via": ["upscribe"],
  "position": null,
  "pinned": false,
  "referrals": {
    "pending": 541,
    "rejected": 38,
    "confirmed": 2890
  },
  "earnings": 867000
}
   ,
   <Recommendation Object>,
   <Recommendation Object>,
 ]
}

You should use the data returned to show the recommendations to the user.

It’s up to you how to display in your app in a way that allows people to subscribe to them.

As an example, this is what that looks like on SparkLoop’s recommendation widget, Upscribe:

Ensure that users are only subscribed with their explicit consent and have not been misled in any way. Failure to comply will result in immediate account termination.

However you decide to display them, you should make a note of the ref_code of the recommendations people subscribe to as that's what you're going to send back to SparkLoop.

Subscribing to recommendations

The last step of this process is to tell SparkLoop which recommendations people subscribed to. This is done in two steps.

1. Create subscriber Create a subscriber using this endpoint.

   Note: It is very important that you pass the country_code when creating a subscriber. Subscribers without a country_code will almost certainly be rejected.

   If the subscriber had already been created, SparkLoop will return a 400 error. You should handle this error and use this endpoint to fetch the subscriber instead. Whether you’re creating or fetching the subscriber, you need to make a note of the subscriber’s uuid returned in the response.
2. Subscribe to recommendations Use this API endpoint to tell SparkLoop which recommendations your subscriber wants to subscribe to. Your payload will need to include the subscriber’s uuid (from the previous step) and a string of comma separated recommendations' ref_codes (from the previous section).