# Subscribers ## Create a subscriber `POST` `https://api.sparkloop.app/v1/campaigns/:campaign_uuid/subscribers` #### Path Parameters | Name | Type | Description | | ------------------------------------------------ | ------ | ----------------------------------------- | | campaign\_uuid\* | string | Campaign's UUID, for example MF9a78983d1c | #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ------------ | | X-Api-Key\* | string | Your API key | #### 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)

| {% tabs %} {% tab title="201: Created " %} ``` { "subscriber": { "uuid": "sub_37775e51c5", "email": "drago.vrago@gmail.com", "name": "Drago Vrago", "ref_code": "drago785f", "referrer_code": "joanne123c", "referrals_count": 0, "ip_address": "213.19.137.18", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.182 Safari/537.36", "origin": "api", "utm_source": null, "utm_campaign": null, "created_at": "2021-03-14T10:34:56.000Z" } } ``` {% 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/v1/campaigns/:campaign_uuid/subscribers` Subscribers are ordered descendingly by *created\_at*, meaning the first page shows the latest subscribers. #### Path Parameters | Name | Type | Description | | ------------------------------------------------ | ------ | ----------------------------------------- | | campaign\_uuid\* | string | Campaign's UUID, for example MF9a78983d1c | #### Query Parameters | Name | Type | Description | | --------- | ------- | ------------------------------------------------------------------------------------------------------ | | type | string | Type of subscribers you want to get. Default is *all*, allowed values are *all, referrals, advocates.* | | per\_page | integer | Number of subscribers returned in a single request. Default is 50, max is 200 | | page | integer | The page you want to get. Default is 1 | #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | X-Api-Key\* | string | API key | {% tabs %} {% tab title="200 Used query params ?page=2\&per\_page=3" %} ``` { "subscribers": [ { "uuid": "sub_4bc1056297", "email": "test36@drago.com", "name": null, "ref_code": "c784ef4f", "referrer_code": null, "referrals_count": 0, "referred": true, "referral_status": "verified", "ip_address": null, "user_agent": null, "origin": "signup", "utm_source": null, "utm_campaign": null, "created_at": "2021-03-24T11:55:02.113Z" }, { "uuid": "sub_869976268c", "email": "test35@drago.com", "name": null, "ref_code": "d163ac6e", "referrer_code": null, "referrals_count": 0, "referred": false, "referral_status": "verified", "ip_address": null, "user_agent": null, "origin": "signup", "utm_source": null, "utm_campaign": null, "created_at": "2021-03-24T11:55:02.096Z" }, { "uuid": "sub_d4795d06e6", "email": "test34@drago.com", "name": null, "ref_code": "57b1fae2", "referrer_code": null, "referrals_count": 0, "referred": false, "referral_status": "verified", "ip_address": null, "user_agent": null, "origin": "api", "utm_source": null, "utm_campaign": null, "created_at": "2021-03-24T11:55:02.066Z" } ], "meta": { "per_page": 3, "page": 2, "total_pages": 12, "total_subscribers": 36 } } ``` {% endtab %} {% tab title="404 Could not find the campaign." %} ``` { "error": "Campaign MF9a7d8983d1c not found!"} ``` {% endtab %} {% endtabs %} ## Get a subscriber `GET` `https://api.sparkloop.app/v1/campaigns/:campaign_uuid/subscribers/:uuid` Returns a single subscriber by email address or UUID #### Path Parameters | Name | Type | Description | | ------------------------------------------------ | ------ | ----------------------------------------- | | uuid\* | string | Subscriber's UUID or email address | | campaign\_uuid\* | string | Campaign's UUID, for example MF9a78983d1c | #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ------------ | | X-Api-Key\* | string | Your API key | {% tabs %} {% tab title="200 " %} ``` { "subscriber": { "uuid": "sub_4bc1056297", "email": "test36@drago.com", "name": null, "ref_code": "c784ef4f", "referrer_code": null, "referrals_count": 0, "referred": true, "referral_status": "verified", "ip_address": null, "user_agent": null, "origin": "signup", "utm_source": null, "utm_campaign": null, "created_at": "2021-03-24T11:55:02.113Z" } } ``` {% endtab %} {% tab title="404 " %} {% tabs %} {% tab title="Subscriber not found" %} ``` { "error": "Subscriber sub_4bc10562d97 not found!" } ``` {% endtab %} {% tab title="Campaign not found" %} ``` { "error": "Campaign MF9a7d8983d1c not found!" } ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ## Get referrals for a subscriber `GET` `https://api.sparkloop.app/v1/campaigns/:campaign_uuid/subscribers/:uuid/referrals` Get the referrals of a specific subscriber. Subscribers are ordered descendingly by *created\_at*, meaning the first page shows the latest subscribers. #### Path Parameters | Name | Type | Description | | ------------------------------------------------ | ------ | ----------------------------------------- | | campaign\_uuid\* | string | Campaign's UUID, for example MF9a78983d1c | | uuid\* | String | Subscriber's UUID or email address | #### Query Parameters | Name | Type | Description | | --------- | ------- | ----------------------------------------------------------------------------- | | per\_page | integer | Number of subscribers returned in a single request. Default is 50, max is 200 | | page | integer | The page you want to get. Default is 1 | #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | X-Api-Key\* | string | API key | {% tabs %} {% tab title="200 Used query params ?page=2\&per\_page=3" %} ``` { "subscribers": [ { "uuid": "sub_4bc1056297", "email": "test36@drago.com", "name": null, "ref_code": "c784ef4f", "referrer_code": null, "referrals_count": 0, "referred": true, "referral_status": "verified", "ip_address": null, "user_agent": null, "origin": "signup", "utm_source": null, "utm_campaign": null, "created_at": "2021-03-24T11:55:02.113Z" }, { "uuid": "sub_869976268c", "email": "test35@drago.com", "name": null, "ref_code": "d163ac6e", "referrer_code": null, "referrals_count": 0, "referred": true, "referral_status": "pending", "ip_address": null, "user_agent": null, "origin": "signup", "utm_source": null, "utm_campaign": null, "created_at": "2021-03-24T11:55:02.096Z" }, { "uuid": "sub_d4795d06e6", "email": "test34@drago.com", "name": null, "ref_code": "57b1fae2", "referrer_code": null, "referrals_count": 0, "referred": true, "referral_status": "rejected", "ip_address": null, "user_agent": null, "origin": "api", "utm_source": null, "utm_campaign": null, "created_at": "2021-03-24T11:55:02.066Z" } ], "meta": { "per_page": 3, "page": 2, "total_pages": 12, "total_subscribers": 36 } } ``` {% endtab %} {% tab title="404 Could not find the campaign." %} ``` { "error": "Campaign MF9a7d8983d1c not found!"} ``` {% endtab %} {% endtabs %} ## Update subscriber `PUT` `https://api.sparkloop.app/v1/campaigns/:campaign_uuid/subscribers/:uuid` Update a subscriber's name, email address or status #### Path Parameters | Name | Type | Description | | ------------------------------------------------ | ------ | ---------------------------------- | | uuid\* | string | Subscriber's UUID or email address | | campaign\_uuid\* | string | Campaign's UUID | #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ------------ | | X-Api-Key\* | string | Your API key | #### 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": { "uuid": "sub_4da34775cc", "email": "drago.vrago@gmail.com", "name": "Drago Vrago", "ref_code": "drago359e", "referrer_code": null, "referrals_count": 0, "ip_address": "12345676543234565432", "user_agent": null, "origin": "api", "utm_source": null, "utm_campaign": null, "created_at": "1993-08-30T10:34:56.000Z" } } ``` {% 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 %} {% tab title="404 " %} {% tabs %} {% tab title="Subscriber not found" %} ``` { "error": "Subscriber sub_34c8e39ca4 not found!" } ``` {% endtab %} {% tab title="Campaign not found" %} ``` { "error": "Campaign MF9a7d8983d1c not found!" } ``` {% endtab %} {% endtabs %} {% 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-1/subscribers.md?ask= ``` 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.