# 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](https://dash.sparkloop.app/settings/integrations).

### 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](http://sparkloop.local/upscribe) and following the checklist.

{% hint style="info" %}
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](http://sparkloop.local/partner_profile/overview).
{% endhint %}

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

<figure><img src="https://307340109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LvjCB8kc4yvMRscfT0m%2Fuploads%2Fr15q7xuK75pWRk4TN21m%2Fimage.png?alt=media&#x26;token=1ee4b09f-8edb-4b84-ae2a-db2d3a70f37c" alt=""><figcaption></figcaption></figure>

Alternatively, you can hit [this API endpoint](https://docs.sparkloop.app/api-v2/endpoints/upscribe#get-all-upscribes) to retrieve your Upscribe ID.&#x20;

### Generating recommendations

To generate recommendations simply hit [this API endpoint](https://docs.sparkloop.app/api-v2/endpoints/upscribe/recommendations#generate-recommendations).

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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) 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.

{% hint style="warning" %}
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.
{% endhint %}

`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:

```json
{
 "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

{% hint style="info" %}
This section requires you to apply and get approved by our team. Reach out to <support@sparkloop.app> if you want to start this process.
{% endhint %}

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.

{% hint style="warning" %}
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.
{% endhint %}

Use [this API endpoint](https://docs.sparkloop.app/api-v2/endpoints/upscribe#subscribe-to-recommendations) 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`.

{% hint style="warning" %}
Note: It is *very* important that you pass the `country_code`. Referrals without a `country_code` will almost certainly be rejected.
{% endhint %}

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.