# Subscribers
## Create a subscriber
`POST` `https://api.sparkloop.app/v2/subscribers`
#### Request Body
| Name | Type | Description |
| --------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| email\* | 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 | Timestamp when subscriber signed up. You can set this value to a date in the past.
Expected format:
YYYY-MM-DDThh:mm:ssTZD
e.g. 2021-03-22T19:20:30+01:00
Where:
YYYY = four-digit year
MM = two-digit month (01=January, etc.)
DD = two-digit day of month (01 through 31)
hh = two digits of hour (00 through 23)
mm = two digits of minute (00 through 59)
ss = two digits of second (00 through 59)
s = one or more digits representing a decimal fraction of a second
TZD = time zone designator (Z or +hh:mm or -hh:mm)
|
| country\_code | string | Alpha-2 ountry code of the subscriber |
{% tabs %}
{% tab title="201: Created " %}
```
{
"subscriber":
}
```
{% 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
`GET` `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": [
,
,
,
],
"meta": {
"per_page": 2,
"page": 2,
"total_pages": 3,
"total_subscribers": 6
}
}
```
{% endtab %}
{% endtabs %}
## Get a subscriber
`GET` `https://api.sparkloop.app/v2/subscribers/:identifier`
Returns a single subscriber by email address or UUID
#### Path Parameters
| Name | Type | Description |
| -------------------------------------------- | ------ | ---------------------------------- |
| identifier\* | 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":
}
```
{% endtab %}
{% tab title="404 " %}
{% tabs %}
{% tab title="Subscriber not found" %}
```
{
"error": "Subscriber sub_4bc10562d97 not found!"
}
```
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}
## Update subscriber
`PUT` `https://api.sparkloop.app/v2/subscribers/:identifier`
Update a subscriber's name, email address or status
#### Path Parameters
| Name | Type | Description |
| -------------------------------------------- | ------ | ---------------------------------- |
| identifier\* | string | Subscriber's UUID or email address |
#### Request Body
| Name | Type | Description |
|---|
| status | string | Subscriber's status. Allowed values are unsubscribed and confirmed. |
| name | string | Subscriber's name. |
| email | string | Subscriber's email address. |
{% tabs %}
{% tab title="200 Returns the subscriber." %}
```
{
"subscriber":
}
```
{% 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
`PUT` `https://api.sparkloop.app/v2/subscribers/:identifier/unsubscribe`
Unsubscribe a subscriber
#### Path Parameters
| Name | Type | Description |
| -------------------------------------------- | ------ | ---------------------------------- |
| identifier\* | string | Subscriber's UUID or email address |
{% tabs %}
{% tab title="200" %}
```
{
"subscriber":
}
```
{% endtab %}
{% tab title="409" %}
Subscriber is not pending
{
"error": "Subscriber subscriber_fsd62dr6 has already been unsubscribed"
}
{% endtab %}
{% endtabs %}
## Reject subscriber
`PUT` `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\* | string | Subscriber's UUID or email address |
{% tabs %}
{% tab title="200" %}
```
{
"subscriber":
}
```
{% endtab %}
{% tab title="409" %}
Subscriber is not pending
{
"error": "Subscriber subscriber_fsd62dr6 must be pending"
}
{% endtab %}
{% endtabs %}