The SimpleCirc API allows 3rd party applications to interact with subscriber and subscription data after proper authentication using an API token.
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 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.
account_id unique identifier for the object
renewal_link unique link for the subscriber to renew their subscription
login_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
company the subscriber's company
email the subscriber's email address
phone the subscriber's phone number
title the subscriber's title
address the subscriber's address
custom_fields the subscriber's custom fields
{
"subscriber": {
"account_id": "76707783",
"renewal_link": "https://simplecirc.com/renew/581675b6ff106bcd4c90ddda1064b899",
"login_link": "https://simplecirc.com/login_link/581675b6ff106bcd4c90ddda1064b899",
"name": "JOHN DOE",
"first_name": "JOHN",
"last_name": "DOE",
"company": "JOE DOE CO.",
"email": "john.doe@example.com",
"phone": "4135968655",
"title": "MR",
"address": {
"address_1": "4 EDSON DR",
"address_2": "",
"city": "WILBRAHAM",
"state": "MA",
"zipcode": "01095",
"country": "UNITED STATES"
},
"custom_fields": {
"Weight": "195",
"Height": "6'1"
}
}
}
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
custom_fields the subscriber's custom field values - custom field ids can be found on the API tab under account settings
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",
"custom_fields": {
"9998":"195",
"9999":"6'1"
}
}
Example Response
{
"subscriber": {
"account_id": "17791080",
"renewal_link": "https://simplecirc.com/renew/581675b6ff106bcd4c90ddda1064b899",
"login_link": "https://simplecirc.com/login_link/581675b6ff106bcd4c90ddda1064b899",
"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"
},
"custom_fields": {
"Weight": "195",
"Height": "6'1"
},
"subscriptions": null
}
}
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://simplecirc.com/renew/581675b6ff106bcd4c90ddda1064b899",
"login_link": "https://simplecirc.com/login_link/581675b6ff106bcd4c90ddda1064b899",
"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"
},
"custom_fields": {
"Weight": "195",
"Height": "6'1"
},
"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,
"promo_code": "SAVEBIG",
"issues_remaining": 4,
"giftgiver": {
"account_id": "84648266",
"renewal_link": "https://simplecirc.com/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"
}
}
}
]
}
}
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
phone the subscriber's phone number
title the subscriber's title
custom_fields the subscriber's custom field values - custom field ids can be found on the API tab under account settings
POST api/v1.2/subscribers/:account_id
Example Request
{
"email":"johndoe@example.com",
"custom_fields": {
"9999": "210"
}
}
Example Response
{
"subscriber": {
"account_id": "76707783",
"renewal_link": "https://simplecirc.com/renew/581675b6ff106bcd4c90ddda1064b899",
"login_link": "https://simplecirc.com/login_link/581675b6ff106bcd4c90ddda1064b899",
"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"
},
"custom_fields": {
"Weight": "210"
},
"subscriptions": [
{
"subscription_id": 1256314,
"publication_id": 764,
"publication_name": "Example Magazine",
"status": "Active",
"digital_status": "Active",
"expiration_date": "2022-04-01",
"never_expires": 0,
"qualified": 0,
"qualified_on": null,
"do_not_renew": 0,
"copies": 1,
"promo_code": "SAVEBIG",
"issues_remaining": 4,
"giftgiver": null
}
]
}
}
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://simplecirc.com/renew/581675b6ff106bcd4c90ddda1064b899",
"login_link": "https://simplecirc.com/login_link/581675b6ff106bcd4c90ddda1064b899",
"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,
"qualified": 0,
"qualified_on": null,
"do_not_renew": 0,
"copies": 1,
"promo_code": "SAVEBIG",
"issues_remaining": 4,
"giftgiver": null
}
]
},
{
"account_id": "17791080",
"renewal_link": "https://simplecirc.com/renew/581675b6ff106bcd4c90ddda1064b888",
"login_link": "https://simplecirc.com/login_link/581675b6ff106bcd4c90ddda1064b888",
"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
}
]
}
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.
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
qualified 1 if the subscription should be classified as qualified, 0 otherwise
qualified_on the date the subscription was last qualified
do_not_renew 1 if the subscription should be excluded from renewal efforts, 0 otherwise
copies the number of copies
promo_code the promo code currently associated with the subscription
issues_remaining the number of issues remaining
giftgiver object representing the person who gifted the subscription
last_order object representing the last order associated with the subscription
questions object representing the answers to the questions associated with 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,
"promo_code": "SAVEBIG",
"issues_remaining": 4,
"giftgiver": null,
"last_order": {
"order_id": 301295828,
"order_date_time": "2021-06-30 07:03:15",
"amount_due": "9.99",
"amount_paid": "9.99",
"tax": "0.00",
"issues": "4",
"copies": 1,
"never_expires": 0,
"qualified": 0,
"qualified_on": null,
"do_not_renew": 0,
"postage_type_id": 549,
"promo_code": "SAVEBIG"
},
"questions": {
"What is your favorite car?": "Audi",
"What are your favorite foods?": "Pizza, Popcorn, Steak"
}
}
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
qualified 1 if the subscription should be classified as qualified, 0 otherwise
qualified_on the date the subscription was last qualified
do_not_renew 1 if the subscription should be excluded from renewal efforts, 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
questions object representing the answers to the questions associated with the subscription - question ids can be found on the API tab under account settings
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":"",
"qualified": 0,
"qualified_on": null,
"do_not_renew": 0,
"amount_paid":9.99,
"amount_due":9.99,
"tax_amount":0.99,
"currency":"USD",
"questions": {
"9998":"Audi",
"9999":"Pizza|Popcorn|Steak",
}
}
Example Response
{
"subscriber": {
"account_id": "17791080",
"renewal_link": "https://simplecirc.com/renew/581675b6ff106bcd4c90ddda1064b899",
"login_link": "https://simplecirc.com/login_link/581675b6ff106bcd4c90ddda1064b899",
"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,
"qualified": 0,
"qualified_on": null,
"do_not_renew": 0,
"copies": 1,
"promo_code": "SAVEBIG",
"issues_remaining": 4,
"giftgiver": null,
"last_order": {
"order_id": 999999999,
"order_date_time": "2022-04-07 10:13:54",
"amount_due": "9.99",
"amount_paid": "9.99",
"tax": "0.00",
"issues": "4",
"copies": 1,
"never_expires": 0,
"postage_type_id": 9999,
"promo_code": "SAVEBIG"
},
"questions": {
"What is your favorite car?": "Audi",
"What are your favorite foods?": "Pizza, Popcorn, Steak"
}
}
]
}
}
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
qualified 1 if the subscription should be classified as qualified, 0 otherwise
qualified_on the date the subscription was last qualified
do_not_renew 1 if the subscription should be excluded from renewal efforts, 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
questions object representing the answers to the questions associated with the subscription - question ids can be found on the API tab under account settings
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":"",
"qualified": 0,
"qualified_on": null,
"do_not_renew": 0,
"amount_paid":9.99,
"amount_due":9.99,
"tax_amount":0.99,
"currency":"USD",
"questions": {
"9998":"BMW",
"9999":"Fish|Beans",
}
}
Example Response
{
"subscriber": {
"account_id": "17791080",
"renewal_link": "https://simplecirc.com/renew/581675b6ff106bcd4c90ddda1064b899",
"login_link": "https://simplecirc.com/login_link/581675b6ff106bcd4c90ddda1064b899",
"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,
"qualified": 0,
"qualified_on": null,
"do_not_renew": 0,
"copies": 1,
"promo_code": "SAVEBIG",
"issues_remaining": 8,
"giftgiver": null,
"last_order": {
"order_id": 999999999,
"order_date_time": "2022-04-07 10:13:54",
"amount_due": "9.99",
"amount_paid": "9.99",
"tax": "0.00",
"issues": "4",
"copies": 1,
"never_expires": 0,
"postage_type_id": 9999,
"promo_code": "SAVEBIG"
},
"questions": {
"What is your favorite car?": "BMW",
"What are your favorite foods?": "Fish, Beans"
}
}
]
}
}
Update values for a given subscription. You must pass the publication_id along with the account_id of the subscriber to identify the correct subscription.
status the subscription status - valid statuses include Active, Bad Address, On Hold, Expired, Cancelled, Other, Bad Debt, Deceased - status of Expired will change the issues remaining to zero
issues_remaining the number of issues remaining for the subscription - must be an integer greater than or equal to zero, zero issues remaining will change the status to Expired
POST api/v1.2/subscribers/:account_id/subscriptions/:publication_id
Example Request
{
"status":"Cancelled"
}
Example Response
{
"subscriber": {
"account_id": "17791080",
"renewal_link": "https://simplecirc.com/renew/581675b6ff106bcd4c90ddda1064b899",
"login_link": "https://simplecirc.com/login_link/581675b6ff106bcd4c90ddda1064b899",
"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": "Cancelled",
"digital_status": "Cancelled",
"expiration_date": "2022-04-01",
"never_expires": 0,
"qualified": 0,
"qualified_on": null,
"do_not_renew": 0,
"copies": 1,
"issues_remaining": 8,
"giftgiver": null
}
]
}
}
Each subscriber has a mailing address. The API allows you to create and update the mailing address.
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"
}
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://simplecirc.com/renew/581675b6ff106bcd4c90ddda1064b899",
"login_link": "https://simplecirc.com/login_link/581675b6ff106bcd4c90ddda1064b899",
"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"
}
}
}
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 |