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)

201: Created

{
    "subscriber": {
        "uuid": "sub_37775e51c5",
        "email": "[email protected]",
        "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"
    }
}

400

Email taken

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

Email invalid

{
    "error": "Email is invalid"
}

Email not provided

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

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

200 Used query params ?page=2&per_page=3

{
    "subscribers": [
        {
            "uuid": "sub_4bc1056297",
            "email": "[email protected]",
            "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": "[email protected]",
            "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": "[email protected]",
            "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
    }
}

404 Could not find the campaign.

{ "error": "Campaign MF9a7d8983d1c not found!"}

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

200

{
    "subscriber": {
        "uuid": "sub_4bc1056297",
        "email": "[email protected]",
        "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"
    }
}

404

Subscriber not found

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

Campaign not found

{
    "error": "Campaign MF9a7d8983d1c not found!"
}

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

200 Used query params ?page=2&per_page=3

{
    "subscribers": [
        {
            "uuid": "sub_4bc1056297",
            "email": "[email protected]",
            "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": "[email protected]",
            "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": "[email protected]",
            "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
    }
}

404 Could not find the campaign.

{ "error": "Campaign MF9a7d8983d1c not found!"}

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.

200 Returns the subscriber.

{
    "subscriber": {
        "uuid": "sub_4da34775cc",
        "email": "[email protected]",
        "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"
    }
}

400 When you try setting status to something other than unsubscribed or confirmed.

Unsupported status

{
    "error": "Invalid status!"
}

Empty PUT body

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

404

Subscriber not found

{
    "error": "Subscriber sub_34c8e39ca4 not found!"
}

Campaign not found

{
    "error": "Campaign MF9a7d8983d1c not found!"
}