# Subscribers

## Create a subscriber

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v2/subscribers`

#### Request Body

| Name                                    | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| email<mark style="color:red;">\*</mark> | string | Email                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| name                                    | string | Name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| referrer\_code                          | string | The referral code of the person who referred this subscriber. If Joanne with ref\_code ***joanne123*** referred this subscriber, you should set this value to ***joanne123***                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ip\_address                             | string | IP Address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| user\_agent                             | string | User Agent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| utm\_source                             | string | UTM Source                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| utm\_campaign                           | string | UTM Campaign                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| created\_at                             | string | <p>Timestamp when subscriber signed up. You can set this value to a date in the past.<br><br>Expected format: <br><em><strong>YYYY-MM-DDThh:mm:ssTZD</strong></em><br><em><strong>e</strong></em>.<em><strong>g. 2021-03-22T19:20:30+01:00</strong></em><br><br>Where:<br>YYYY = four-digit year<br>MM    = two-digit month (01=January, etc.)<br>DD      = two-digit day of month (01 through 31)<br>hh       = two digits of hour (00 through 23) <br>mm     = two digits of minute (00 through 59)<br>ss        = two digits of second (00 through 59)<br>s          = one or more digits representing a decimal fraction of a second<br>TZD     = time zone designator (Z or +hh:mm or -hh:mm)</p> |
| country\_code                           | string | Alpha-2 ountry code of the subscriber                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

{% tabs %}
{% tab title="201: Created " %}

```
{
    "subscriber": <Subscriber Object>
}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="Email taken" %}

```
{
    "error": "Email has already been taken"
}
```

{% endtab %}

{% tab title="Email invalid" %}

```
{
    "error": "Email is invalid"
}
```

{% endtab %}

{% tab title="Email not provided" %}

```
{
    "error": "You have to provide at least an email"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Get subscribers

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v2/subscribers`

Subscribers are ordered in desceding order by *created\_at*, meaning the first page shows the latest subscribers.

#### Query Parameters

| Name   | Type   | Description                                                                                            |
| ------ | ------ | ------------------------------------------------------------------------------------------------------ |
| type   | string | Type of subscribers you want to get. Default is *all*, allowed values are *all, referrals, advocates.* |
| expand | string | If you pass "campaigns" the response will include referral\_programs data                              |

{% tabs %}
{% tab title="200 Used query params ?page=2\&per\_page=2" %}

```json
{
  "subscribers": [
    <Subscriber Object>,
    <Subscriber Object>,
    <Subscriber Object>,
  ],
  "meta": {
    "per_page": 2,
    "page": 2,
    "total_pages": 3,
    "total_subscribers": 6
  }
}
```

{% endtab %}
{% endtabs %}

## Get a subscriber

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v2/subscribers/:identifier`

Returns a single subscriber by email address or UUID

#### Path Parameters

| Name                                         | Type   | Description                        |
| -------------------------------------------- | ------ | ---------------------------------- |
| identifier<mark style="color:red;">\*</mark> | string | Subscriber's UUID or email address |

#### Query Parameters

| Name   | Type   | Description                                                               |
| ------ | ------ | ------------------------------------------------------------------------- |
| expand | String | If you pass "campaigns" the response will include referral\_programs data |

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

```json
{
  "subscriber": <Subscriber Object>
}
```

{% endtab %}

{% tab title="404 " %}
{% tabs %}
{% tab title="Subscriber not found" %}

```
{
    "error": "Subscriber sub_4bc10562d97 not found!"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Update subscriber

<mark style="color:orange;">`PUT`</mark> `https://api.sparkloop.app/v2/subscribers/:identifier`

Update a subscriber's name, email address or status

#### Path Parameters

| Name                                         | Type   | Description                        |
| -------------------------------------------- | ------ | ---------------------------------- |
| identifier<mark style="color:red;">\*</mark> | string | Subscriber's UUID or email address |

#### Request Body

<table><thead><tr><th>Name</th><th width="60">Type</th><th>Description</th></tr></thead><tbody><tr><td>status</td><td>string</td><td>Subscriber's status. Allowed values are <em><strong>unsubscribed</strong></em> and <em><strong>confirmed</strong></em>.</td></tr><tr><td>name</td><td>string</td><td>Subscriber's name.</td></tr><tr><td>email</td><td>string</td><td>Subscriber's email address.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 Returns the subscriber." %}

```
{
    "subscriber": <Subscriber Object>
}
```

{% endtab %}

{% tab title="400 When you try setting status to something other than unsubscribed or confirmed." %}
{% tabs %}
{% tab title="Unsupported status" %}

```
{
    "error": "Invalid status!"
}
```

{% endtab %}

{% tab title="Empty PUT body" %}

```
{
    "error": "You have to update at least 1 field."
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Unsubscribe subscriber

<mark style="color:orange;">`PUT`</mark> `https://api.sparkloop.app/v2/subscribers/:identifier/unsubscribe`

Unsubscribe a subscriber

#### Path Parameters

| Name                                         | Type   | Description                        |
| -------------------------------------------- | ------ | ---------------------------------- |
| identifier<mark style="color:red;">\*</mark> | string | Subscriber's UUID or email address |

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

```
{
    "subscriber": <Subscriber Object>
}
```

{% endtab %}

{% tab title="409" %}
Subscriber is not pending

<pre><code><strong>{
</strong>    "error": "Subscriber subscriber_fsd62dr6 has already been unsubscribed"
}
</code></pre>

{% endtab %}
{% endtabs %}

## Reject subscriber

<mark style="color:orange;">`PUT`</mark> `https://api.sparkloop.app/v2/subscribers/:identifier/reject`

Reject a pending subscriber (acquired via partner program or referral program)

#### Path Parameters

| Name                                         | Type   | Description                        |
| -------------------------------------------- | ------ | ---------------------------------- |
| identifier<mark style="color:red;">\*</mark> | string | Subscriber's UUID or email address |

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

```
{
    "subscriber": <Subscriber Object>
}
```

{% endtab %}

{% tab title="409" %}
Subscriber is not pending

<pre><code><strong>{
</strong>    "error": "Subscriber subscriber_fsd62dr6 must be pending"
}
</code></pre>

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sparkloop.app/api-v2/endpoints/subscribers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.