Customer Accounts

These resources handle everything about the customer:

GET /account

List all details pertaining to the current customer

Request

No parameters required (besides your API key of course).

Responses

Success: Logged in with an active subscription and affiliate codes

{
    "status": "ok",
    "customer": {
        "id": 1,
        "first_name": "Naveen",
        "last_name": "Jain",
        "email": "temp123@sparkart.com",
        "new_email": null,
        "birthdate": "1987-09-03",
        "age": 26,
        "username": "Fighter123", // Only included if the fanclub supports it. Otherwise this key will not exist
        "fanclub_id": 2,
        "expired": false, // True if the customer has no active subscription
        "trial_membership": false, // True if active subscription is a trial subscription
        "at_renewal_cap": false, // True if the customer is locked into a plan and at the cap
        "auto_renewal_enabled": false, // True if the customer has opted-in to auto renewal
        "lists_opt_in": true, // True if the customer has opted-in to receive email marketing messages
        "email_aliases": [
            "temp123@sparkart.com",
            "tempupdate@sparkart.com"
        ],
        "invalid_email_message": "Please update and confirm your email to continue receiving important notifications from us.", // Only if customer has an invalid email, otherwise null
        "authentications": [ // Customer has enable facebook and twitter login. Otherwise this key will be an empty array
            {
                "name": "facebook"
            },
            {
                "name": "twitter"
            }
        ],
        "subscription": { // This key will not exist if current customer has no active subscription
            "plan": {
                "id": 3,
                "name": "Another Plan",
                "class": "another-plan",
                "description": "<p>Plan description or else null</p>",
                "online_benefits": "<p>Plan online benefits or else null</p>",
                "annotations": "<p>Plan annotations or else null</p>",
                "tags": ["presales"]
            },
            "start_date": "2013-01-29T23:39:59Z",
            "end_date": "2014-01-29T23:39:59Z",  // Calculated via plan duration.  Subscription may remain active due to sales period extension
            "lapsed": false,  // True if subscription would have expired, but sales period extension is keeping it active
            "trial_membership": false, // True if subscription is a trial
            "affiliates": [
                {
                    "id": 1,
                    "name": "UFC Presales",
                    "codes": [
                        "test-code-1",
                        "test-code-2"
                    ]
                },
                {
                    "id": 2,
                    "name": "UFC.tv PPV",
                    "codes": [
                        "ppv-test-code"
                    ]
                }
            ]
        }
    }
}

Success: Unregistered customer after purchase of free plan

Creates a new customer with registered = false

{
    "status": "ok",
    "customer": {
        "id": null,
        "first_name": null,
        "last_name": null,
        "email": null,
        "new_email": null,
        "birthdate": null,
        "age": null,
        "fanclub_id": null,
        "expired": false,
        "trial_membership": false,
        "at_renewal_cap": false,
        "lists_opt_in": false,
        "email_aliases": [],
        "invalid_email_message": null,
        "authentications": []
    }
}

Failure: Current customer not found

{
    "status": "ok",
    "customer": null
}

GET /account/status

Checks the customer's cookie and determines if they are logged in or not. Endpoint does as little processing as possible and does not verify that the customer's cookie is valid just that one exists. Used to short-circuit processing and display of logged in modules when customers are currently logged out.

Request

No parameters required

Responses

Success: Customer logged in

{
    "status": "ok",
    "logged_in": true
}

Failure: Customer not logged in

{
    "status": "ok",
    "logged_in": false
}

POST /accounts

Creates a new customer account

Request

Name Type Description
email string [Required] Customer's email
first_name string [Optional] Customer's first name
last_name string [Optional] Customer's last name
birthdate string [Required] Customer's date of birth
Format: YYYY-MM-DD
username string [Required] Customer's username
Only required if fanclub supports Vanilla Forums
accept_terms boolean [Optional] Whether or not the customer has accepted the Terms of Service
password_attributes object [Optional] Used to create a password for the customer
Format: {"password": "temp123", "password_confirmation": "temp123"}
{
    "email": "rwar1@haha.com",
    "first_name": "joe",
    "last_name": "jackson",
    "birthdate": "1995-05-01",
    "username": "shoelessJoe",
    "accept_terms": true,
    "password_attributes": {
        "password": "temp123",
        "password_confirmation": "temp123"
    }
}

Responses

Success: Created a new registered customer

{
    "status": "ok",
    "customer": {
        "id": 55,
        "first_name": "joe",
        "last_name": "jackson",
        "email": "rwar1@haha.com",
        "new_email": null,
        "birthdate": "1995-05-01",
        "age": 19,
        "fanclub_id": 73,
        "expired": false,
        "trial_membership": false,
        "at_renewal_cap": false,
        "email_aliases": [
            "rwar1@haha.com",
            "tempupdate@sparkart.com"
        ],
        "invalid_email_message": null,
        "authentications": []
    }
}

Failure: Trying to create a customer with invalid information

{
    "status": "error",
    "messages": [
        "Birthdate can't be blank",
        "Email has already been taken",
        "Password can't be blank",
    ]
}
Failure: Missing customer parameter
{
    "status": "error",
    "messages": [
        "Customer parameter is required."
    ]
}

POST /account

Updates current customer's account information

Request

Name Type Description
email string [Optional] Customer's new email
first_name string [Optional] Customer's new first name
last_name string [Optional] Customer's new last name
username string [Optional] Customer's new username
Only if fanclub supports Vanilla Forums
current_password string [Optional] Customer's current password
Only required if customer is changing their password
password string [Optional] Customer's new password
password_confirmation string [Optional] Confirmation for customer's new password
lists_opt_in string [Optional] Customer email marketing preference. "True" enables opt-in. "False" disables opt-in. Any other value leaves the current preference intact
lists_opt_in_source string [Optional] Customer email marketing source (example: "Giveaway Campaign")
{
    "email": "random@sparkart.com",
    "first_name": "Bobby",
    "last_name": "Ricky",
    "username": "slice-and-dice",
    "current_password": 'temp123',
    "password": "asdf123",
    "password_confirmation": "asdf123"
}

Responses

Success: Updated customer's email, names, and password

{
    "status": "ok",
    "customer": {
        "id": 55,
        "first_name": "Bobby",
        "last_name": "Ricky",
        "email": "random@sparkart.com",
        "new_email": null,
        "birthdate": "1995-05-01",
        "age": 19,
        "username": "slice-and-dice",
        "fanclub_id": 12,
        "expired": false,
        "trial_membership": false,
        "at_renewal_cap": false,
        "email_aliases": [
            "random@sparkart.com",
            "tempupdate@sparkart.com"
        ],
        "invalid_email_message": null,
        "authentications": []
    }
}

Failure: Invalid email and password

{
    "status": "error",
    "messages": [
        "Email has already been taken",
        "Current password is incorrect"
    ]
}

GET /account/benefits

This endpoint returns the benefits associated with the current users active subscription.

Request

No parameters required (besides your API key of course).

Responses

Success: Returns benefits associated with active subscription

{
    "status":"ok",
    "benefits":[
        {
            "id":8,
            "summary":"Benefit Summary 1",
            "details":null,
            "benefit_type":"online",
            "image_url":null
        }
    ]
}

Success: Returns no benefits for a customer without an active subscription

{
    "status":"ok",
    "benefits":[]
}

POST /login

Customers can login with their emails and passwords

This is identical to the Facebook login endpoint with the exception of the request parameters.

Request

Name Type Description
email string [Required] Customer's email
password string [Required] Customer's password
{
  "email": "test@sparkart.com",
  "password": "temp123"
}

Responses

Success: Email and password combination verified

{
    "status": "ok",
    "customer": {
        "id": 2,
        "first_name": "Test",
        "last_name": "Robot",
        "email": "test@example.com",
        "new_email": null,
        "birthdate": "1995-01-30",
        "age": 19,
        "fanclub_id": 1,
        "registered": true,
        "expired": false,
        "trial_membership": false,
        "at_renewal_cap": false,
        "email_aliases": [
            "test@example.com",
            "tempupdate@sparkart.com"
        ],
        "invalid_email_message": null,
        "authentications": [],
        "subscription": {
            "plan": {
                "id": 1,
                "name": "The Free Plan",
                "class": "the-free-plan",
                "description": null,
                "online_benefits": null,
                "annotations": null,
                "tags": []
            },
            "start_date": "2013-01-30T03:56:34Z",,
            "end_date": null,
            "lapsed": false,
            "trial_membership": false,
            "affiliates": []
        }
    }
}

Failure: Customer blacklisted

{
    "status": "error",
    "messages": [
        "Unable to login. Please contact support@sparkart.com for assistance."
    ]
}

Failure: Email cannot be found or email/password combination incorrect

{
    "status": "error",
    "messages": [
        "Email and password combination is incorrect."
    ]
}

Failure: Unregistered account

{
    "status": "error",
    "messages": [
        "Your email address has an unregistered account associated with it. Please contact support for assistance."
    ]
}

Failure: Unconfirmed account

{
    "status": "error",
    "messages": [
        "Your email address has not been confirmed. Please click on the link from your confirmation email or contact support for assistance."
    ]
}

Failure: Facebook login invalid signature

{
    "status": "error",
    "messages": [
        "Invalid request: Format. Please try logging into Facebook again."
    ]
}

Failure: Facebook login lack of access

{
    "status": "error",
    "messages": [
        "Sorry, your Facebook account does not have access to this website."
    ]
}

GET /logout

Customers can log out

Request

No parameters required (besides your API key of course).

Responses

Success: Logged Out

{
    "status": "ok"
}

GET /search?email={email}

This endpoint is available to 3rd-parties to search for customer information.

Please note that two different API keys are required to access information from this endpoint:

The organization (related to the Api-Key) must match the organization belonging to the fanclub (related to the key). The scope of the email will be filtered down to only customers belonging to the fanclub.

Request

Name Type Description
email url query parameter [Required] Email of the customer you want to search for
Api-Key header key [Required] Organization API Key
curl -H "Api-Key: c97e6157-a4f3-495a-b4bf-24545628dd25" "https://services.sparkart.net/api/v1/account/search?email=temp123@sparkart.com&key=9ade308e-bd28-4b31-b000-3e3be931eed5"

Responses

Success: If all information checks out, the customer information will be returned

{
    "status": "ok",
    "customer": {
        "id": 1,
        "first_name": "Naveen",
        "last_name": "Jain",
        "email": "temp123@sparkart.com",
        "new_email": null,
        "birthdate": "1987-09-03",
        "age": 26,
        "username": "Fighter123", // Only included if the fanclub supports it. Otherwise this key will not exist
        "fanclub_id": 2,
        "expired": false, // True if the customer has no active subscription
        "trial_membership": false,
        "at_renewal_cap": false,
        "email_aliases": [
            "temp123@sparkart.com",
            "tempupdate@sparkart.com"
        ],
        "invalid_email_message": null,
        "authentications": [ // Customer has enable facebook and twitter login. Otherwise this key will be an empty array
            {
                "name": "facebook"
            },
            {
                "name": "twitter"
            }
        ],
        "subscription": { // This key will not exist if current customer has no active subscription
            "plan": {
                "id": 3,
                "name": "Another Plan",
                "class": "another-plan",
                "description": "<p>Plan description or else null</p>",
                "online_benefits": "<p>Plan online benefits or else null</p>",
                "annotations": "<p>Plan annotations or else null</p>",
                "tags": ["presales"]
            },
            "start_date": "2013-01-29T23:39:59Z",
            "end_date": "2014-01-29T23:39:59Z",  // Calculated via plan duration.  Subscription may remain active due to sales period extension
            "lapsed": false,  // True if subscription would have expired, but sales period extension is keeping it active
            "trial_membership": false,
            "affiliates": [
                {
                    "id": 1,
                    "name": "UFC Presales",
                    "codes": [
                        "test-code-1",
                        "test-code-2"
                    ]
                },
                {
                    "id": 2,
                    "name": "UFC.tv PPV",
                    "codes": [
                        "ppv-test-code"
                    ]
                }
            ]
        }
    }
}

Failure: Invalid customer

{
    "status": "ok",
    "customer": null
}

Failure: Invalid API Key(s)

{
    "status": "error",
    "messages": [
        "Please use a valid API Key."
    ]
}