# API Interaction Methods

Here is a description of Each Method of the class API\_HELPER in order to get access to all information provided by the SDK.

A whole set of public methods exists within the SDK using which you can easily access most of the data.

|                                                |                                                          |
| ---------------------------------------------- | -------------------------------------------------------- |
| formSubmit(param: RHSubscriber)                | Submits a form to create a new subscriber.               |
| getSubscriberDetail()\`                        | Fetches details for a subscriber.                        |
| DeleteSubscriber()                             | Deletes a subscriber                                     |
| UpdateSubscriber(param: RHSubscriber)          | Updates subscriber details.                              |
| clickCapture(social: String)                   | Captures a click action for a specified social media     |
| getMyReferrals()                               | Retrieves referral data for the subscriber               |
| getLeaderboard()                               | Fetches the leaderboard data                             |
| trackReferral(param: RHTrackReferral)          | Tracks a referral event                                  |
| ConfirmReferral()                              | Confirms a referral                                      |
| OrganicTrackReferral(param: RHOrganicReferral) | Tracks an organic referral event                         |
| CreatePendingReferral(param: RHReferral)       | Creates a pending referral                               |
| RewardsList()                                  | Retrieves a list of rewards                              |
| ReferrerList()                                 | Fetches a list of referrers based on specific parameters |
| Logout()                                       | Logs out the current user and clears stored data         |

#### 1. Add Subscriber

Setting/Updating the ReferralParams details is an important step. This is how ReferralHero would be aware of the identity of a business user as classified by your app.

To add a subscriber (for example, post a successful signup or login) simply call ReferralHero's `RH.formSubmit()` function and send the `RHSubscriber` information such as email address and name.

{% tabs %}
{% tab title="Input" %}
{% code overflow="wrap" %}

```swift
func formSubmit()
    {
        RH.formSubmit(param: RHSubscriber(email: "xyz@gmail.com", domain: "www.abc.com", name: “ABC"))
    }
```

{% endcode %}
{% endtab %}

{% tab title="Output" %}

```swift
 {
    "status": "ok",
    "data": {
        "id": "sub_8645f85ac894",
        "name": "Test User 10",
        "email": "test10@gmail.com",
        "phone_number": "",
        "crypto_wallet_address": "",
        "crypto_wallet_provider": "",
        "extra_field": "",
        "extra_field_2": "",
        "option_field": "",
        "conversion_amount": 0,
        "code": "3ab0f674",
        "position": 10,
        "referred": false,
        "referred_by": {},
        "people_referred": 0,
        "promoted": false,
        "promoted_at": null,
        "verified": true,
        "verified_at": 1684403108,
        "points": 0,
        "risk_level": 0,
        "host": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxx/analytics/traffic",
        "source": null,
        "device": null,
        "referral_link": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxxx/analytics/traffic?mwr=3ab0f674",
        "created_at": 1684403108,
        "last_updated_at": 1684403108,
        "response": "subscriber_created"
    },
    "calls_left": null,
    "timestamp": 1684403108
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
NOTE:

The parameters need to be sent in the correct order for our system to automatically generate a referral.
{% endhint %}

#### 2. Update Subscriber Details

This method is used to update various user related data.

First, create a RHSubscriber model and set the user data you want to update.

To update the subscriber simply call ReferralHero's `RH.UpdateSubscriber()` function and send the `RHSubscriber` information such as email address and name.

{% tabs %}
{% tab title="Input" %}
{% code overflow="wrap" %}

```swift
  RH.UpdateSubscriber(param: RHSubscriber(email:"abc@gmail.com", domain: "www.xyz.com", name: "abc"))

```

{% endcode %}
{% endtab %}

{% tab title="Output" %}

```swift
{
  "status": "ok",
  "data": {
    "response": "subscribers_retrieved",
    "subscribers": [
      {
        "id": "sub_fa49ba0d30e9",
        "name": "Test User 10",
        "email": "test125@gmail.com",
        "phone_number": "",
        "crypto_wallet_address": "",
        "crypto_wallet_provider": "",
        "extra_field": "",
        "extra_field_2": "",
        "option_field": "",
        "conversion_amount": 0,
        "code": "dededb46",
        "position": 20,
        "referred": true,
        "referred_by": {
          "id": "sub_d0cc231dce89",
          "name": "Test name",
          "email": "test26@gmail.com",
          "code": "0879561f",
          "people_referred": 1,
          "points": 0
        },
        "people_referred": 0,
        "promoted": false,
        "promoted_at": null,
        "verified": true,
        "verified_at": 1684985427,
        "points": 0,
        "risk_level": 0,
        "host": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxxxx/analytics/traffic",
        "source": null,
        "device": null,
        "referral_link": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxxx/analytics/traffic?mwr=dededb46",
        "created_at": 1684985427,
        "last_updated_at": 1684985427
      }
    ],
    "pagination": {
      "total_pages": 1,
      "current_page": 1,
      "per_page": 50,
      "total_objects": 1
    }
```

{% endtab %}
{% endtabs %}

#### 3. Get Subscriber Details

This method is used to retrieve Subscriber details. RH.getSubscriberDetail()

{% tabs %}
{% tab title="Input" %}

```swift
  RH.getSubscriberDetail()
```

{% endtab %}

{% tab title="Output" %}

```swift
{
    "status": "ok",
    "data": {
        "id": "sub_ee32baa54196",
        "name": "Test User 10",
        "email": "test15@gmail.com",
        "phone_number": "",
        "crypto_wallet_address": "",
        "crypto_wallet_provider": "",
        "extra_field": "",
        "extra_field_2": "",
        "option_field": "",
        "conversion_amount": 0,
        "code": "e7ceeff6",
        "position": 1,
        "referred": false,
        "referred_by": {},
        "people_referred": 0,
        "promoted": false,
        "promoted_at": null,
        "verified": true,
        "verified_at": 1684408479,
        "points": 0,
        "risk_level": 0,
        "host": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxx/analytics/traffic",
        "source": null,
        "device": null,
        "referral_link": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxx/analytics/traffic?mwr=e7ceeff6",
        "created_at": 1684408479,
        "last_updated_at": 1684408479,
        "response": "subscriber_retrieved"
    },
    "calls_left": null,
    "timestamp": 1684414915
}


```

{% endtab %}
{% endtabs %}

#### 4. Delete Subscriber

This method is used to Delete a newly Created Subscriber.

To update the subscriber call ReferralHero's `RH.DeleteSubscriber()`.

{% tabs %}
{% tab title="Input" %}

```
  RH.DeleteSubscriber()
```

{% endtab %}

{% tab title="Output" %}

```json
{
    "status": "ok",
    "data": {
        "id": "sub_0d7cfab3a25f",
        "name": "Test User 10",
        "email": "android3@test",
        "phone_number": "",
        "crypto_wallet_address": "",
        "crypto_wallet_provider": "",
        "extra_field": "",
        "extra_field_2": "",
        "option_field": "",
        "conversion_amount": 0,
        "code": "41eace36",
        "position": 8,
        "referred": false,
        "referred_by": {},
        "people_referred": 0,
        "promoted": false,
        "promoted_at": null,
        "verified": true,
        "verified_at": 1684831504,
        "points": 0,
        "risk_level": 0,
        "host": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxx/analytics/traffic",
        "source": null,
        "device": null,
        "referral_link": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxx/analytics/traffic?mwr=41eace36",
        "created_at": 1684831504,
        "last_updated_at": 1684831504,
        "response": "subscriber_deleted"
    },
    "calls_left": null,
    "timestamp": 1685012056
}
```

{% endtab %}
{% endtabs %}

#### 5. Track Referral

This method is used to track the referral conversion event. It means it is used to convert Referral status from pending to unconfirmed/confirmed.

**If the referrer is present** in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, we will create the referral and set the referral status.

**If the referrer is not present** in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, the referral will not be created.

**Note:**

1. Your campaign must be set up as a custom event or a multi-step event otherwise, an error will return.
2. If the referral is present in ReferralHero with pending status, a successful response `custom_event_completed` will return.
3. If the referral unique identifier is not present in the ReferralHero, but the referrer unique identifier is present, a successful response `custom_event_completed` with the data of the new confirmed referral will return.
4. If a referral exists but the referral status is not pending, the error `custom event is already completed` will return.
5. If the referral unique identifier is not present in ReferralHero and the referrer is also not provided in the API, the error `referer is invalid or not present` will return.
6. If the referral status is unconfirmed or confirmed, the error `custom event is already completed` will return.

{% hint style="info" %}

* uniqueIdentifier is a placeholder.
* When tracking referrals on your App you should ALWAYS send the ACTUAL unique identifier (email, phone number, crypto wallet address, or other ID) of the user in RHSubscriber class Object
  {% endhint %}

Call `RH.trackReferral`(**RHTrackReferral** *referralparams* ). Use the following code to Track referral:

{% tabs %}
{% tab title="Input" %}
{% code overflow="wrap" %}

```swift
RH.trackReferral(param: RHTrackReferral(email: "xyz@gmail.com", name:"xyz"))
```

{% endcode %}
{% endtab %}

{% tab title="Output" %}

```swift
{
  "status": "error",
  "message": "Custom Event is already completed.",
  "code": "custom_event_already_completed"
}
```

{% endtab %}
{% endtabs %}

#### 6. Capture Share

**Step 1. Method Usage**

This method is used to send the Share event to the RH. It means if a user called this method with any params like Facebook, messenger, etc. We capture this as a share in our system.

Call the RH.clickCapture method of the RH class and pass “social” as an input parameter. Use the following code to Capture Share for a user:

{% tabs %}
{% tab title="Input" %}

```swift
RH.clickCapture(social: "facebook")
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "ok",
  "data": {
    "id": "sub_0d7cfab3a25f",
    "name": "Test User 10",
    "email": "android3@test",
    "phone_number": "",
    "crypto_wallet_address": "",
    "crypto_wallet_provider": "",
    "extra_field": "",
    "extra_field_2": "",
    "option_field": "",
    "conversion_amount": 0,
    "code": "41eace36",
    "position": 8,
    "referred": false,
    "referred_by": {},
    "people_referred": 0,
    "promoted": false,
    "promoted_at": null,
    "verified": true,
    "verified_at": 1684831504,
    "points": 0,
    "risk_level": 0,
    "host": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxx/analytics/traffic",
    "source": null,
    "device": null,
    "referral_link": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxx/analytics/traffic?mwr=41eace36",
    "created_at": 1684831504,
    "last_updated_at": 1684831504,
    "response": "click captured"
  },
  "calls_left": null,
  "timestamp": 1685006602
}
```

{% endtab %}
{% endtabs %}

#### 7. Get My Referrals

This method is used for retrieving all referrals of the specific subscriber.

Call `RH.getMyReferrals()` method of the RH class

Use the following code to Get My Referrals:

{% tabs %}
{% tab title="Input" %}

```swift
RH.getMyReferrals()
```

{% endtab %}

{% tab title="Output" %}

```swift
{
  "status": "ok",
  "data": {
    "response": "subscribers_retrieved",
    "subscribers": [
      {
        "id": "sub_fa49ba0d30e9",
        "name": "Test User 10",
        "email": "test125@gmail.com",
        "phone_number": "",
        "crypto_wallet_address": "",
        "crypto_wallet_provider": "",
        "extra_field": "",
        "extra_field_2": "",
        "option_field": "",
        "conversion_amount": 0,
        "code": "dededb46",
        "position": 20,
        "referred": true,
        "referred_by": {
          "id": "sub_d0cc231dce89",
          "name": "Test name",
          "email": "test26@gmail.com",
          "code": "0879561f",
          "people_referred": 1,
          "points": 0
        },
        "people_referred": 0,
        "promoted": false,
        "promoted_at": null,
        "verified": true,
        "verified_at": 1684985427,
        "points": 0,
        "risk_level": 0,
        "host": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxx/analytics/traffic",
        "source": null,
        "device": null,
        "referral_link": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxx/analytics/traffic?mwr=dededb46",
        "created_at": 1684985427,
        "last_updated_at": 1684985427
      }
    ],
    "pagination": {
      "total_pages": 1,
      "current_page": 1,
      "per_page": 50,
      "total_objects": 1
    }
  },
  "calls_left": null,
  "timestamp": 1685012334
}
```

{% endtab %}
{% endtabs %}

#### 8. Get Leaderboard

This method is used for retrieving the campaign leaderboard. It will get the leaderboard from the Campaign specified in the Appdelegate.swift file.

**Step 1. Input Parameters**

Call the `RH.getLeaderboard()` method of the RH class to get the Subscriber Leaderboard.

{% tabs %}
{% tab title="Input" %}

```swift
RH.getLeaderboard()
```

{% endtab %}

{% tab title="Output" %}

```swift
{
  "status": "ok",
  "data": {
    "ranking": [
      {
        "id": "sub_7b9be1ed8ccb",
        "name": "Test User 10",
        "email": "test15@gmail.com",
        "phone_number": "",
        "crypto_wallet_address": "",
        "crypto_wallet_provider": "",
        "extra_field": "",
        "extra_field_2": "",
        "option_field": "",
        "conversion_amount": 0,
        "code": "2c2dbefb",
        "position": 1,
        "referred": false,
        "referred_by": {},
        "people_referred": 0,
        "promoted": false,
        "promoted_at": null,
        "verified": true,
        "verified_at": 1685018462,
        "points": 0,
        "risk_level": 0,
        "host": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxx/analytics/traffic",
        "source": null,
        "device": null,
        "referral_link": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxx/analytics/traffic?mwr=2c2dbefb",
        "created_at": 1685018462,
        "last_updated_at": 1685020506
      },
      {
        "id": "sub_06e2af5a2236",
        "name": "Test User multi1",
        "email": "testorganic3@gmail.com",
        "phone_number": "",
        "crypto_wallet_address": "",
        "crypto_wallet_provider": "",
        "extra_field": "",
        "extra_field_2": "",
        "option_field": "",
        "conversion_amount": 0,
        "code": "afd54225",
        "position": 2,
        "referred": false,
        "referred_by": {},
        "people_referred": 0,
        "promoted": false,
        "promoted_at": null,
        "verified": true,
        "verified_at": 1685018562,
        "points": 0,
        "risk_level": 0,
        "host": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxx/analytics/traffic",
        "source": null,
        "device": null,
        "referral_link": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxx/analytics/traffic?mwr=afd54225",
        "created_at": 1685018562,
        "last_updated_at": 1685018562
      }
    ],
    "count": 2
  },
  "calls_left": null,
  "timestamp": 1685020750
}
```

{% endtab %}
{% endtabs %}

#### 9. Create Pending Referral

This method is used for creating a Referral with the Pending Status.

Create a ReferralParams class object and set the various user details to recognize the user matching your back-end system. To add a pending referral, simply call ReferralHero's `RH.CreatePendingReferral()` function and send the ReferralParams information such as email address and name.

{% tabs %}
{% tab title="Input" %}
{% code overflow="wrap" %}

```swift
RH.CreatePendingReferral(param: RHReferral(email: "xyz@gmail.com", name: "XYZ"))
```

{% endcode %}
{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "ok",
  "data": {
    "id": "sub_1bb1e02b90cb",
    "name": "Pending Referral",
    "email": "testpending1@email.com",
    "phone_number": "",
    "crypto_wallet_address": "",
    "crypto_wallet_provider": "",
    "extra_field": "",
    "extra_field_2": "",
    "option_field": "",
    "conversion_amount": 0,
    "code": "1b155f4e",
    "position": 3,
    "referred": true,
    "referred_by": {
      "id": "sub_7b9be1ed8ccb",
      "name": "Test User 10",
      "email": "test15@gmail.com",
      "code": "2c2dbefb",
      "people_referred": 0,
      "points": 0
    },
    "people_referred": 0,
    "promoted": false,
    "promoted_at": null,
    "verified": true,
    "verified_at": 1685018482,
    "points": 0,
    "risk_level": 0,
    "host": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxx/analytics/traffic",
    "source": null,
    "device": "IOS",
    "referral_link": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxx/analytics/traffic?mwr=1b155f4e",
    "created_at": 1685018482,
    "last_updated_at": 1685018482,
    "os_type": "IOS",
    "screen_size": "64*32",
    "ip_address": "123.456.789.0123",
    "response": "subscriber_created"
  },
  "calls_left": null,
  "timestamp": 1685018482
}
```

{% endtab %}
{% endtabs %}

#### 10. Organic Track Referral

If you would like to track referrals or add organic subscribers on the conversion page to your referral campaign, you can use this method.

**If the Referrer code and uniqueidentifier are present**, a Referral is created with the status unconfirmed/confirmed referral on the basis of the ‘Review Referral’ feature enabled/disabled.

**If the Referrer code is not present but uniqueidentifier is present**, an Organic Subscriber is created.

If the Referrer code is not present but a uniqueidentifier is present and **a Referral already exists with the same uniqueidentifier in the campaign** with pending status, the Referral Status will convert from pending to unconfirmed/confirmed on the basis of the ‘Review Referral’ feature enabled/disabled.

Create a RHOrganicReferral model and set the various user details to recognize the user matching your back-end system.

{% tabs %}
{% tab title="Input" %}
{% code overflow="wrap" %}

```swift
RH.OrganicTrackReferral(param: RHOrganicReferral(email: "abc@gmail.com", name: "ABC"))
```

{% endcode %}
{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "ok",
  "data": {
    "id": "sub_41adff0cfc8e",
    "name": "Test organic User1",
    "email": "testorganic1@gmail.com",
    "phone_number": "",
    "crypto_wallet_address": "",
    "crypto_wallet_provider": "",
    "extra_field": "",
    "extra_field_2": "",
    "option_field": "",
    "conversion_amount": 0,
    "code": "23e0fb1c",
    "position": 5,
    "referred": true,
    "referred_by": {
      "id": "sub_7b9be1ed8ccb",
      "name": "Test User 10",
      "email": "test15@gmail.com",
      "code": "2c2dbefb",
      "people_referred": 0,
      "points": 0
    },
    "people_referred": 0,
    "promoted": false,
    "promoted_at": null,
    "verified": true,
    "verified_at": 1685020506,
    "points": 0,
    "risk_level": 0,
    "host": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxxx/analytics/traffic",
    "source": null,
    "device": null,
    "referral_link": "https://app.referralhero.com/dashboard/lists/MFxxxxxxxxxxx/analytics/traffic?mwr=23e0fb1c",
    "created_at": 1685020506,
    "last_updated_at": 1685020506,
    "os_type": null,
    "screen_size": null,
    "ip_address": null,
    "response": "subscriber_created"
  },
  "calls_left": null,
  "timestamp": 1685020506
}
```

{% endtab %}
{% endtabs %}

#### 11. Confirm Referral

Confirm a referral. Useful when your campaign Goal is set to a "3-step conversion event" option and you want to confirm referrals when they complete your 3rd conversion event.

{% hint style="warning" %}
Only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a `subscriber_not_found` error.
{% endhint %}

Call the `RH.ConfrimReferral` method of the RH class.

{% tabs %}
{% tab title="First Tab" %}

```swift
RH.ConfirmReferral()
```

{% endtab %}

{% tab title="Second Tab" %}

```swift
{
  "status": "error",
  "message": "Subscriber is already confirmed",
  "code": "subscriber_already_confirmed"
}
```

{% endtab %}
{% endtabs %}

#### 12. Get Referrer

Call the RH.ReferrerList method of the RH class. Use the following code to get the referrer:

{% tabs %}
{% tab title="Input" %}

```
RH.ReferrerList()
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "ok",
  "data": {
    "id": "sub_68c9ed9e2712",
    "name": "test one",
    "email": "test1@gmail.com",
    "phone_number": "",
    "crypto_wallet_address": "",
    "crypto_wallet_provider": "",
    "extra_field": "",
    "extra_field_2": "",
    "option_field": "",
    "conversion_amount": 0,
    "code": "00598133",
    "position": 3,
    "referred": false,
    "referred_by": {},
    "people_referred": 1,
    "promoted": false,
    "promoted_at": null,
    "verified": true,
    "verified_at": 1686310876,
    "points": 0,
    "risk_level": 0,
    "host": "https://app.referralhero.com",
    "source": null,
    "device": null,
    "referral_link": "https://app.referralhero.com?mwr=00598133",
    "created_at": 1686310876,
    "last_updated_at": 1686311874,
    "response": "subscriber_retrieved"
  },
  "calls_left": null,
  "timestamp": 1686554060
}
```

{% endtab %}
{% endtabs %}

#### 13. Get Rewards

Call the RH.RewardsList method of the RH class. Use the following code to get the rewards:

{% tabs %}
{% tab title="Input" %}

```swift
RH.RewardsList()
```

{% endtab %}

{% tab title="Output" %}

```swift
{
  "status": "ok",
  "data": {
    "response": "rewards_retrieved",
    "rewards": [
      {
        "id": 1795,
        "name": "A free Premium account for 1 year",
        "status": "confirmed",
        "referrals": null,
        "created_at": 1686397951,
        "signup_type": "organic subscriber",
        "referrals_type": null,
        "recurring_count": null
      }
    ],
    "pagination": {
      "total_pages": 1,
      "current_page": 1,
      "per_page": 10,
      "total_objects": 1
    }
  },
  "calls_left": null,
  "timestamp": 1686561327
}
```

{% endtab %}
{% endtabs %}