How to use Upscribe via API

In this guide you'll learn how to create an Upscribe-like 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/representations/.../logo.png",
      "description": "Weekly, in-depth email marketing advice for creators by email genius Brennan Dunn.",
      "pinned": false,
      "position": null,
      "max_payout": 150000,
      "last_30_days_confirmation_rate": 30,
      "signup_url": "https://recs.page/create-and-sell?ref_code=14ea515235",
      "partner_program_uuid": "partner_program_83ba92h24",
      "available_budget_dollars": 100000,
      "cpa": 300,
      "referrals": {
        "pending": 541,
        "rejected": 38,
        "confirmed": 2890
      },
      "earnings": 867000,
      "net_earnings": 800000
    }
   ,
   <Recommendation Object>,
   <Recommendation Object>,
 ]
}

You should use the data returned to show the recommendations to the user. The main fields are:

• publication_name: Name of the recommended newsletter

• description: Newsletter description or recommendation reason if you set one

• publication_logo: Link to the publication logo asset

• signup_url: Link to the page where the subscriber can complete their subscription

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

Native Upscribe Integration

This section requires you to apply and get approved by our team. Reach out to [email protected] if you want to start this process.

To create a referral submission 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.

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.

Use this API endpoint to tell SparkLoop which recommendations your subscriber wants to subscribe to. Your payload will need to include the subscriber_email , a string of comma separated recommendations' ref_codes (from the previous section) and the country_code.

Note: It is very important that you pass the country_code. Referrals without a country_code will almost certainly be rejected.

If this endpoint returns a 200, it means the submission to create referrals was accepted. The creation of referrals will depend on the system evaluation of that submission.