API v1.2


Introduction

The SimpleCirc API allows 3rd party applications to interact with subscriber and subscription data after proper authentication using an API token.


Authentication

The SimpleCirc API uses Basic Authentication. The username is “Bearer” and the password is your API Token. Your API Token can be found on the API tab under your Account Settings. The API tab is visible only to the primary account holder.


Subscribers

Subscribers are the people who have subscriptions. The API allows you to create and update your subscribers. You can retrieve individual subscribers as well as a list of all your subscribers.


The subscriber object

account_id unique identifier for the object

renewal_link unique link for the subscriber to log into their account

name the subscriber's full name

first_name the subscriber's first name

last_name the subscriber's last name

email the subscriber's email address

company the subscriber's company

{
    "subscriber": {
        "account_id": "76707783",
        "renewal_link": "https://beta.simplecirc.com/subscriber_renew/581675b6ff106bcd4c90ddda1064b86f",
        "name": "JOHN DOE",
        "first_name": "JOHN",
        "last_name": "DOE",
        "email": "john.doe@example.com",
        "company": "JOE DOE CO.",
    }
}


Create a subscriber

Creates a new subscriber.

name the subscriber's full name

email the subscriber's email address

company the subscriber's company

address_1 the subscriber's mailing address line 1

address_2 the subscriber's mailing address line 2

city the subscriber's mailing address city

state the subscriber's mailing address state

zipcode the subscriber's mailing address zipcode

country the subscriber's mailing address country

POST api/v1.2/subscribers

Example Request

{
	"name":"Jane Doe",
	"email":"jane.doe@example.com",
	"company":"Jane Co.",
	"address_1":"2 Edson Drive",
	"address_2":"Apt 4",
	"city":"Wilbraham",
	"state":"MA",
	"zipcode":"01095",
	"country":"United States"
}

Example Response

{
    "subscriber": {
        "account_id": "17791080",
        "renewal_link": "https://beta.simplecirc.com/subscriber_renew/d17718feb947953b9d812f194531b178",
        "name": "JANE DOE",
        "first_name": "JANE",
        "last_name": "DOE",
        "email": "jane.doe@example.com",
        "company": "JANE CO.",
        "address": {
            "address_1": "2 EDSON DR",
            "address_2": "APT 4",
            "city": "WILBRAHAM",
            "state": "MA",
            "zipcode": "01095-2327",
            "country": "UNITED STATES"
        },
        "subscriptions": null
    }
}


Retrieve a subscriber

Retrieves the details of an existing subscriber. You need only supply the unique account_id for the subscriber.

GET api/v1.2/subscribers/:account_id

Example Response

{
    "subscriber": {
        "account_id": "76707783",
        "renewal_link": "https://beta.simplecirc.com/subscriber_renew/581675b6ff106bcd4c90ddda1064b86f",
        "name": "JOHN DOE",
        "first_name": "JOHN",
        "last_name": "DOE",
        "email": "john.doe@example.com",
        "company": "JOE DOE CO.",
        "address": {
            "address_1": "16 EASTVIEW TER",
            "address_2": "",
            "city": "PITTSFORD",
            "state": "NY",
            "zipcode": "14534-2008",
            "country": "UNITED STATES"
        },
        "subscriptions": [
            {
                "subscription_id": 1256314,
                "publication_id": 764,
                "publication_name": "Example Magazine",
                "status": "Active",
                "digital_status": "Active",
                "expiration_date": "2022-04-01",
                "never_expires": 0,
                "copies": 1,
                "issues_remaining": 4,
                "giftgiver": {
                    "account_id": "84648266",
                    "renewal_link": "https://beta.simplecirc.com/subscriber_renew/1d645c5f82b66c0b691f811cd4ca116e",
                    "name": "GARY GIVES",
                    "first_name": "GARY",
                    "last_name": "GIVES",
                    "email": "",
                    "company": "",
                    "address": {
                        "address_1": "17 SEA PINE RD",
                        "address_2": "",
                        "city": "WELLFLEET",
                        "state": "MA",
                        "zipcode": "02667",
                        "country": "UNITED STATES"
                    }
                }
            }
        ]
    }
}


Update a subscriber

Updates an existing subscriber by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

name the subscriber's full name

email the subscriber's email address

company the subscriber's company

POST api/v1.2/subscribers/:account_id

Example Request

{
	"email":"johndoe@example.com"
}

Example Response

{
    "subscriber": {
        "account_id": "76707783",
        "renewal_link": "https://beta.simplecirc.com/subscriber_renew/581675b6ff106bcd4c90ddda1064b86f",
        "name": "JOHN DOE",
        "first_name": "JOHN",
        "last_name": "DOE",
        "email": "johndoe@example.com",
        "company": "JOE DOE CO.",
        "address": {
            "address_1": "16 EASTVIEW TER",
            "address_2": "",
            "city": "PITTSFORD",
            "state": "NY",
            "zipcode": "14534-2008",
            "country": "UNITED STATES"
        },
        "subscriptions": [
            {
                "subscription_id": 1256314,
                "publication_id": 764,
                "publication_name": "Example Magazine",
                "status": "Active",
                "digital_status": "Active",
                "expiration_date": "2022-04-01",
                "never_expires": 0,
                "copies": 1,
                "issues_remaining": 4,
                "giftgiver": null
            }
        ]
    }
}


List all subscribers

Returns a list of your subscribers.

limit A limit on the number of subscribers returned. The limit can range between 1 and 100. The default is 10.

email A filter on the list based on the subscriber's email address.

starting_after A cursor for use in pagination. starting_after is a account id representing a subscriber. For example, if you requested 10 subscribers and you want the next 10, pass the account_id of the last subscriber in your previous request as the starting_after value.

GET api/v1.2/subscribers?limit=3

Example Response

{
    "subscribers": [
        {
            "account_id": "76707783",
            "renewal_link": "https://beta.simplecirc.com/subscriber_renew/581675b6ff106bcd4c90ddda1064b86f",
            "name": "JOHN DOE",
            "first_name": "JOHN",
            "last_name": "DOE",
            "email": "johndoe@example.com",
            "company": "JOE DOE CO.",
            "address": {
                "address_1": "16 EASTVIEW TER",
                "address_2": "",
                "city": "PITTSFORD",
                "state": "NY",
                "zipcode": "14534-2008",
                "country": "UNITED STATES"
            },
            "subscriptions": [
                {
                    "subscription_id": 1256314,
                    "publication_id": 764,
                    "publication_name": "Example Magazine",
                    "status": "Active",
                    "digital_status": "Active",
                    "expiration_date": "2022-04-01",
                    "never_expires": 0,
                    "copies": 1,
                    "issues_remaining": 4,
                    "giftgiver": null
                }
            ]
        },
        {
            "account_id": "17791080",
            "renewal_link": "https://beta.simplecirc.com/subscriber_renew/d17718feb947953b9d812f194531b178",
            "name": "JANE DOE",
            "first_name": "JANE",
            "last_name": "DOE",
            "email": "jane.doe@example.com",
            "company": "JANE CO.",
            "address": {
                "address_1": "2 EDSON DR",
                "address_2": "APT 4",
                "city": "WILBRAHAM",
                "state": "MA",
                "zipcode": "01095-2327",
                "country": "UNITED STATES"
            },
            "subscriptions": null
        }
    ]
}


Subscriptions

Subscribers can have one or more subscriptions. Each subscription is to a single publication. The API allows you to create and renew subscriptions for subscribers. To retrieve a subscription you must retrieve the subscriber and then inspect the subscribers subscriptions.


The subscription object

subscription_id unique identifier for the object

publication_id identifies the publication that the subscription is for, publication_id can be found on the API tab under account settings

publication_name the name of the publication

status the status of the subscription (Active, Expired, On Hold, Cancelled, Bad Debt, Bad Address, Other)

digital_status the status of the subscription as it relates to online access to a publication, this status will remain active while the subscription's last issue is still equal to the last issue published

expiration_date the date the subscription expires or expired, if a subscription is active you should get a valid expiration_date, in the future, in the format of YYYY-MM-DD. The one exception to this is if the subscription "never expires". In this case the expiration_date will be blank and never_expires will be 1. If a subscription has expired and we know when they got their last issue then the expiration_date will be populated. If we don't have that information then the status will be expired but the expiration_date will be blank.

never_expires 1 if the subscription never expires, 0 otherwise

copies the number of copies

issues_remaining the number of issues remaining

giftgiver object representing the person who gifted the subscription

{
    "subscription_id": 1256314,
    "publication_id": 764,
    "publication_name": "Example Magazine",
    "status": "Active",
    "digital_status": "Active",
    "expiration_date": "2021-04-01",
    "never_expires": 0,
    "copies": 1,
    "issues_remaining": 4,
    "giftgiver": null
}


Create a subscrption

Creates a new subscription for the given subscriber. If a subscription already exists for the given subscriber and publication that subscription will be renewed.

publication_id identifies the publication the subscription should be for, publication ids can be found on the API tab under account settings

issues_purchased the number of issues the subscriber is getting

copies the number of copies

postage_id identifies the type of postage, postage ids can be found on the API tab under account settings

promo_code promo code to be associated with the purchase

giftgiver_account_id account_id of an existing subscriber if given as a gift

never_expires 1 if the subscription should never expire, 0 otherwise

amount_paid the amount paid

amount_due the price of the purchase

tax_amount the amount of tax paid

currency the currency the purchase was denominated in

POST api/v1.2/subscribers/:account_id/subscriptions

Example Request

{
	"publication_id":"764",
	"issues_purchased":"4",
	"copies":"1",
	"postage_id":"441",
	"promo_code":"SAVEBIG",
	"giftgiver_account_id":"",
	"never_expires":"",
	"amount_paid":9.99,
	"amount_due":9.99,
	"tax_amount":0.99,
	"currency":"USD"	
}

Example Response

{
    "subscriber": {
        "account_id": "17791080",
        "renewal_link": "https://beta.simplecirc.com/subscriber_renew/d17718feb947953b9d812f194531b178",
        "name": "JANE DOE",
        "first_name": "JANE",
        "last_name": "DOE",
        "email": "jane.doe@example.com",
        "company": "JANE CO.",
        "address": {
            "address_1": "2 EDSON DR",
            "address_2": "APT 4",
            "city": "WILBRAHAM",
            "state": "MA",
            "zipcode": "01095-2327",
            "country": "UNITED STATES"
        },
        "subscriptions": [
            {
                "subscription_id": 1256315,
                "publication_id": 764,
                "publication_name": "Example Magazine",
                "status": "Active",
                "digital_status": "Active",
                "expiration_date": "2022-04-01",
                "never_expires": 0,
                "copies": 1,
                "issues_remaining": 4,
                "giftgiver": null
            }
        ]
    }
}


Renew a subscription

Adds issues to the given subscription as indicated by subscriber and publication. If a subscription to the given publication does not exist for the given subscriber a new subscription will be created.

publication_id identifies the publication the subscription should be for, publication ids can be found on the API tab under account settings

issues_purchased the number of issues the subscriber is getting

copies the number of copies

postage_id identifies the type of postage, postage ids can be found on the API tab under account settings

promo_code promo code to be associated with the purchase

giftgiver_account_id account_id of an existing subscriber if given as a gift

never_expires 1 if the subscription should never expire, 0 otherwise

amount_paid the amount paid

amount_due the price of the purchase

tax_amount the amount of tax paid

currency the currency the purchase was denominated in

POST api/v1.2/subscribers/:account_id/subscriptions

Example Request

{
	"publication_id":"764",
	"issues_purchased":"4",
	"copies":"1",
	"postage_id":"441",
	"promo_code":"SAVEBIG",
	"giftgiver_account_id":"",
	"never_expires":"",
	"amount_paid":9.99,
	"amount_due":9.99,
	"tax_amount":0.99,
	"currency":"USD"	
}

Example Response

{
    "subscriber": {
        "account_id": "17791080",
        "renewal_link": "https://beta.simplecirc.com/subscriber_renew/d17718feb947953b9d812f194531b178",
        "name": "JANE DOE",
        "first_name": "JANE",
        "last_name": "DOE",
        "email": "jane.doe@example.com",
        "company": "JANE CO.",
        "address": {
            "address_1": "2 EDSON DR",
            "address_2": "APT 4",
            "city": "WILBRAHAM",
            "state": "MA",
            "zipcode": "01095-2327",
            "country": "UNITED STATES"
        },
        "subscriptions": [
            {
                "subscription_id": 1256315,
                "publication_id": 764,
                "publication_name": "Example Magazine",
                "status": "Active",
                "digital_status": "Active",
                "expiration_date": "2022-04-01",
                "never_expires": 0,
                "copies": 1,
                "issues_remaining": 8,
                "giftgiver": null
            }
        ]
    }
}


Addresses

Each subscriber has a mailing address. The API allows you to create and update the mailing address.


The address object

address_1 the subscriber's mailing address line 1

address_2 the subscriber's mailing address line 2

city the subscriber's mailing address city

state the subscriber's mailing address state

zipcode the subscriber's mailing address zipcode

country the subscriber's mailing address country

{
	"address_1": "1123 FRICK LN",
	"address_2": "APT 4",
	"city": "PITTSBURGH",
	"state": "PA",
	"zipcode": "15217-2576",
	"country": "UNITED STATES"
}


Create/update an address

Creates a new address for the given subscriber or updates the subscribers address if they already have one.

address_1 the subscriber's mailing address line 1

address_2 the subscriber's mailing address line 2

city the subscriber's mailing address city

state the subscriber's mailing address state

zipcode the subscriber's mailing address zipcode

country the subscriber's mailing address country

POST api/v1.2/subscribers/:account_id/addresses

Example Request

{
	"address_1":"1123 Frick Ln",
	"address_2":"APT 4",
	"city":"Pittsburgh",
	"state":"PA",
	"zipcode":"15217",
	"country":"United States"
}

Example Response

{
    "subscriber": {
        "account_id": "79766940",
        "renewal_link": "https://beta.simplecirc.com/subscriber_renew/eccf7ddd4a53d11aad906b4572f23b45",
        "name": "RON JOHNSON",
        "first_name": "RON",
        "last_name": "JOHNSON",
        "email": "",
        "company": "",
        "address": {
            "address_1": "1123 FRICK LN",
            "address_2": "APT 4",
            "city": "PITTSBURGH",
            "state": "PA",
            "zipcode": "15217-2576",
            "country": "UNITED STATES"
        }
    }
}


Testing

To make test requests to our production API please use the following test account api_token:

Gq0LcmyRFh2zMWByimoNJzluVd7fbX8PJMQh27vYnAOYCrNNJrMkvV9kT1Zs

Below are test accounts for the test API token given above. These accounts include 2 actives, 2 expireds with expiration dates, 1 expired with unknown (blank) expiration date, and 1 active that never expires.

You can also use the test API token to create new subscribers and subscriptions.

The publication_id for the test account is 205.

The postage_ids for the test account are 13810 and 13811.

Name Account ID Expiration Date Notes
Ron Jones 66131093 2018-12-01 active
Tim Thompson 19335023 expiration date unknown
Erica Willis 05925013 2019-02-01 active
Freddy Freetown 69135217 never expires
Zeke Anderson 63003506 2017-11-01 expired
Sally Smith 29995624 2017-07-01 expired