Spaces API


The Spaces API is build on REST principles with resource-oriented URL's. The API is using HTTP status codes for errors. All responses will be returned in JSON format.

API Endpoints

Authentication

Authentication for the API is granted by using the access_token generated through an OAuth 2 application. The API will request authentication via HTTP Basic Auth. For the username, you will use the access_token, and for the password you do not need to enter anything.

Please keep your access tokens secure as they allow for many irreversible actions.

Authentication are mandatory for all requests to the API.

Example on authenticating an API request through curl:

$ curl https://gospaces.com/api/v1/customers \
    -u ACCESS_TOKEN:

SSL

All requests are required to be done through HTTPS. Requests over plain HTTP will be rejected.

Errors

Spaces uses HTTP status codes to indicate errors (or success). Codes in range 2xx indicates success, codes in 4xx range indicates a client side error (e.g. a missing or invalid parameter), and codes in 5xx range indicates an error in Spaces' system.

HTTP status code errors

Error Description
200 OK The request was handled and returned correctly
400 Bad Request Missing a required parameter, or using an invalid parameter
401 Unauthorized No valid API key used
404 Not Found A resource was not found
500 Internal Server Error Something went wrong in Spaces' system

Error return

The returning JSON on errors will often include the following attributes:

Name Description
message A human-readable message giving information about the error.

Versioning

Currently there is no versioning of the API. We're implementing this as soon as there will be breaking changes.

Pagination

Spaces has cursor based pagination for lists of objects.

Pagination Arguments

Name Required Description
limit optional A limit on the number of objects to be returned. Limit can range between 1 and 100 items. Defaults to 20.
starting_after optional A cursor containing the ID of the object you wish to paginate after. If you have obj_bar you wish to paginate after, you can set the subsequent call with starting_after=obj_bar.
starting_before optional A cursor containing the ID of the object you wish to paginate before. If you have obj_bar you wish to paginate before, you can set the subsequent call with starting_after=obj_bar.

List Response Format

Name type Description
object string Is "list".
data array An array of objects for the list.
has_more boolean Whether there is more elements available or not. If false, there is no subsequent pages for the list.

Help us

We always love to hear from you if you have any ideas of how to make the API better. You can contact us directly at help@gospaces.com with your suggestions. Also, feel free to fork these docs and send a pull request with improvements!

Need an account?

Sign up right now at https://gospaces.com/

Account


The account object

Attributes

Name Type Description
object string Is "account".
created integer
name string
email string
avatar_image_url string
referral_code string The referral code the user can use to referrer others.

Example

{
    "object": "account",
    "created": 1412036805,
    "name": "John Doe",
    "email": "test@example.com",
    "avatar_image_url": "http://example.com/image.jpg",
    "referral_code": "V7OAkRU"
}

Retrieve the account

Returns the current authenticated user account.

Example request

curl https://gospaces.com/api/v1/account \
    -u ACCESS_TOKEN:

Example response

{
    "object": "account",
    "created": 1412036805,
    "name": "John Doe",
    "email": "test@example.com",
    "avatar_image_url": "http://example.com/image.jpg",
    "referral_code": "V7OAkRU"
}

Captured Email


The captured email object is read only.

The captured email object

Attributes

Name Type Description
object string Is "captured_email".
email string
created integer
space object

Example

{
    "object": "captured_email",
    "email": "test@example.com",
    "created": 1410196557,
    "space": {
        "object": "space",
        "id": 1,
        "created": 1410196557,
        "url": "https://gospaces.com/s/EXAMPLE"
    }
}

List all captured emails

Returns a list of all captured emails.

Example request

curl https://gospaces.com/api/v1/captured_emails \
    -u ACCESS_TOKEN:

Example response

{
    "object": "list",
    "count": 20,
    "has_more": true,
    "data": [
        {
            "object": "customer",
            "id": "CUSTOMER_TOKEN",
            "name": "John Doe",
            "email": "test@example.com",
            "created": 1410196557,
            "space": {
                "object": "space",
                "id": 1,
                "created": 1410196557,
                "url": "https://gospaces.com/s/EXAMPLE"
            }
        },
        {...}
    ]
}

Customer


The customer object is read only.

The customer object

Attributes

Name Type Description
object string Is "customer".
id string
name string
email string
created integer
space object

Example

{
    "object": "customer",
    "id": "CUSTOMER_TOKEN",
    "name": "John Doe",
    "email": "test@example.com",
    "created": 1410196557,
    "space": {
        "object": "space",
        "id": 1,
        "created": 1410196557,
        "url": "https://gospaces.com/s/EXAMPLE"
    }
}

Retrieve a customer

Returns a specified customer. The customer id is unique among all Spaces for a user.

Example request

curl https://gospaces.com/api/v1/customers/CUSTOMER_TOKEN \
    -u ACCESS_TOKEN:

Example response

{
    "object": "customer",
    "id": "CUSTOMER_TOKEN",
    "name": "John Doe",
    "email": "test@example.com",
    "created": 1410196557,
    "space": {
        "object": "space",
        "id": 1,
        "created": 1410196557,
        "url": "https://gospaces.com/s/EXAMPLE"
    }
}

List all customers

Returns a list of all customers.

Example request

curl https://gospaces.com/api/v1/customers \
    -u ACCESS_TOKEN:

Example response

{
    "object": "list",
    "count": 20,
    "has_more": true,
    "data": [
        {
            "object": "customer",
            "id": "CUSTOMER_TOKEN",
            "name": "John Doe",
            "email": "test@example.com",
            "created": 1410196557,
            "space": {
                "object": "space",
                "id": 1,
                "created": 1410196557,
                "url": "https://gospaces.com/s/EXAMPLE"
            }
        },
        {...}
    ]
}

Event


Events are created when something happens to your data. It can be that a new customer has be created, or a subscription has been cancelled. When an event is created, it will try to send webhooks out through the application webhook URL, the user webhook URL's, and/or the REST Hook URL's.

The event object

Attributes

Name Type Description
object string Is "event".
created integer
type string The event type.
data object Referencing data. E.g. customer, invoice or subscription.

Example

{
    "object": "event",
    "created": 1410196574,
    "type": "customer.created",
    "data": {
        "object": { 
            "object": "customer",
            "token": "CUSTOMER_TOKEN",
            "name": "John Doe",
            "email": "test@example.com",
            "created": 1410196574
        }
    }
}

Event types

Event Description
customer.created A customer has been created
invoice.created An invoice has been created.
invoice.paid An invoice has been paid.
subscription.created A subscription has been created.
subscription.deleted A subscription has been canceled.
captured_email.created An email has been captured through a capture email section.

List all events

Returns a list of all events.

Arguments

Example request

$ curl https://gospaces.com/api/v1/events \
    -u ACCESS_TOKEN:

Example response

{
    "object": "list",
    "count": 20,
    "has_more": true,
    "data": [
        {
            "object": "event",
            "created": 1410196574,
            "type": "customer.created",
            "data": {
                "object": { 
                    "object": "customer",
                    "token": "CUSTOMER_TOKEN",
                    "name": "John Doe",
                    "email": "test@example.com",
                    "created": 1410196574
                }
            }
        },
        {...}
    ]
}

Invoice


The invoice object belongs to a customer.

The invoice object

Attributes

Name Type Description
object string Is "invoice".
id string
created integer
order_number integer The sequential order number. It's scoped to the Space.
billing_address object A JSON object containing an address field.
shipping_address object A JSON object containing an address field.
paid boolean
shipped boolean
shipping_details string A message sent to the customer when the order was marked as shipped.
total integer The fractional amount paid.
currency integer The currency paid in.
items object The invoice items.
items->data array The list of invoice items.
items->count integer Number of invoice items.
customer object

Example

{
    "object": "invoice",
    "id": "INVOICE_TOKEN",
    "order_number": 1,
    "billing_address": {
        "line_1": "SpaceX",
        "line_2": "1 Rocket Rd",
        "line_3": "",
        "zip_code": "90250",
        "locality": "Hawthorne",
        "region": "CA",
        "country":"US"
    },
    "shipping_address": null,
    "created": 1410196576,
    "paid": false,
    "shipped": false,
    "shipping_details": null,
    "total": 1200,
    "currency": "USD",
    "items": {
        "data": [
            {
                "object": "invoice_item",
                "item_id": "100100",
                "description": "Product 1",
                "quantity": 1,
                "discount": 0,
                "unit_amount": 1200,
                "total_amount": 1200,
                "currency": "USD",
                "date_range_start": null,
                "date_range_end": null
            },
            {
                "object": "invoice_item",
                "item_id": 101,
                "description": "Domestic shipping",
                "quantity": 1,
                "discount": 0,
                "unit_amount": 1000,
                "total_amount": 1000,
                "currency": "USD",
                "date_range_start": null,
                "date_range_end": null
            }
        ],
        "count": 2
    },
    "customer": {
        "object": "customer",
        "id": "CUSTOMER_TOKEN",
        "name": "John Doe",
        "email": "test@example.com",
        "created": 1410196576,
        "space": {
            "object": "space",
            "id": 1,
            "created": 1410196557,
            "url": "https://gospaces.com/s/EXAMPLE"
        }
    }
}

Retrieve an invoice

Returns a specified invoice. The invoice id is unique among all Spaces for a user.

Example request

$ curl https://gospaces.com/api/v1/invoices/INVOICE_TOKEN \
    -u ACCESS_TOKEN:

Example response

{
    "object": "invoice",
    "id": "INVOICE_TOKEN",
    "order_number": 1,
    "billing_address": {
        "line_1": "SpaceX",
        "line_2": "1 Rocket Rd",
        "line_3": "",
        "zip_code": "90250",
        "locality": "Hawthorne",
        "region": "CA",
        "country":"US"
    },
    "shipping_address": null,
    "created": 1410196576,
    "paid": false,
    "shipped": false,
    "shipping_details": null,
    "total": 1200,
    "currency": "USD",
    "items": {
        "data": [
            {
                "object": "invoice_item",
                "item_id": "100100",
                "description": "Product 1",
                "quantity": 1,
                "discount": 0,
                "unit_amount": 1200,
                "total_amount": 1200,
                "currency": "USD",
                "date_range_start": null,
                "date_range_end": null
            },
            {
                "object": "invoice_item",
                "item_id": 101,
                "description": "Domestic shipping",
                "quantity": 1,
                "discount": 0,
                "unit_amount": 1000,
                "total_amount": 1000,
                "currency": "USD",
                "date_range_start": null,
                "date_range_end": null
            }
        ],
        "count": 2
    },
    "customer": {
        "object": "customer",
        "id": "CUSTOMER_TOKEN",
        "name": "John Doe",
        "email": "test@example.com",
        "created": 1410196576,
        "space": {
            "object": "space",
            "id": 1,
            "created": 1410196557,
            "url": "https://gospaces.com/s/EXAMPLE"
        }
    }
}

List all invoices

Returns a list of all invoices.

Example request

$ curl https://gospaces.com/api/v1/invoices \
    -u ACCESS_TOKEN:

Example response

{
    "object": "list",
    "count": 2,
    "data": [
        {
            "object": "invoice",
            "id": "INVOICE_TOKEN",
            "order_number": 1,
            "billing_address": {
                "line_1": "SpaceX",
                "line_2": "1 Rocket Rd",
                "line_3": "",
                "zip_code": "90250",
                "locality": "Hawthorne",
                "region": "CA",
                "country":"US"
            },
            "shipping_address": null,
            "created": 1410196576,
            "paid": false,
            "shipped": false,
            "shipping_details": null,
            "total": 1200,
            "currency": "USD",
            "items": {
                "data": [
                    {
                        "object": "invoice_item",
                        "item_id": "100100",
                        "description": "Product 1",
                        "quantity": 1,
                        "discount": 0,
                        "unit_amount": 1200,
                        "total_amount": 1200,
                        "currency": "USD",
                        "date_range_start": null,
                        "date_range_end": null
                    },
                    {
                        "object": "invoice_item",
                        "item_id": 101,
                        "description": "Domestic shipping",
                        "quantity": 1,
                        "discount": 0,
                        "unit_amount": 1000,
                        "total_amount": 1000,
                        "currency": "USD",
                        "date_range_start": null,
                        "date_range_end": null
                    }
                ],
                "count": 2
            }
        },
        "customer": {
            "object": "customer",
            "id": "CUSTOMER_TOKEN",
            "name": "John Doe",
            "email": "test@example.com",
            "created": 1410196576,
            "space": {
                "object": "space",
                "id": 1,
                "created": 1410196557,
                "url": "https://gospaces.com/s/EXAMPLE"
            }
        },
        {...}
    ]
}

Ship or close invoice

You can close an invoice, and also send shipping email if a product was shipped.

Arguments

Name Required/Optional Description
skip_shipped_email optional Don't send an email out. Default to false.
shipping_note optional A note to include in the shipped email.
files optional A list of files to attach to an invoice that can be downloaded.

Example request close

$ curl https://gospaces.com/api/v1/invoices/invoice_token/close \
    -u ACCESS_TOKEN: \
    -d shipping_note="Your FedEx tracking ID is #00000"

Example response

Will respond with 200 OK status, and the full resource subscription object if could be set to shipped, or fail with failure HTTP status code.

Subscription


A subscription object is always tied to a Customer. The subscription token is only unique within the customer scope. For this reason, when you are handling individual subscriptions, you are always required to use the Customer resource.

The subscription object

Attributes

Name Type Description
object string Is "subscription"
token string The token is under the scope of a customer.
serial_number integer The sequential number for the subscription within the scope of the Space.
created integer
items object A list of invoice items for the subscription.
items->data array The list of invoice items.
items->count integer Number of invoice items.
total integer The fractional amount paid.
currency integer The currency paid in.
customer object

Example

{
    "object": "subscription",
    "token": "SUBSCRIPTION_TOKEN",
    "serial_number": 1,
    "created": 1410196578,
    "status": "active",
    "items": {
        "data": [
            {
                "object": "subscription_item",
                "item_id": "100100",
                "description": "Product 7",
                "quantity": 1,
                "discount": 0,
                "unit_amount": 1200,
                "total_amount": 1200
            },
            {
                "object": "subscription_item",
                "item_id": 101,
                "description": "Domestic shipping",
                "quantity": 1,
                "discount": 0,
                "unit_amount": 1000,
                "total_amount": 1000
            }
        ],
        "count": 2
    },
    "total": 2200,
    "currency": "USD",
    "customer": {
        "object": "customer",
        "id": "CUSTOMER_TOKEN",
        "name": "John Doe",
        "email": "test@example.com",
        "created": 1410196576,
        "space": {
            "object": "space",
            "id": 1,
            "created": 1410196557,
            "url": "https://gospaces.com/s/EXAMPLE"
        }
    }
}

Retrieve a subscription

To retrieve a specific subscription resource, you need to use the Customer resource for the subscription in the URI.

Example request

$ curl https://gospaces.com/api/v1/customers/CUSTOMER_TOKEN/subscriptions/SUBSCRIPTION_TOKEN \
    -u ACCESS_TOKEN:

Example response

{
    "object": "subscription",
    "token": "SUBSCRIPTION_TOKEN",
    "serial_number": 1,
    "created": 1410196578,
    "status": "active",
    "items": {
        "data": [
            {
                "object": "subscription_item",
                "item_id": "100100",
                "description": "Product 7",
                "quantity": 1,
                "discount": 0,
                "unit_amount": 1200,
                "total_amount": 1200
            },
            {
                "object": "subscription_item",
                "item_id": 101,
                "description": "Domestic shipping",
                "quantity": 1,
                "discount": 0,
                "unit_amount": 1000,
                "total_amount": 1000
            }
        ],
        "count": 2
    },
    "total": 2200,
    "currency": "USD",
    "customer": {
        "object": "customer",
        "id": "CUSTOMER_TOKEN",
        "name": "John Doe",
        "email": "test@example.com",
        "created": 1410196576,
        "space": {
            "object": "space",
            "id": 1,
            "created": 1410196557,
            "url": "https://gospaces.com/s/EXAMPLE"
        }
    }
}

List all subscriptions

Returns a list of all subscriptions.

Example request

$ curl https://gospaces.com/api/v1/subscriptions \
    -u ACCESS_TOKEN:

Example response

{
    "object": "list",
    "count": 2,
    "data": [
        {
            "object": "subscription",
            "token": "SUBSCRIPTION_TOKEN",
            "serial_number": 1,
            "created": 1410196578,
            "status": "active",
            "items": {
                "data": [
                    {
                        "object": "subscription_item",
                        "item_id": "100100",
                        "description": "Product 7",
                        "quantity": 1,
                        "discount": 0,
                        "unit_amount": 1200,
                        "total_amount": 1200
                    },
                    {
                        "object": "subscription_item",
                        "item_id": 101,
                        "description": "Domestic shipping",
                        "quantity": 1,
                        "discount": 0,
                        "unit_amount": 1000,
                        "total_amount": 1000
                    }
                ],
                "count": 2
            },
            "total": 2200,
            "currency": "USD",
            "customer": {
                "object": "customer",
                "id": "CUSTOMER_TOKEN",
                "name": "John Doe",
                "email": "test@example.com",
                "created": 1410196576,
                "space": {
                    "object": "space",
                    "id": 1,
                    "created": 1410196557,
                    "url": "https://gospaces.com/s/EXAMPLE"
                }
            }
        },
        {...}
    ]
}

Webhook


The webhooks will attempt delivery each hour until delivered, or until 24 tries.

The webhook object

Attributes

Name Type Description
object string Is "webhook"
created integer
url string
event object
pending boolean Whether the webhook is yet to be delivered or not.

Example

{
    "object": "webhook",
    "created": 1412106939,
    "url": "http://example.com/webhook_location_example",
    "event": {
        "object": "event",
        "created": 1412106939,
        "type": "customer.created",
        "data": {
            "object": {
                "object": "customer",
                "id": "CUSTOMER_TOKEN",
                "name": "John Doe",
                "email": "test@example.com",
                "created": 1412106939
            }
        }
    },
    "pending": true
}

List all webhooks

Returns a list of all webhooks.

Example request

$ curl https://gospaces.com/api/v1/webhooks \
    -u ACCESS_TOKEN:

Example response

{
    "object": "list",
    "count": 2,
    "data": [
        {
            "object": "webhook",
            "created": 1412106939,
            "url": "http://example.com/webhook_location_example",
            "event": {
                "object": "event",
                "created": 1412106939,
                "type": "customer.created",
                "data": {
                    "object": {
                        "object": "customer",
                        "id": "CUSTOMER_TOKEN",
                        "name": "John Doe",
                        "email": "test@example.com",
                        "created": 1412106939
                    }
                }
            },
            "pending": true
        },
        {...}
    ]
}

Space


The Space object is read only.

The Space object

Attributes

Name Type Description
id integer ID is sequentially running starting from 1.
object string Is "space".
created integer
url string If null, the space is not publicly available.

Example

{
    "object": "space",
    "id": 1,
    "created": 1410196557,
    "url": "https://gospaces.com/s/EXAMPLE"
}

Retrieve a Space

Returns a specified Space.

Example request

$ curl https://gospaces.com/api/v1/spaces/1 \
    -u ACCESS_TOKEN:

Example response

{
    "object": "space",
    "id": 1,
    "created": 1410196557,
    "url": "https://gospaces.com/s/EXAMPLE"
}

List all Spaces

Returns a list of all Spaces.

Example request

curl https://gospaces.com/api/v1/spaces \
    -u ACCESS_TOKEN:

Example response

{
    "object": "list",
    "count": 20,
    "has_more": true,
    "data": [
        {
            "object": "space",
            "id": 1,
            "created": 1410196557,
            "url": "https://gospaces.com/s/EXAMPLE"
        },
        {...}
    ]
}

Resource Subscription


The resource subscription is based in REST Hooks.

The customer object

Attributes

Name Type Description
object string Is "resource_subscription".
event string
target_url string
api_version string
created integer

Example

{
    "object": "resource_subscription",
    "event": "customer.created",
    "target_url": "http://example.com/resource_subscription_example",
    "api_version": "04-09-2014",
    "created":1412036808
}

Create a resource subscription

A resource subscription can be created over the API.

Arguments

Name Required/Optional Description
event required The event to trigger for.
target_url required The target URL to send webhooks to.

Example request create

$ curl https://gospaces.com/api/v1/resource_subscriptions \
    -u ACCESS_TOKEN: \
    -d event="customer.created" \
    -d target_url="http://example.com/resource_subscription_example"

Example response

Will respond with 200 OK status, and the full resource subscription object if valid, or fail with failure HTTP status code.

List all resource subscriptions

Returns a list of all resource subscriptions.

Example request

curl https://gospaces.com/api/v1/resource_subscriptions \
    -u ACCESS_TOKEN:

Example response

{
    "object": "list",
    "count": 20,
    "has_more": true,
    "data": [
        {
            "object": "resource_subscription",
            "event": "customer.created",
            "target_url": "http://example.com/resource_subscription_example",
            "api_version": "04-09-2014",
            "created":1412036808
        },
        {...}
    ]
}