Auth & credentials

The DjaoApp API is meant to be used by your application front-end logic in the same way you are calling your application backend API. DjaoApp seemlessly extends your application's backend with accounts & billing API end points required to manage authentication, subscription, user profiles, billing statements and other administrative features required to run Software-as-a-Service on the Internet.

DjaoApp supports three methods of authentication:

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

To learn more about authenticating to a DjaoApp service, visit How to authenticate with the API on the command line?

Logs a user in

POST /api/auth/
        

Returns a JSON Web Token that can be used in requests that require authentication.

Request body
username
string required

Username to identify the account

password
string required

Secret password for the account

code
integer

One-time code. This field will be checked against an expected code when multi-factor authentication (MFA) is enabled.

Responses

200

token
string

Token used to authenticate user on every HTTP request

Examples

POST /api/auth/
{
  "username": "donny",
  "password": "yoyo"
}
responds
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"
}

Retrieves user associated to an activation key

GET /api/auth/activate/{verification_key}/
        

Retrieves information about a user based on an activation key.

Responses

200

slug
string

printable_name
string

Full name

picture
string

Picture

email
string

Primary e-mail to contact user

created_at
string

credentials
string

True if the user has valid login credentials

username
string

full_name
string

Full name

Examples

GET /api/auth/activate/0123456789abcef0123456789abcef/
responds
{
  "username": "joe1",
  "email": "joe1@localhost.localdomain",
  "full_name": "Joe Act"
}

Activates a user

POST /api/auth/activate/{verification_key}/
        

Activates a new user and returns a JSON Web Token that can subsequently be used to authenticate the new user in HTTP requests.

Request body
username
string

Username to identify the account

new_password
string

Password with which a user can authenticate with the service

full_name
string

Full name (effectively first name followed by last name)

Responses

200

token
string

Token used to authenticate user on every HTTP request

Examples

POST /api/auth/activate/0123456789abcef0123456789abcef/
{
  "username": "joe1",
  "new_password": "yoyo",
  "full_name": "Joe Card1"
}
responds
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6    ImpvZTEiLCJlbWFpbCI6ImpvZSsxQGRqYW9kamluLmNvbSIsImZ1bGxfbmFtZ    SI6IkpvZSAgQ2FyZDEiLCJleHAiOjE1Mjk2NTUyMjR9.GFxjU5AvcCQbVylF1P    JwcBUUMECj8AKxsHtRHUSypco"
}

Logs a user out

POST /api/auth/logout/
        

Removes all cookies associated with the session.

This API endpoint is only useful when the user is using Cookie-based authentication. Tokens expire; they cannot be revoked.

Responses

200

Examples

POST /api/auth/logout/

Emails a password reset link

POST /api/auth/recover/
        

The user is uniquely identified by her email address.

Request body
email
string required

Primary e-mail to contact user

Responses

200

email
string

Primary e-mail to contact user

Examples

POST /api/auth/recover/
{
  "email": "xia@localhost.localdomain"
}
responds
{
  "email": "xia@localhost.localdomain"
}

Registers a user

POST /api/auth/register/
        

Creates a new user and returns a JSON Web Token that can subsequently be used to authenticate the new user in HTTP requests.

Request body
username
string

Username to identify the account

password
string

Password with which a user can authenticate with the service

email
string required

Primary e-mail to contact user

full_name
string required

Full name (effectively first name followed by last name)

Responses

200

token
string

Token used to authenticate user on every HTTP request

Examples

POST /api/auth/register/
{
  "username": "joe1",
  "password": "yoyo",
  "email": "joe+1@example.com",
  "full_name": "Joe Card1"
}
responds
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImpvZTEiLCJlbWFpbCI6ImpvZSsxQGRqYW9kamluLmNvbSIsImZ1bGxfbmFtZSI6IkpvZSAgQ2FyZDEiLCJleHAiOjE1Mjk2NTUyMjR9.GFxjU5AvcCQbVylF1PJwcBUUMECj8AKxsHtRHUSypco"
}

Confirms a password reset

POST /api/auth/reset/{uidb64}/{token}/
        

Sets a new password after a recover password was triggered and returns a JSON Web Token that can subsequently be used to authenticate the new user in HTTP requests.

Request body
new_password
string required

New password for the user referenced in the URL

Responses

200

token
string

Token used to authenticate user on every HTTP request

Examples

POST /api/auth/reset/0123456789abcef0123456789abcef/abc123/
{
  "new_password": "yoyo",
  "new_password2": "yoyo"
}
responds
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImpvZTEiLCJlbWFpbCI6ImpvZSsxQGRqYW9kamluLmNvbSIsImZ1bGxfbmFtZSI6IkpvZSAgQ2FyZDEiLCJleHAiOjE1Mjk2NTUyMjR9.GFxjU5AvcCQbVylF1PJwcBUUMECj8AKxsHtRHUSypco"
}

Refreshes a JSON Web Token

POST /api/auth/tokens/
        

Refreshes a JSON Web Token by verifying the token and creating a new one that expires further in the future.

The authenticated user and the user associated to the token should be identical.

Request body
token
string required

Token used to authenticate user on every HTTP request

Responses

200

token
string

Token used to authenticate user on every HTTP request

Examples

POST /api/tokens/
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"
}
responds
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5Njk1NjA1fQ.-uuZb8R68jWw1Tc9FJocOWe1KHFklRffXbH0Rg6d_0c"
}

Verifies a JSON Web Token

POST /api/auth/tokens/verify/
        

The authenticated user and the user associated to the token should be identical.

Request body
token
string required

Token used to authenticate user on every HTTP request

Responses

200

token
string

Token used to authenticate user on every HTTP request

Examples

POST /api/tokens/verify/
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"
}
responds
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"
}

Sends a contact-us message

POST /api/contact/
        

Emails a free form contact-us message from a customer to the provider

Request body
full_name
string required

email
string required

message
string

Responses

200

full_name
string

email
string

message
string

Examples

POST /api/contact/
{
  "email": "joe+1@example.com",
  "full_name": "Joe Card1",
  "message": "Can I request a demo?"
}
responds
{
  "details": "Your request has been sent. We will reply within24 hours. Thank you."
}

Re-sends an activation link

POST /api/users/{user}/activate/
        

Re-sends an activation e-mail if the user is not already activated.

The template for the e-mail sent to the user can be found in notification/verification.eml.

Responses

200

slug
string

Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.

printable_name
string

picture
string

Profile picture

email
string

E-mail address

created_at
string

Date/time of creation (in ISO format)

credentials
string

True if the user has valid login credentials

Examples

POST /api/users/donny/activate/
responds
{
  "slug": "xia",
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "nick_name": "Xia",
  "created_at": "2018-01-01T00:00:00Z"
}

Resets a user secret API key

POST /api/users/{user}/api-keys/
        

Resets the secret API key with which a user can authenticate with the service.

Responses

200

secret
string

Secret API Key used to authenticate user on every HTTP request

Examples

POST /api/users/donny/api-keys/
responds
{
  "secret": "tgLwDw5ErQ2pQr5TTdAzSYjvZenHC9pSy7fB3sXWERzynbG5zG6h67pTN4dh7fpy"
}

Changes a user password

PUT /api/users/{user}/password/
        
Request body
new_password
string required

New password for the user referenced in the URL

password
string required

Password of the user making the HTTP request

Responses

200

Examples

PUT /api/users/donny/password/
{
  "password": "yeye",
  "new_password": "yoyo"
}
responds
{}

Updates a user public RSA key

PUT /api/users/{user}/ssh-keys/
        
Request body
password
string required

Password of the user making the HTTP request

pubkey
string required

New public key for the user referenced in the URL

Responses

200

Examples

PUT /api/users/donny/ssh-keys/
{
  "pubkey": "ssh-rsa AAAAB3N...",
  "password": "secret"
}
responds
{
  "detail": "ok"
}

Lists processor charges

GET /api/billing/charges/
        

Queries a page (PAGE_SIZE records) of Charge that were created on the processor.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

Query parameters
page
integer

A page number within the paginated result set.

o
string

Which field to use when ordering the results.

q
string

A search term.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

Date/time of creation (in ISO format)

amount
integer

Total amount in currency unit

unit
string

Three-letter ISO 4217 code for currency unit (ex: usd)

readable_amount
string

Amount and unit in a commonly accepted readable format

description
string

Description for the charge as appears on billing statements

last4
integer

Last 4 digits of the credit card used

exp_date
string

Expiration date of the credit card used

processor_key
string

state
string

Current state (i.e. created, done, failed, disputed)

Examples

GET /api/billing/charges?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc
responds
{
  "count": 1,
  "unit": "usd",
  "total": "112120",
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2016-01-01T00:00:02Z",
      "readable_amount": "$1121.20",
      "amount": 112120,
      "unit": "usd",
      "description": "Charge for subscription to cowork open-space",
      "last4": "1234",
      "exp_date": "2016-06-01",
      "processor_key": "ch_XAb124EF",
      "state": "DONE"
    }
  ]
}

Retrieves a single processor charge

GET /api/billing/charges/{organization}/
        

Pass through to the processor and returns details about a Charge.

Responses

200

created_at
string

Date/time of creation (in ISO format)

amount
integer

Total amount in currency unit

unit
string

Three-letter ISO 4217 code for currency unit (ex: usd)

readable_amount
string

Amount and unit in a commonly accepted readable format

description
string

Description for the charge as appears on billing statements

last4
integer

Last 4 digits of the credit card used

exp_date
string

Expiration date of the credit card used

processor_key
string

state
string

Current state (i.e. created, done, failed, disputed)

Examples

GET /api/billing/charges/ch_XAb124EF/
responds
{
  "created_at": "2016-01-01T00:00:01Z",
  "readable_amount": "$1121.20",
  "amount": 112120,
  "unit": "usd",
  "description": "Charge for subscription to cowork open-space",
  "last4": "1234",
  "exp_date": "2016-06-01",
  "processor_key": "ch_XAb124EF",
  "state": "DONE"
}

Re-sends a charge receipt

POST /api/billing/charges/{organization}/email/
        

Email the charge receipt to the customer email address on file.

The service sends a duplicate e-mail receipt for charge ch_XAb124EF to the e-mail address of the customer, i.e. joe@localhost.localdomain.

Responses

200

charge_id
string

Charge identifier (i.e. matches the URL {charge} parameter)

email
string

E-mail address to which the receipt was sent.

Examples

POST /api/billing/charges/ch_XAb124EF/email/
responds
{
  "charge_id": "ch_XAb124EF",
  "email": "joe@localhost.localdomain"
}

Refunds a processor charge

POST /api/billing/charges/{organization}/refund/
        

Partially or totally refund all or a subset of line items on a Charge.

Request body
lines
array required

num
integer

Line item index counting from zero.

refunded_amount
integer

The amount to refund cannot be higher than the amount of the line item minus the total amount already refunded on that line item.

Responses

200

created_at
string

Date/time of creation (in ISO format)

amount
integer

Total amount in currency unit

unit
string

Three-letter ISO 4217 code for currency unit (ex: usd)

readable_amount
string

Amount and unit in a commonly accepted readable format

description
string

Description for the charge as appears on billing statements

last4
integer

Last 4 digits of the credit card used

exp_date
string

Expiration date of the credit card used

processor_key
string

state
string

Current state (i.e. created, done, failed, disputed)

Examples

POST /api/billing/charges/ch_XAb124EF/refund/
{
  "lines": [
    {
      "num": 0,
      "refunded_amount": 4000
    },
    {
      "num": 1,
      "refunded_amount": 82120
    }
  ]
}
responds
{
  "created_at": "2016-01-01T00:00:05Z",
  "readable_amount": "$1121.20",
  "amount": 112120,
  "unit": "usd",
  "description": "Charge for subscription to cowork open-space",
  "last4": "1234",
  "exp_date": "2016-06-01",
  "processor_key": "ch_XAb124EF",
  "state": "DONE"
}

Lists ledger transactions

GET /api/billing/transactions/
        

Queries a page (PAGE_SIZE records) of Transaction from the ledger.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

Query parameters
page
integer

A page number within the paginated result set.

q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

True if the transaction is indentified as a debit in the API context

orig_account
string

Source account from which funds are withdrawn

orig_organization
string

Source organization from which funds are withdrawn

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

Three-letter ISO 4217 code for source currency unit (ex: usd)

dest_account
string

Target account to which funds are deposited

dest_organization
string

Target organization to which funds are deposited

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

Three-letter ISO 4217 code for target currency unit (ex: usd)

Examples

GET /api/billing/transactions?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc
responds
{
  "ends_at": "2017-03-30T18:10:12.962859Z",
  "balance": 11000,
  "unit": "usd",
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2017-02-01T00:00:00Z",
      "description": "Charge for 4 periods",
      "amount": "($356.00)",
      "is_debit": true,
      "orig_account": "Liability",
      "orig_organization": "xia",
      "orig_amount": 112120,
      "orig_unit": "usd",
      "dest_account": "Funds",
      "dest_organization": "stripe",
      "dest_amount": 112120,
      "dest_unit": "usd"
    }
  ]
}

Retrieves a customer balance

GET /api/billing/{organization}/balance/
        

Get the statement balance due for an organization.

Responses

200

Examples

GET /api/billing/cowork/balance/
responds
{
  "balance_amount": "1200",
  "balance_unit": "usd"
}

Cancels a balance due

DELETE /api/billing/{organization}/balance/
        

Cancel the balance for a provider organization. This will create a transaction for this balance cancellation. A manager can use this endpoint to cancel balance dues that is known impossible to be recovered (e.g. an external bank or credit card company act).

The endpoint returns the transaction created to cancel the balance due.

Responses

204

Examples

DELETE /api/billing/cowork/balance/

Retrieves a user cart for checkout

GET /api/billing/{organization}/checkout/
        

Get a list indexed by plans of items that will be charged (lines) and options that could be charged instead.

In many subscription businesses, it is possible to buy multiple period in advance at a discount. The options reflects that.

Responses

200

items
array

subscription
object required

Subscription lines and options refer to.

created_at
string

Date/time of creation (in ISO format)

ends_at
string

Date/time when the subscription period currently ends (in ISO format)

description
string

Free-form text description for the subscription

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

plan
object

slug
string

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period for the subscription

app_url
string

advance_discount
integer

Incremental discount for payment of multiple periods (in %%).

unit
string

organization
string

Provider of the plan

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Natural period length of a subscription to the plan (monthly, yearly, etc.)

renewal_type
string

Natural period for the subscription

is_not_priced
boolean

created_at
string

skip_optin_on_grant
boolean

True when a subscriber can automatically be subscribed to the plan by its provider. Otherwise the subscriber must manually accept the subscription. (defaults to False)

optin_on_request
boolean

True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)

auto_renew
boolean

The subscription is set to auto-renew at the end of the period

editable
string

True if the request user is able to update the subscription. Typically a manager for the plan provider.

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

request_key
string

lines
array

Line items to charge on checkout.

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

True if the transaction is indentified as a debit in the API context

orig_account
string

Source account from which funds are withdrawn

orig_organization
string

Source organization from which funds are withdrawn

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

Three-letter ISO 4217 code for source currency unit (ex: usd)

dest_account
string

Target account to which funds are deposited

dest_organization
string

Target organization to which funds are deposited

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

Three-letter ISO 4217 code for target currency unit (ex: usd)

options
array

Options to replace line items.

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

True if the transaction is indentified as a debit in the API context

orig_account
string

Source account from which funds are withdrawn

orig_organization
string

Source organization from which funds are withdrawn

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

Three-letter ISO 4217 code for source currency unit (ex: usd)

dest_account
string

Target account to which funds are deposited

dest_organization
string

Target organization to which funds are deposited

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

Three-letter ISO 4217 code for target currency unit (ex: usd)

Examples

GET /api/billing/xia/checkout
responds
{
  "items": [
    {
      "subscription": {
        "created_at": "2016-06-21T23:24:09.242925Z",
        "ends_at": "2016-10-21T23:24:09.229768Z",
        "description": null,
        "organization": {
          "slug": "xia",
          "full_name": "Xia",
          "printable_name": "Xia",
          "created_at": "2012-08-14T23:16:55Z",
          "email": "xia@localhost.localdomain"
        },
        "plan": {
          "slug": "basic",
          "title": "Basic",
          "description": "Basic Plan",
          "is_active": true,
          "setup_amount": 0,
          "period_amount": 2000,
          "period_type": "monthly",
          "app_url": "/app/"
        },
        "auto_renew": true
      },
      "lines": [
        {
          "created_at": "2016-06-21T23:42:13.863739Z",
          "description": "Subscription to basic until 2016/11/21 (1 month)",
          "amount": "$20.00",
          "is_debit": false,
          "orig_account": "Receivable",
          "orig_organization": "cowork",
          "orig_amount": 2000,
          "orig_unit": "usd",
          "dest_account": "Payable",
          "dest_organization": "xia",
          "dest_amount": 2000,
          "dest_unit": "usd"
        }
      ],
      "options": []
    }
  ]
}

Checkouts a user cart

POST /api/billing/{organization}/checkout/
        

Places an order for the subscription items in the cart and creates a Charge on the {organization} payment card.

If the charge fails a balance is due, to be collected later.

The cart is manipulated through various API endpoints:

  • /api/cart/redeem/ applies a coupon code for a potential discount.

  • /api/cart/ adds or updates a cart item.

  • /api/cart/{plan} removes a cart item.

Responses

200

created_at
string

Date/time of creation (in ISO format)

amount
integer

Total amount in currency unit

unit
string

Three-letter ISO 4217 code for currency unit (ex: usd)

readable_amount
string

Amount and unit in a commonly accepted readable format

description
string

Description for the charge as appears on billing statements

last4
integer

Last 4 digits of the credit card used

exp_date
string

Expiration date of the credit card used

processor_key
string

state
string

Current state (i.e. created, done, failed, disputed)

Examples

POST /api/billing/xia/checkout
responds
{
  "created_at": "2016-06-21T23:42:44.270977Z",
  "processor_key": "pay_5lK5TacFH3gbKe",
  "amount": 2000,
  "unit": "usd",
  "description": "Charge pay_5lK5TacFH3gblP on credit card of Xia",
  "last4": "1234",
  "exp_date": "2016-06-01",
  "state": "created"
}

Lists discount codes

GET /api/billing/{organization}/coupons/
        

Queries a page (PAGE_SIZE records) of Coupon associated to a provider.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

Query parameters
page
integer

A page number within the paginated result set.

o
string

Which field to use when ordering the results.

q
string

A search term.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

code
string

Unique identifier per provider, typically used in URLs

percent
integer

Percentage discounted

created_at
string

Date/time of creation (in ISO format)

ends_at
string

Date/time at which the coupon code expires (in ISO format)

description
string

Free-form text description for the coupon

nb_attempts
integer

Number of times the coupon can be used

plan
string

Examples

GET /api/billing/cowork/coupons?o=code&ot=asc&q=DIS
responds
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "code": "DIS100",
      "percent": 100,
      "created_at": "2014-01-01T09:00:00Z",
      "ends_at": null,
      "description": null
    },
    {
      "code": "DIS50",
      "percent": 50,
      "created_at": "2014-01-01T09:00:00Z",
      "ends_at": null,
      "description": null
    }
  ]
}

Retrieves a discount code

GET /api/billing/{organization}/coupons/{coupon}/
        
Responses

200

code
string

Unique identifier per provider, typically used in URLs

percent
integer

Percentage discounted

created_at
string

Date/time of creation (in ISO format)

ends_at
string

Date/time at which the coupon code expires (in ISO format)

description
string

Free-form text description for the coupon

nb_attempts
integer

Number of times the coupon can be used

plan
string

Examples

GET /api/billing/cowork/coupons/DIS100
responds
{
  "code": "DIS100",
  "percent": 100,
  "created_at": "2014-01-01T09:00:00Z",
  "ends_at": null,
  "description": null
}

Updates a discount code

PUT /api/billing/{organization}/coupons/{coupon}/
        
Request body
code
string required

Unique identifier per provider, typically used in URLs

percent
integer

Percentage discounted

ends_at
string

Date/time at which the coupon code expires (in ISO format)

description
string

Free-form text description for the coupon

nb_attempts
integer

Number of times the coupon can be used

plan
string

Responses

200

code
string

Unique identifier per provider, typically used in URLs

percent
integer

Percentage discounted

created_at
string

Date/time of creation (in ISO format)

ends_at
string

Date/time at which the coupon code expires (in ISO format)

description
string

Free-form text description for the coupon

nb_attempts
integer

Number of times the coupon can be used

plan
string

Examples

PUT /api/billing/cowork/coupons/DIS100
{
  "percent": 100,
  "ends_at": null,
  "description": null
}
responds
{
  "percent": 100,
  "ends_at": null,
  "description": null
}

Deletes a discount code

DELETE /api/billing/{organization}/coupons/{coupon}/
        

Only coupons which have never been applied to an oder will be permanently deleted. Coupons which have already be used at least once will be de-activated and still available for performance measurements.

Responses

204

Examples

DELETE /api/billing/cowork/coupons/DIS100

Lists subscriber transactions

GET /api/billing/{organization}/history/
        

Queries a page (PAGE_SIZE records) of Transaction associated to {organization} while the organization acts as a subscriber.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

This API end point is typically used to display orders, payments and refunds of a subscriber (see subscribers pages)

Query parameters
page
integer

A page number within the paginated result set.

q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

True if the transaction is indentified as a debit in the API context

orig_account
string

Source account from which funds are withdrawn

orig_organization
string

Source organization from which funds are withdrawn

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

Three-letter ISO 4217 code for source currency unit (ex: usd)

dest_account
string

Target account to which funds are deposited

dest_organization
string

Target organization to which funds are deposited

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

Three-letter ISO 4217 code for target currency unit (ex: usd)

Examples

GET /api/billing/xia/history?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "balance": 11000,
  "unit": "usd",
  "results": [
    {
      "created_at": "2015-08-01T00:00:00Z",
      "description": "Charge for 4 periods",
      "amount": "($356.00)",
      "is_debit": true,
      "orig_account": "Liability",
      "orig_organization": "xia",
      "orig_amount": 112120,
      "orig_unit": "usd",
      "dest_account": "Funds",
      "dest_organization": "stripe",
      "dest_amount": 112120,
      "dest_unit": "usd"
    }
  ]
}

Lists provider receivables

GET /api/billing/{organization}/receivables/
        

Queries a page (PAGE_SIZE records) of Transaction marked as receivables associated to {organization} while the organization acts as a provider.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

This API endpoint is typically used to find all sales for {organization} whether it was paid or not.

Query parameters
page
integer

A page number within the paginated result set.

q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

True if the transaction is indentified as a debit in the API context

orig_account
string

Source account from which funds are withdrawn

orig_organization
string

Source organization from which funds are withdrawn

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

Three-letter ISO 4217 code for source currency unit (ex: usd)

dest_account
string

Target account to which funds are deposited

dest_organization
string

Target organization to which funds are deposited

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

Three-letter ISO 4217 code for target currency unit (ex: usd)

Examples

GET /api/billing/cowork/receivables?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc
responds
{
  "count": 1,
  "total": "112120",
  "unit": "usd",
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2015-08-01T00:00:00Z",
      "description": "Charge <a href='/billing/cowork/receipt/1123'>1123</a> distribution for demo562-open-plus",
      "amount": "112120",
      "is_debit": false,
      "orig_account": "Funds",
      "orig_organization": "stripe",
      "orig_amount": 112120,
      "orig_unit": "usd",
      "dest_account": "Funds",
      "dest_organization": "cowork",
      "dest_amount": 112120,
      "dest_unit": "usd"
    }
  ]
}

Lists provider payouts

GET /api/billing/{organization}/transfers/
        

Queries a page (PAGE_SIZE records) of Transaction associated to {organization} while the organization acts as a provider.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

This API endpoint is typically used to find sales, payments, refunds and bank deposits for a provider. (see provider pages)

Query parameters
page
integer

A page number within the paginated result set.

q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

True if the transaction is indentified as a debit in the API context

orig_account
string

Source account from which funds are withdrawn

orig_organization
string

Source organization from which funds are withdrawn

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

Three-letter ISO 4217 code for source currency unit (ex: usd)

dest_account
string

Target account to which funds are deposited

dest_organization
string

Target organization to which funds are deposited

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

Three-letter ISO 4217 code for target currency unit (ex: usd)

Examples

GET /api/billing/cowork/transfers?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2015-08-01T00:00:00Z",
      "description": "Charge <a href='/billing/cowork/receipt/1123'>1123</a> distribution for demo562-open-plus",
      "amount": "$1121.20",
      "is_debit": false,
      "orig_account": "Funds",
      "orig_organization": "stripe",
      "orig_amount": 112120,
      "orig_unit": "usd",
      "dest_account": "Funds",
      "dest_organization": "cowork",
      "dest_amount": 112120,
      "dest_unit": "usd"
    }
  ]
}

Inserts an offline transactions.

POST /api/billing/{organization}/transfers/import/
        

The primary purpose of this API call is for a provider to keep accurate metrics for the performance of the product sold, regardless of payment options (online or offline).

Request body
subscription
string required

The subscription the offline transaction refers to.

created_at
string required

Date/time of creation (in ISO format)

amount
number required

descr
string

Free-form text description for the transaction

Responses

200

subscription
string

The subscription the offline transaction refers to.

created_at
string

Date/time of creation (in ISO format)

amount
number

descr
string

Free-form text description for the transaction

Examples

POST /api/billing/cowork/transfers/import/
{
  "subscription": "demo562-open-plus",
  "amount": "10.00",
  "descr": "Paid by check"
}
responds
{
  "subscription": "demo562-open-plus",
  "amount": "10.00",
  "descr": "Paid by check"
}

Adds an item into a cart

POST /api/cart/
        

Adds a Plan into the cart of the request.user.

The cart can later be checked out and paid by an Organization, either through the HTML page or API end point.

This end point is typically used when a user is presented with a list of add-ons that she can subscribes to in one checkout screen. The end-point works in both cases, authenticated or anonymous users. For authenticated users, the cart is stored in the database as CartItem objects. For anonymous users, the cart is stored in an HTTP Cookie.

The end-point accepts a single item or a list of items.

quantity is optional. When it is not specified, subsquent checkout screens will provide choices to pay multiple periods in advance When additional full_name, email and sync_on are specified, payment can be made by one Organization for another Organization to be subscribed (see GroupBuy orders).

option is optional. When it is not specified, subsquent checkout screens will provide choices to pay multiple periods in advance When additional full_name and sync_on are specified, payment can be made by one Organization for another Organization to be subscribed (see GroupBuy orders).

Request body
plan
string required

The plan to add into the request.user cart.

option
integer

full_name
string

Full name of the person that will benefit from the subscription (GroupBuy)

sync_on
string

email
string

Responses

200

plan
string

The plan to add into the request.user cart.

option
integer

full_name
string

Full name of the person that will benefit from the subscription (GroupBuy)

sync_on
string

email
string

Examples

POST /api/cart/
{
  "plan": "open-space",
  "option": 1
}
responds
{
  "plan": "open-space",
  "option": 1
}

Removes an item from a cart

DELETE /api/cart/
        

Removes an item from the request.user cart.

Responses

204

Examples

DELETE /api/cart/?plan=open-space

Redeems a discount code

POST /api/cart/redeem/
        

Redeems a Coupon and applies the discount to the eligible items in the cart.

Request body
code
string required

Coupon code to redeem

Responses

200

detail
string

Describes the reason for the error in plain text

Examples

POST /api/redeem
{
  "code": "LABORDAY"
}
responds
{
  "details": "Coupon 'LABORDAY' was successfully applied."
}

Uploads multiple discount codes into a cart

POST /api/cart/{plan}/upload/
        

Add a Plan into the subscription cart of multiple users as per the content of an uploaded file.

This works bulk fashion of /cart/ endpoint. The uploaded file must be a CSV containing the fields first_name, last_name and email. The CSV file must not contain a header line, only data.

Responses

200

created
string

updated
string

failed
string

Examples

POST /api/cart/basic/upload/
responds
{
  "created": [
    {
      "first_name": "Joe",
      "last_name": "Smith",
      "email": "joesmith@example.com"
    },
    {
      "first_name": "Marie",
      "last_name": "Johnson",
      "email": "mariejohnson@example.com"
    }
  ],
  "updated": [],
  "failed": []
}

Remove tags from an editable node

PUT /api/themes/editables/{slug}/remove-tags/
        

Remove tags from a PageElement.

Request body
tag
string

Responses

200

tag
string

Examples

PUT /api/editables/_my-element_/reomve-tags
{
  "tag": "sometag"
}
responds
{}

Retrieves a balance sheet

GET /api/metrics/balances/{report}/
        

Queries a balance sheet named {report} for the broker.

To add lines in the report see /api/metrics/balances/{report}/lines/.

Responses

200

scale
number

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)

unit
string

Three-letter ISO 4217 code for currency unit (ex: usd)

title
string

Title for the table

table
array

key
string

Unique key in the table for the data series

selector
string

Filter on the Transaction accounts

values
array

Datapoints in the serie

Examples

GET /api/metrics/balances/taxes/
responds
{
  "scale": 0.01,
  "unit": "usd",
  "title": "Balances: taxes",
  "table": [
    {
      "key": "Sales",
      "selector": "Receivable",
      "values": [
        [
          "2015-05-01T00:00:00Z",
          0
        ],
        [
          "2015-08-01T00:00:00Z",
          0
        ],
        [
          "2015-11-01T00:00:00Z",
          0
        ],
        [
          "2016-02-01T00:00:00Z",
          0
        ],
        [
          "2016-05-01T00:00:00Z",
          0
        ],
        [
          "2016-05-16T21:08:15.637Z",
          0
        ]
      ]
    }
  ]
}

Retrieves row headers for a balance sheet

GET /api/metrics/balances/{report}/lines/
        

Queries the list of rows reported on a balance sheet named {report}.

Query parameters
page
integer

A page number within the paginated result set.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

title
string

Title for the row

selector
string

Filter on the Transaction accounts

rank
integer

Absolute position of the row in the list of rows for the table

Examples

GET /api/metrics/balances/taxes/lines/
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "title": "Sales",
      "selector": "Receivable",
      "rank": 1
    }
  ]
}

Creates a row in a balance sheet

POST /api/metrics/balances/{report}/lines/
        

Adds a new row on the {report} balance sheet.

Request body
title
string required

Title for the row

selector
string

Filter on the Transaction accounts

rank
integer required

Absolute position of the row in the list of rows for the table

Responses

200

title
string

Title for the row

selector
string

Filter on the Transaction accounts

rank
integer

Absolute position of the row in the list of rows for the table

Examples

POST /api/metrics/balances/taxes/lines/
{
  "title": "Sales",
  "selector": "Receivable",
  "rank": 1
}
responds
{
  "title": "Sales",
  "selector": "Receivable",
  "rank": 1
}

Retrieves a row in a balance sheet

GET /api/metrics/balances/{report}/lines/{rank}/
        

Describes a row reported on a balance sheet named {report}.

Responses

200

title
string

Title for the row

selector
string

Filter on the Transaction accounts

rank
integer

Absolute position of the row in the list of rows for the table

Examples

GET /api/metrics/balances/taxes/lines/1/
responds
{
  "title": "Sales",
  "selector": "Receivable",
  "rank": 1
}

Updates a row in a balance sheet

PUT /api/metrics/balances/{report}/lines/{rank}/
        

Updates a row reported on a balance sheet named {report}.

Request body
title
string required

Title for the row

selector
string

Filter on the Transaction accounts

rank
integer required

Absolute position of the row in the list of rows for the table

Responses

200

title
string

Title for the row

selector
string

Filter on the Transaction accounts

rank
integer

Absolute position of the row in the list of rows for the table

Examples

PUT /api/metrics/balances/taxes/lines/1/
{
  "title": "Sales",
  "selector": "Receivable",
  "rank": 1
}
responds
{
  "title": "Sales",
  "selector": "Receivable",
  "rank": 1
}

Deletes a row in a balance sheet

DELETE /api/metrics/balances/{report}/lines/{rank}/
        

Deletes a row reported on a balance sheet named {report}.

Responses

204

Examples

DELETE /api/metrics/balances/taxes/lines/1/

Lists top of funnel registered users

GET /api/metrics/registered/
        

Lists all User which have no associated role or a role to an Organization which has no Subscription, active or inactive.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

Query parameters
page
integer

A page number within the paginated result set.

o
string

Which field to use when ordering the results.

q
string

A search term.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

slug
string

Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.

email
string

E-mail address for the user

full_name
string

Full name for the contact (effectively first name followed by last name)

created_at
string

Date/time of creation (in ISO format)

Examples

GET /api/metrics/registered?o=created_at&ot=desc
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "alice",
      "email": "alice@djaodjin.com",
      "full_name": "Alice Cooper",
      "created_at": "2014-01-01T00:00:00Z"
    }
  ]
}

Lists active subscriptions

GET /api/metrics/{organization}/active/
        

Lists all Subscription to a plan whose provider is {organization} and which are currently in progress.

Optionnaly when an ends_at query parameter is specified, returns a queryset of Subscription that were active at ends_at. When a start_at query parameter is specified, only considers Subscription that were created after start_at.

The queryset can be filtered for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

Query parameters
page
integer

A page number within the paginated result set.

o
string

Which field to use when ordering the results.

q
string

A search term.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

Date/time of creation (in ISO format)

ends_at
string

Date/time when the subscription period currently ends (in ISO format)

description
string

Free-form text description for the subscription

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

plan
object

slug
string

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period for the subscription

app_url
string

advance_discount
integer

Incremental discount for payment of multiple periods (in %%).

unit
string

organization
string

Provider of the plan

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Natural period length of a subscription to the plan (monthly, yearly, etc.)

renewal_type
string

Natural period for the subscription

is_not_priced
boolean

created_at
string

skip_optin_on_grant
boolean

True when a subscriber can automatically be subscribed to the plan by its provider. Otherwise the subscriber must manually accept the subscription. (defaults to False)

optin_on_request
boolean

True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)

auto_renew
boolean

The subscription is set to auto-renew at the end of the period

editable
string

True if the request user is able to update the subscription. Typically a manager for the plan provider.

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

request_key
string

Examples

GET /api/metrics/cowork/active?o=created_at&ot=desc
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2016-01-14T23:16:55Z",
      "ends_at": "2017-01-14T23:16:55Z",
      "description": null,
      "organization": {
        "slug": "xia",
        "printable_name": "Xia Lee"
      },
      "plan": {
        "slug": "open-space",
        "title": "Open Space",
        "description": "open space desk, High speed internet- Ethernet or WiFi, Unlimited printing,Unlimited scanning, Unlimited fax service(send and receive)",
        "is_active": true,
        "setup_amount": 0,
        "period_amount": 17999,
        "interval": 4,
        "app_url": "http://localhost:8020/app"
      },
      "auto_renew": true
    }
  ]
}

Retrieves a default balance sheet

GET /api/metrics/{organization}/balances/
        

Generate a table of revenue (rows) per months (columns) for a default balance sheet (Income, Backlog, Receivable).

Query parameters
page
integer

A page number within the paginated result set.

Responses

200

scale
number

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)

unit
string

Three-letter ISO 4217 code for currency unit (ex: usd)

title
string

Title for the table

table
array

key
string

Unique key in the table for the data series

selector
string

Filter on the Transaction accounts

values
array

Datapoints in the serie

Examples

GET /api/metrics/cowork/balances
responds
{
  "title": "Balances",
  "scale": 0.01,
  "unit": "usd",
  "table": [
    {
      "key": "Income",
      "values": [
        [
          "2014-09-01T00:00:00Z",
          0
        ],
        [
          "2014-10-01T00:00:00Z",
          1532624
        ],
        [
          "2014-11-01T00:00:00Z",
          2348340
        ],
        [
          "2014-12-01T00:00:00Z",
          3244770
        ],
        [
          "2015-01-01T00:00:00Z",
          5494221
        ],
        [
          "2015-02-01T00:00:00Z",
          7214221
        ],
        [
          "2015-03-01T00:00:00Z",
          8444221
        ],
        [
          "2015-04-01T00:00:00Z",
          9784221
        ],
        [
          "2015-05-01T00:00:00Z",
          12784221
        ],
        [
          "2015-06-01T00:00:00Z",
          14562341
        ],
        [
          "2015-07-01T00:00:00Z",
          16567341
        ],
        [
          "2015-08-01T00:00:00Z",
          17893214
        ],
        [
          "2015-08-06T02:24:50.485Z",
          221340
        ]
      ]
    },
    {
      "key": "Backlog",
      "values": [
        [
          "2014-09-01T00:00:00Z",
          1712624
        ],
        [
          "2014-10-01T00:00:00Z",
          3698340
        ],
        [
          "2014-11-01T00:00:00Z",
          7214770
        ],
        [
          "2014-12-01T00:00:00Z",
          10494221
        ],
        [
          "2015-01-01T00:00:00Z",
          14281970
        ],
        [
          "2015-02-01T00:00:00Z",
          18762845
        ],
        [
          "2015-03-01T00:00:00Z",
          24258765
        ],
        [
          "2015-04-01T00:00:00Z",
          31937741
        ],
        [
          "2015-05-01T00:00:00Z",
          43002401
        ],
        [
          "2015-06-01T00:00:00Z",
          53331444
        ],
        [
          "2015-07-01T00:00:00Z",
          64775621
        ],
        [
          "2015-08-01T00:00:00Z",
          75050033
        ],
        [
          "2015-08-06T02:24:50.485Z",
          89156321
        ]
      ]
    },
    {
      "key": "Receivable",
      "values": [
        [
          "2014-09-01T00:00:00Z",
          0
        ],
        [
          "2014-10-01T00:00:00Z",
          0
        ],
        [
          "2014-11-01T00:00:00Z",
          0
        ],
        [
          "2014-12-01T00:00:00Z",
          0
        ],
        [
          "2015-01-01T00:00:00Z",
          0
        ],
        [
          "2015-02-01T00:00:00Z",
          0
        ],
        [
          "2015-03-01T00:00:00Z",
          0
        ],
        [
          "2015-04-01T00:00:00Z",
          0
        ],
        [
          "2015-05-01T00:00:00Z",
          0
        ],
        [
          "2015-06-01T00:00:00Z",
          0
        ],
        [
          "2015-07-01T00:00:00Z",
          0
        ],
        [
          "2015-08-01T00:00:00Z",
          0
        ],
        [
          "2015-08-06T02:24:50.485Z",
          0
        ]
      ]
    }
  ]
}

Lists churned subscriptions

GET /api/metrics/{organization}/churned/
        

Lists all Subscription to a plan whose provider is :organization which have ended already.

The queryset can be further filtered to a range of dates between start_at and ends_at.

The queryset can be further filtered by passing a q parameter. The result queryset can be ordered.

Query parameters
page
integer

A page number within the paginated result set.

o
string

Which field to use when ordering the results.

q
string

A search term.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

Date/time of creation (in ISO format)

ends_at
string

Date/time when the subscription period currently ends (in ISO format)

description
string

Free-form text description for the subscription

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

plan
object

slug
string

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period for the subscription

app_url
string

advance_discount
integer

Incremental discount for payment of multiple periods (in %%).

unit
string

organization
string

Provider of the plan

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Natural period length of a subscription to the plan (monthly, yearly, etc.)

renewal_type
string

Natural period for the subscription

is_not_priced
boolean

created_at
string

skip_optin_on_grant
boolean

True when a subscriber can automatically be subscribed to the plan by its provider. Otherwise the subscriber must manually accept the subscription. (defaults to False)

optin_on_request
boolean

True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)

auto_renew
boolean

The subscription is set to auto-renew at the end of the period

editable
string

True if the request user is able to update the subscription. Typically a manager for the plan provider.

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

request_key
string

Examples

GET /api/metrics/cowork/churned?o=created_at&ot=desc
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2016-01-14T23:16:55Z",
      "ends_at": "2017-01-14T23:16:55Z",
      "description": null,
      "organization": {
        "slug": "xia",
        "printable_name": "Xia Lee"
      },
      "plan": {
        "slug": "open-space",
        "title": "Open Space",
        "description": "open space desk, High speed internet- Ethernet or WiFi, Unlimited printing,Unlimited scanning, Unlimited fax service(send and receive)",
        "is_active": true,
        "setup_amount": 0,
        "period_amount": 17999,
        "interval": 4,
        "app_url": "http://localhost:8020/app"
      },
      "auto_renew": true
    }
  ]
}

Retrieves performance of a discount code

GET /api/metrics/{organization}/coupons/{coupon}/
        

Queries a page (PAGE_SIZE records) of Coupon usage.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

The result queryset can be ordered by passing an o (field name) and ot (asc or desc) parameter.

Query parameters
o
string

Which field to use when ordering the results.

q
string

A search term.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

Date/time of creation (in ISO format)

user
object required

slug
string

Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.

email
string

E-mail address for the user

full_name
string

Full name for the contact (effectively first name followed by last name)

created_at
string

Date/time of creation (in ISO format)

plan
string

option
integer

full_name
string

Full name of the person that will benefit from the subscription (GroupBuy)

sync_on
string

Examples

GET /api/metrics/cowork/coupons/DIS100/
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "user": {
        "slug": "xia",
        "email": "xia@localhost.localdomain",
        "full_name": "Xia Doe",
        "created_at": "2012-09-14T23:16:55Z"
      },
      "plan": "basic",
      "created_at": "2014-01-01T09:00:00Z"
    }
  ]
}

Retrieves 12-month trailing customer counts

GET /api/metrics/{organization}/customers/
        
Query parameters
page
integer

A page number within the paginated result set.

Responses

200

scale
number

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)

unit
string

Three-letter ISO 4217 code for currency unit (ex: usd)

title
string

Title for the table

table
array

key
string

Unique key in the table for the data series

selector
string

Filter on the Transaction accounts

values
array

Datapoints in the serie

Examples

GET /api/metrics/cowork/customers
responds
{
  "title": "Customers",
  "table": [
    {
      "key": "Total # of Customers",
      "values": [
        [
          "2014-10-01T00:00:00Z",
          15
        ],
        [
          "2014-11-01T00:00:00Z",
          17
        ],
        [
          "2014-12-01T00:00:00Z",
          19
        ],
        [
          "2015-01-01T00:00:00Z",
          19
        ],
        [
          "2015-02-01T00:00:00Z",
          25
        ],
        [
          "2015-03-01T00:00:00Z",
          29
        ],
        [
          "2015-04-01T00:00:00Z",
          37
        ],
        [
          "2015-05-01T00:00:00Z",
          43
        ],
        [
          "2015-06-01T00:00:00Z",
          46
        ],
        [
          "2015-07-01T00:00:00Z",
          48
        ],
        [
          "2015-08-01T00:00:00Z",
          54
        ],
        [
          "2015-08-06T05:20:24.537Z",
          60
        ]
      ]
    },
    {
      "key": "# of new Customers",
      "values": [
        [
          "2014-10-01T00:00:00Z",
          2
        ],
        [
          "2014-11-01T00:00:00Z",
          2
        ],
        [
          "2014-12-01T00:00:00Z",
          0
        ],
        [
          "2015-01-01T00:00:00Z",
          6
        ],
        [
          "2015-02-01T00:00:00Z",
          4
        ],
        [
          "2015-03-01T00:00:00Z",
          8
        ],
        [
          "2015-04-01T00:00:00Z",
          6
        ],
        [
          "2015-05-01T00:00:00Z",
          3
        ],
        [
          "2015-06-01T00:00:00Z",
          2
        ],
        [
          "2015-07-01T00:00:00Z",
          6
        ],
        [
          "2015-08-01T00:00:00Z",
          7
        ],
        [
          "2015-08-06T05:20:24.537Z",
          0
        ]
      ]
    },
    {
      "key": "# of churned Customers",
      "values": [
        [
          "2014-10-01T00:00:00Z",
          0
        ],
        [
          "2014-11-01T00:00:00Z",
          0
        ],
        [
          "2014-12-01T00:00:00Z",
          0
        ],
        [
          "2015-01-01T00:00:00Z",
          0
        ],
        [
          "2015-02-01T00:00:00Z",
          0
        ],
        [
          "2015-03-01T00:00:00Z",
          0
        ],
        [
          "2015-04-01T00:00:00Z",
          0
        ],
        [
          "2015-05-01T00:00:00Z",
          0
        ],
        [
          "2015-06-01T00:00:00Z",
          0
        ],
        [
          "2015-07-01T00:00:00Z",
          0
        ],
        [
          "2015-08-01T00:00:00Z",
          1
        ],
        [
          "2015-08-06T05:20:24.537Z",
          60
        ]
      ]
    },
    {
      "key": "Net New Customers",
      "values": [
        [
          "2014-10-01T00:00:00Z",
          2
        ],
        [
          "2014-11-01T00:00:00Z",
          2
        ],
        [
          "2014-12-01T00:00:00Z",
          0
        ],
        [
          "2015-01-01T00:00:00Z",
          6
        ],
        [
          "2015-02-01T00:00:00Z",
          4
        ],
        [
          "2015-03-01T00:00:00Z",
          8
        ],
        [
          "2015-04-01T00:00:00Z",
          6
        ],
        [
          "2015-05-01T00:00:00Z",
          3
        ],
        [
          "2015-06-01T00:00:00Z",
          2
        ],
        [
          "2015-07-01T00:00:00Z",
          6
        ],
        [
          "2015-08-01T00:00:00Z",
          6
        ],
        [
          "2015-08-06T05:20:24.537Z",
          -60
        ]
      ]
    }
  ],
  "extra": [
    {
      "key": "% Customer Churn",
      "values": [
        [
          "2014-10-01T00:00:00Z",
          0
        ],
        [
          "2014-11-01T00:00:00Z",
          0.0
        ],
        [
          "2014-12-01T00:00:00Z",
          0.0
        ],
        [
          "2015-01-01T00:00:00Z",
          0.0
        ],
        [
          "2015-02-01T00:00:00Z",
          0.0
        ],
        [
          "2015-03-01T00:00:00Z",
          0.0
        ],
        [
          "2015-04-01T00:00:00Z",
          0.0
        ],
        [
          "2015-05-01T00:00:00Z",
          0.0
        ],
        [
          "2015-06-01T00:00:00Z",
          0.0
        ],
        [
          "2015-07-01T00:00:00Z",
          0.0
        ],
        [
          "2015-08-01T00:00:00Z",
          2.08
        ],
        [
          "2015-08-06T05:20:24.537Z",
          111.11
        ]
      ]
    }
  ]
}

Retrieves 12-month trailing revenue

GET /api/metrics/{organization}/funds/
        

Produces sales, payments and refunds over a period of time.

Query parameters
page
integer

A page number within the paginated result set.

Responses

200

scale
number

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)

unit
string

Three-letter ISO 4217 code for currency unit (ex: usd)

title
string

Title for the table

table
array

key
string

Unique key in the table for the data series

selector
string

Filter on the Transaction accounts

values
array

Datapoints in the serie

Examples

GET /api/metrics/cowork/funds/
responds
{
  "title": "Amount",
  "scale": 0.01,
  "unit": "usd",
  "table": [
    {
      "key": "Total Sales",
      "values": [
        [
          "2014-10-01T00:00:00Z",
          1985716
        ],
        [
          "2014-11-01T00:00:00Z",
          3516430
        ],
        [
          "2014-12-01T00:00:00Z",
          3279451
        ],
        [
          "2015-01-01T00:00:00Z",
          3787749
        ],
        [
          "2015-02-01T00:00:00Z",
          4480875
        ],
        [
          "2015-03-01T00:00:00Z",
          5495920
        ],
        [
          "2015-04-01T00:00:00Z",
          7678976
        ],
        [
          "2015-05-01T00:00:00Z",
          11064660
        ],
        [
          "2015-06-01T00:00:00Z",
          10329043
        ],
        [
          "2015-07-01T00:00:00Z",
          11444177
        ],
        [
          "2015-08-01T00:00:00Z",
          10274412
        ],
        [
          "2015-08-06T04:59:14.721Z",
          14106288
        ]
      ]
    },
    {
      "key": "New Sales",
      "values": [
        [
          "2014-10-01T00:00:00Z",
          0
        ],
        [
          "2014-11-01T00:00:00Z",
          0
        ],
        [
          "2014-12-01T00:00:00Z",
          0
        ],
        [
          "2015-01-01T00:00:00Z",
          0
        ],
        [
          "2015-02-01T00:00:00Z",
          0
        ],
        [
          "2015-03-01T00:00:00Z",
          0
        ],
        [
          "2015-04-01T00:00:00Z",
          0
        ],
        [
          "2015-05-01T00:00:00Z",
          0
        ],
        [
          "2015-06-01T00:00:00Z",
          0
        ],
        [
          "2015-07-01T00:00:00Z",
          0
        ],
        [
          "2015-08-01T00:00:00Z",
          0
        ],
        [
          "2015-08-06T04:59:14.721Z",
          0
        ]
      ]
    },
    {
      "key": "Churned Sales",
      "values": [
        [
          "2014-10-01T00:00:00Z",
          0
        ],
        [
          "2014-11-01T00:00:00Z",
          0
        ],
        [
          "2014-12-01T00:00:00Z",
          0
        ],
        [
          "2015-01-01T00:00:00Z",
          0
        ],
        [
          "2015-02-01T00:00:00Z",
          0
        ],
        [
          "2015-03-01T00:00:00Z",
          0
        ],
        [
          "2015-04-01T00:00:00Z",
          0
        ],
        [
          "2015-05-01T00:00:00Z",
          0
        ],
        [
          "2015-06-01T00:00:00Z",
          0
        ],
        [
          "2015-07-01T00:00:00Z",
          0
        ],
        [
          "2015-08-01T00:00:00Z",
          0
        ],
        [
          "2015-08-06T04:59:14.721Z",
          0
        ]
      ]
    },
    {
      "key": "Payments",
      "values": [
        [
          "2014-10-01T00:00:00Z",
          1787144
        ],
        [
          "2014-11-01T00:00:00Z",
          3164787
        ],
        [
          "2014-12-01T00:00:00Z",
          2951505
        ],
        [
          "2015-01-01T00:00:00Z",
          3408974
        ],
        [
          "2015-02-01T00:00:00Z",
          4032787
        ],
        [
          "2015-03-01T00:00:00Z",
          4946328
        ],
        [
          "2015-04-01T00:00:00Z",
          6911079
        ],
        [
          "2015-05-01T00:00:00Z",
          9958194
        ],
        [
          "2015-06-01T00:00:00Z",
          9296138
        ],
        [
          "2015-07-01T00:00:00Z",
          10299759
        ],
        [
          "2015-08-01T00:00:00Z",
          9246970
        ],
        [
          "2015-08-06T04:59:14.721Z",
          12695659
        ]
      ]
    },
    {
      "key": "Refunds",
      "values": [
        [
          "2014-10-01T00:00:00Z",
          0
        ],
        [
          "2014-11-01T00:00:00Z",
          0
        ],
        [
          "2014-12-01T00:00:00Z",
          0
        ],
        [
          "2015-01-01T00:00:00Z",
          0
        ],
        [
          "2015-02-01T00:00:00Z",
          0
        ],
        [
          "2015-03-01T00:00:00Z",
          0
        ],
        [
          "2015-04-01T00:00:00Z",
          0
        ],
        [
          "2015-05-01T00:00:00Z",
          0
        ],
        [
          "2015-06-01T00:00:00Z",
          0
        ],
        [
          "2015-07-01T00:00:00Z",
          0
        ],
        [
          "2015-08-01T00:00:00Z",
          0
        ],
        [
          "2015-08-06T04:59:14.721Z",
          0
        ]
      ]
    }
  ]
}

Retrieves 12-month trailing plans performance

GET /api/metrics/{organization}/plans/
        
Query parameters
page
integer

A page number within the paginated result set.

Responses

200

scale
number

The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)

unit
string

Three-letter ISO 4217 code for currency unit (ex: usd)

title
string

Title for the table

table
array

key
string

Unique key in the table for the data series

selector
string

Filter on the Transaction accounts

values
array

Datapoints in the serie

Examples

GET /api/metrics/cowork/plans
responds
{
  "title": "Active Subscribers",
  "table": [
    {
      "is_active": true,
      "key": "open-space",
      "location": "/profile/plan/open-space/",
      "values": [
        [
          "2014-09-01T00:00:00Z",
          4
        ],
        [
          "2014-10-01T00:00:00Z",
          5
        ],
        [
          "2014-11-01T00:00:00Z",
          6
        ],
        [
          "2014-12-01T00:00:00Z",
          6
        ],
        [
          "2015-01-01T00:00:00Z",
          6
        ],
        [
          "2015-02-01T00:00:00Z",
          9
        ],
        [
          "2015-03-01T00:00:00Z",
          9
        ],
        [
          "2015-04-01T00:00:00Z",
          9
        ],
        [
          "2015-05-01T00:00:00Z",
          11
        ],
        [
          "2015-06-01T00:00:00Z",
          11
        ],
        [
          "2015-07-01T00:00:00Z",
          14
        ],
        [
          "2015-08-01T00:00:00Z",
          16
        ],
        [
          "2015-08-06T05:37:50.004Z",
          16
        ]
      ]
    },
    {
      "is_active": true,
      "key": "open-plus",
      "location": "/profile/plan/open-plus/",
      "values": [
        [
          "2014-09-01T00:00:00Z",
          7
        ],
        [
          "2014-10-01T00:00:00Z",
          8
        ],
        [
          "2014-11-01T00:00:00Z",
          9
        ],
        [
          "2014-12-01T00:00:00Z",
          9
        ],
        [
          "2015-01-01T00:00:00Z",
          12
        ],
        [
          "2015-02-01T00:00:00Z",
          13
        ],
        [
          "2015-03-01T00:00:00Z",
          18
        ],
        [
          "2015-04-01T00:00:00Z",
          19
        ],
        [
          "2015-05-01T00:00:00Z",
          19
        ],
        [
          "2015-06-01T00:00:00Z",
          20
        ],
        [
          "2015-07-01T00:00:00Z",
          23
        ],
        [
          "2015-08-01T00:00:00Z",
          25
        ],
        [
          "2015-08-06T05:37:50.014Z",
          25
        ]
      ]
    },
    {
      "is_active": true,
      "key": "private",
      "location": "/profile/plan/private/",
      "values": [
        [
          "2014-09-01T00:00:00Z",
          3
        ],
        [
          "2014-10-01T00:00:00Z",
          3
        ],
        [
          "2014-11-01T00:00:00Z",
          3
        ],
        [
          "2014-12-01T00:00:00Z",
          3
        ],
        [
          "2015-01-01T00:00:00Z",
          6
        ],
        [
          "2015-02-01T00:00:00Z",
          7
        ],
        [
          "2015-03-01T00:00:00Z",
          10
        ],
        [
          "2015-04-01T00:00:00Z",
          15
        ],
        [
          "2015-05-01T00:00:00Z",
          16
        ],
        [
          "2015-06-01T00:00:00Z",
          17
        ],
        [
          "2015-07-01T00:00:00Z",
          17
        ],
        [
          "2015-08-01T00:00:00Z",
          18
        ],
        [
          "2015-08-06T05:37:50.023Z",
          18
        ]
      ]
    }
  ],
  "extra": [
    {
      "key": "churn",
      "values": [
        [
          "2014-09-01T00:00:00Z",
          0
        ],
        [
          "2014-10-01T00:00:00Z",
          0
        ],
        [
          "2014-11-01T00:00:00Z",
          0
        ],
        [
          "2014-12-01T00:00:00Z",
          0
        ],
        [
          "2015-01-01T00:00:00Z",
          0
        ],
        [
          "2015-02-01T00:00:00Z",
          0
        ],
        [
          "2015-03-01T00:00:00Z",
          0
        ],
        [
          "2015-04-01T00:00:00Z",
          0
        ],
        [
          "2015-05-01T00:00:00Z",
          0
        ],
        [
          "2015-06-01T00:00:00Z",
          0
        ],
        [
          "2015-07-01T00:00:00Z",
          0
        ],
        [
          "2015-08-01T00:00:00Z",
          1
        ],
        [
          "2015-08-06T05:37:50.031Z",
          1
        ]
      ]
    }
  ]
}

Retrieves recently active users

GET /api/proxy/recent/
        
Query parameters
page
integer

A page number within the paginated result set.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

printable_name
string

descr
string

created_at
string

slug
string

Examples

GET /api/proxy/recent/
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "printable_name": "Alice Cooper",
      "descr": "recently logged in",
      "created_at": "2019-07-15T20:40:29.509572Z",
      "slug": "alice"
    }
  ]
}

Retrieves news and items to take care of.

GET /api/todos/
        
Query parameters
page
integer

A page number within the paginated result set.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

Date/time of creation (in ISO format)

created_by
string

User that created the activity

text
string

Free form text description of the activity

account
string

Account the activity is associated to

Examples

GET /api/todos/
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {}
  ]
}

Searches billing and login profiles

GET /api/accounts/
        

Queries a page (PAGE_SIZE records) of organization and user profiles.

The queryset can be filtered for at least one field to match a search term (q).

The queryset can be ordered by a field by adding an HTTP query parameter o= followed by the field name. A sequence of fields can be used to create a complete ordering by adding a sequence of o HTTP query parameters. To reverse the natural order of a field, prefix the field name by a minus (-) sign.

Query parameters
page
integer

A page number within the paginated result set.

q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

Examples

GET /api/accounts/?o=created_at
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "full_name": "Xia Lee",
      "email": "xia@localhost.localdomain",
      "created_at": "2016-01-14T23:16:55Z",
      "printable_name": "Xia Lee"
    }
  ]
}

Searches billing profiles

GET /api/accounts/profiles/
        

Queries a page (PAGE_SIZE records) of candidate profiles based of a search criteria (q).

This API differs from /api/profile in that it is designed to be used in auto-completion input fields instead of designed to list all profiles.

The queryset can be ordered by a field by adding an HTTP query parameter o= followed by the field name. A sequence of fields can be used to create a complete ordering by adding a sequence of o HTTP query parameters. To reverse the natural order of a field, prefix the field name by a minus (-) sign.

Query parameters
page
integer

A page number within the paginated result set.

q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

Examples

GET /api/accounts/profile/?q=xia
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "full_name": "Xia Lee",
      "email": "xia@localhost.localdomain",
      "created_at": "2016-01-14T23:16:55Z",
      "printable_name": "Xia Lee"
    }
  ]
}

Searches login profiles

GET /api/accounts/users/
        

Queries a page (PAGE_SIZE records) of User.

The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).

Query results can be ordered by natural fields (o) in either ascending or descending order (ot).

Query parameters
page
integer

A page number within the paginated result set.

o
string

Which field to use when ordering the results.

q
string

A search term.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

slug
string

Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.

email
string

E-mail address for the user

full_name
string

Full name for the contact (effectively first name followed by last name)

created_at
string

Date/time of creation (in ISO format)

Examples

GET /api/users/?o=created_at&ot=desc
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "alice",
      "email": "alice@djaodjin.com",
      "full_name": "Alice Cooper",
      "created_at": "2014-01-01T00:00:00Z"
    }
  ]
}

Creates a user profile

POST /api/contacts/
        
Request body
picture
string

Profile picture

email
string required

E-mail address

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the contact

extra
string

Extra meta data (can be stringify JSON)

Responses

200

slug
string

Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.

printable_name
string

picture
string

Profile picture

email
string

E-mail address

created_at
string

Date/time of creation (in ISO format)

credentials
string

True if the user has valid login credentials

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the contact

extra
string

Extra meta data (can be stringify JSON)

activities
array

created_at
string

Date/time of creation (in ISO format)

created_by
string

User that created the activity

text
string

Free form text description of the activity

account
string

Account the activity is associated to

Examples

POST /api/users/
{
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "nick_name": "Xia"
}
responds
{
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "nick_name": "Xia"
}

Updates a login profile

PUT /api/contacts/{user}/
        
Request body
picture
string

Profile picture

email
string required

E-mail address

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the contact

extra
string

Extra meta data (can be stringify JSON)

Responses

200

slug
string

Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.

printable_name
string

picture
string

Profile picture

email
string

E-mail address

created_at
string

Date/time of creation (in ISO format)

credentials
string

True if the user has valid login credentials

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the contact

extra
string

Extra meta data (can be stringify JSON)

activities
array

created_at
string

Date/time of creation (in ISO format)

created_by
string

User that created the activity

text
string

Free form text description of the activity

account
string

Account the activity is associated to

Examples

PUT /api/users/xia/
{
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "nick_name": "Xia"
}
responds
{
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "nick_name": "Xia"
}

Deletes a login profile

DELETE /api/contacts/{user}/
        
Responses

204

Examples

DELETE /api/users/xia/

Lists activities for a contact

GET /api/contacts/{user}/activities/
        

Returns PAGE_SIZE activity records for a user.

Query parameters
page
integer

A page number within the paginated result set.

q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

Date/time of creation (in ISO format)

created_by
string

User that created the activity

text
string

Free form text description of the activity

account
string

Account the activity is associated to

Examples

GET /api/contacts/xia/activities
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2018-01-01T00:00:00Z",
      "created_by": "alice",
      "text": "Phone call",
      "account": null
    },
    {
      "created_at": "2018-01-02T00:00:00Z",
      "created_by": "alice",
      "text": "Follow up e-mail",
      "account": "cowork"
    }
  ]
}

Records new activity with a contact

POST /api/contacts/{user}/activities/
        
Request body
text
string

Free form text description of the activity

account
string required

Account the activity is associated to

Responses

200

created_at
string

Date/time of creation (in ISO format)

created_by
string

User that created the activity

text
string

Free form text description of the activity

account
string

Account the activity is associated to

Examples

POST /api/contacts/xia/activities/
{
  "text": "Phone call",
  "account": null
}
responds
{
  "text": "Phone call",
  "account": null
}

Signs a consent agreement

POST /api/legal/{agreement}/sign/
        

Indicates the request user has signed the required consent agreement.

Request body
read_terms
boolean required

I have read and understand these terms and conditions

Responses

200

read_terms
boolean

I have read and understand these terms and conditions

last_signed
string

Examples

POST /api/legal/terms-of-use/sign/
{
  "read_terms": true
}
responds
{
  "read_terms": true,
  "last_signed": "2019-01-01T00:00:00Z"
}

Lists billing profiles

GET /api/profile/
        

Queries a page (PAGE_SIZE records) of organization and user profiles.

The queryset can be filtered for at least one field to match a search term (q).

The queryset can be ordered by a field by adding an HTTP query parameter o= followed by the field name. A sequence of fields can be used to create a complete ordering by adding a sequence of o HTTP query parameters. To reverse the natural order of a field, prefix the field name by a minus (-) sign.

Query parameters
page
integer

A page number within the paginated result set.

q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

Examples

GET /api/profile/?o=created_at&ot=desc
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "full_name": "Xia Lee",
      "email": "xia@localhost.localdomain",
      "created_at": "2016-01-14T23:16:55Z",
      "printable_name": "Xia Lee"
    }
  ]
}

Creates a billing profile

POST /api/profile/
        
Request body
slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

default_timezone
string

Timezone to use when reporting metrics

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

extra
string

Extra meta data (can be stringify JSON)

type
string

One of 'organization', 'personal' or 'user'

Responses

200

Examples

POST /api/profile/
{
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee"
}

Retrieves a billing profile

GET /api/profile/{organization}/
        
Responses

200

slug
string

Unique identifier shown in the URL bar

created_at
string

Date/time of creation (in ISO format)

full_name
string

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

printable_name
string

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

type
string

One of 'organization', 'personal' or 'user'

extra
string

Extra meta data (can be stringify JSON)

subscriptions
array

created_at
string

Date/time of creation (in ISO format)

ends_at
string

Date/time when the subscription period currently ends (in ISO format)

plan
string

auto_renew
boolean

The subscription is set to auto-renew at the end of the period

picture
string

Profile picture

Examples

GET /api/profile/xia/
responds
{
  "created_at": "2018-01-01T00:00:00Z",
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "printable_name": "Xia Lee",
  "slug": "xia",
  "phone": "555-555-5555",
  "street_address": "185 Berry St #550",
  "locality": "San Francisco",
  "region": "CA",
  "postal_code": "",
  "country": "US",
  "default_timezone": "Europe/Kiev",
  "is_provider": false,
  "is_bulk_buyer": false,
  "type": "",
  "picture": "",
  "subscriptions": [
    {
      "created_at": "2018-01-01T00:00:00Z",
      "ends_at": "2019-01-01T00:00:00Z",
      "plan": "open-space",
      "auto_renew": true
    }
  ]
}

Updates a billing profile

PUT /api/profile/{organization}/
        
Request body
slug
string

Unique identifier shown in the URL bar

full_name
string required

Full name

email
string required

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

Responses

200

slug
string

Unique identifier shown in the URL bar

created_at
string

Date/time of creation (in ISO format)

full_name
string

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

printable_name
string

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

type
string

One of 'organization', 'personal' or 'user'

extra
string

Extra meta data (can be stringify JSON)

subscriptions
array

created_at
string

Date/time of creation (in ISO format)

ends_at
string

Date/time when the subscription period currently ends (in ISO format)

plan
string

auto_renew
boolean

The subscription is set to auto-renew at the end of the period

picture
string

Profile picture

Examples

PUT /api/profile/xia/
{
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee"
}
responds
{
  "created_at": "2018-01-01T00:00:00Z",
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "printable_name": "Xia Lee",
  "slug": "xia",
  "subscriptions": [
    {
      "created_at": "2018-01-01T00:00:00Z",
      "ends_at": "2019-01-01T00:00:00Z",
      "plan": "open-space",
      "auto_renew": true
    }
  ]
}

Deletes a billing profile

DELETE /api/profile/{organization}/
        

We anonymize the organization instead of purely deleting it from the database because we don't want to loose history on subscriptions and transactions.

Responses

204

Examples

DELETE /api/profile/xia/

Lists user profiles

GET /api/users/
        

Queries a page (PAGE_SIZE records) of organization and user profiles.

The queryset can be filtered for at least one field to match a search term (q).

The queryset can be ordered by a field by adding an HTTP query parameter o= followed by the field name. A sequence of fields can be used to create a complete ordering by adding a sequence of o HTTP query parameters. To reverse the natural order of a field, prefix the field name by a minus (-) sign.

Query parameters
page
integer

A page number within the paginated result set.

q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

slug
string

Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.

printable_name
string

picture
string

Profile picture

email
string

E-mail address

created_at
string

Date/time of creation (in ISO format)

credentials
string

True if the user has valid login credentials

Examples

GET /api/users/?q=xia
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "email": "xia@locahost.localdomain",
      "full_name": "Xia Lee",
      "nick_name": "Xia",
      "created_at": "2018-01-01T00:00:00Z",
      "activities": [
        {
          "created_at": "2018-01-01T00:00:00Z",
          "created_by": "alice",
          "text": "Phone call",
          "account": null
        },
        {
          "created_at": "2018-01-02T00:00:00Z",
          "created_by": "alice",
          "text": "Follow up e-mail",
          "account": "cowork"
        }
      ]
    }
  ]
}

Creates a user profile

POST /api/users/
        
Request body
picture
string

Profile picture

email
string required

E-mail address

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the contact

extra
string

Extra meta data (can be stringify JSON)

Responses

200

slug
string

Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.

printable_name
string

picture
string

Profile picture

email
string

E-mail address

created_at
string

Date/time of creation (in ISO format)

credentials
string

True if the user has valid login credentials

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the contact

extra
string

Extra meta data (can be stringify JSON)

activities
array

created_at
string

Date/time of creation (in ISO format)

created_by
string

User that created the activity

text
string

Free form text description of the activity

account
string

Account the activity is associated to

Examples

POST /api/users/
{
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "nick_name": "Xia"
}
responds
{
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "nick_name": "Xia"
}

Retrieves a login profile

GET /api/users/{user}/
        

Retrieves details on one single user profile with slug {user}.

Responses

200

slug
string

Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.

printable_name
string

picture
string

Profile picture

email
string

E-mail address

created_at
string

Date/time of creation (in ISO format)

credentials
string

True if the user has valid login credentials

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the contact

extra
string

Extra meta data (can be stringify JSON)

activities
array

created_at
string

Date/time of creation (in ISO format)

created_by
string

User that created the activity

text
string

Free form text description of the activity

account
string

Account the activity is associated to

Examples

GET /api/users/xia
responds
{
  "slug": "xia",
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "nick_name": "Xia",
  "created_at": "2018-01-01T00:00:00Z",
  "activities": [
    {
      "created_at": "2018-01-01T00:00:00Z",
      "created_by": "alice",
      "text": "Phone call",
      "account": null
    },
    {
      "created_at": "2018-01-02T00:00:00Z",
      "created_by": "alice",
      "text": "Follow up e-mail",
      "account": "cowork"
    }
  ]
}

Updates a login profile

PUT /api/users/{user}/
        
Request body
picture
string

Profile picture

email
string required

E-mail address

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the contact

extra
string

Extra meta data (can be stringify JSON)

Responses

200

slug
string

Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.

printable_name
string

picture
string

Profile picture

email
string

E-mail address

created_at
string

Date/time of creation (in ISO format)

credentials
string

True if the user has valid login credentials

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the contact

extra
string

Extra meta data (can be stringify JSON)

activities
array

created_at
string

Date/time of creation (in ISO format)

created_by
string

User that created the activity

text
string

Free form text description of the activity

account
string

Account the activity is associated to

Examples

PUT /api/users/xia/
{
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "nick_name": "Xia"
}
responds
{
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "nick_name": "Xia"
}

Deletes a login profile

DELETE /api/users/{user}/
        
Responses

204

Examples

DELETE /api/users/xia/

Changes a user notifications preferences

PUT /api/users/{user}/notifications/
        
Request body
notifications
array required

Responses

200

notifications
array

Examples

POST /api/users/donny/notifications/
{
  "notifications": [
    "user_registered_notice"
  ]
}
responds
{
  "notifications": [
    "user_registered_notice"
  ]
}

List billing profiles owned by user

GET /api/users/{user}/profiles/
        

Queries a page (PAGE_SIZE records) of organization and user profiles.

The queryset can be filtered for at least one field to match a search term (q).

The queryset can be ordered by a field by adding an HTTP query parameter o= followed by the field name. A sequence of fields can be used to create a complete ordering by adding a sequence of o HTTP query parameters. To reverse the natural order of a field, prefix the field name by a minus (-) sign.

Query parameters
page
integer

A page number within the paginated result set.

q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

Examples

GET /api/users/xia/profiles/?o=created_at
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "full_name": "Xia Lee",
      "email": "xia@localhost.localdomain",
      "printable_name": "Xia Lee",
      "created_at": "2016-01-14T23:16:55Z"
    }
  ]
}

Lists roles for an organization

GET /api/profile/{organization}/roles/
        
Query parameters
page
integer

A page number within the paginated result set.

q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

user
object required

slug
string

Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.

email
string

E-mail address for the user

full_name
string

Full name for the contact (effectively first name followed by last name)

created_at
string

Date/time of creation (in ISO format)

grant_key
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

role_description
object required

created_at
string

Date/time of creation (in ISO format)

title
string

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

slug
string

Unique identifier shown in the URL bar

is_global
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

accept_request_api_url
string

remove_api_url
string

Examples

GET /api/profile/cowork/roles/
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2018-01-01T00:00:00Z",
      "role_description": {
        "name": "Manager",
        "slug": "manager",
        "organization": {
          "slug": "cowork",
          "full_name": "ABC Corp.",
          "printable_name": "ABC Corp.",
          "created_at": "2018-01-01T00:00:00Z",
          "email": "support@localhost.localdomain"
        }
      },
      "user": {
        "slug": "alice",
        "email": "alice@localhost.localdomain",
        "full_name": "Alice Doe",
        "created_at": "2018-01-01T00:00:00Z"
      },
      "request_key": "1",
      "grant_key": null
    }
  ]
}

Lists role types

GET /api/profile/{organization}/roles/describe/
        

Lists roles by description``RoleDescription``.

see Flexible Security Framework.

Query parameters
page
integer

A page number within the paginated result set.

Responses

200

Examples

GET /api/profile/cowork/roles/describe/

Creates a role type

POST /api/profile/{organization}/roles/describe/
        

Creates a role that users can take on an organization.

see Flexible Security Framework.

Request body
title
string required

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

Responses

200

created_at
string

Date/time of creation (in ISO format)

title
string

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

slug
string

Unique identifier shown in the URL bar

is_global
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

Examples

POST /api/profile/cowork/roles/describe/
{
  "title": "Managers"
}
responds
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2018-01-01T00:00:00Z",
      "title": "Managers",
      "slug": "manager",
      "is_global": true,
      "roles": [
        {
          "created_at": "2018-01-01T00:00:00Z",
          "user": {
            "slug": "donny",
            "email": "donny@localhost.localdomain",
            "full_name": "Donny Cooper",
            "created_at": "2018-01-01T00:00:00Z"
          },
          "request_key": null,
          "grant_key": null
        }
      ]
    },
    {
      "created_at": "2018-01-01T00:00:00Z",
      "title": "Contributors",
      "slug": "contributor",
      "is_global": false,
      "roles": []
    }
  ]
}

Retrieves a role type

GET /api/profile/{organization}/roles/describe/{role}/
        
Responses

200

created_at
string

Date/time of creation (in ISO format)

title
string

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

slug
string

Unique identifier shown in the URL bar

is_global
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

Examples

GET /api/profile/cowork/roles/describe/manager
responds
{
  "created_at": "2018-01-01T00:00:00Z",
  "slug": "manager",
  "title": "Profile Managers",
  "is_global": true,
  "roles": [
    {
      "created_at": "2018-01-01T00:00:00Z",
      "user": {
        "slug": "donny",
        "email": "donny@localhost.localdomain",
        "full_name": "Donny Cooper",
        "created_at": "2018-01-01T00:00:00Z"
      },
      "request_key": null,
      "grant_key": null
    }
  ]
}

Updates a role type

PUT /api/profile/{organization}/roles/describe/{role}/
        
Request body
title
string required

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

Responses

200

created_at
string

Date/time of creation (in ISO format)

title
string

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

slug
string

Unique identifier shown in the URL bar

is_global
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

Examples

PUT /api/profile/cowork/roles/describe/manager
{
  "title": "Profile managers"
}
responds
{
  "created_at": "2018-01-01T00:00:00Z",
  "title": "Profile managers",
  "slug": "manager",
  "is_global": true,
  "roles": [
    {
      "created_at": "2018-01-01T00:00:00Z",
      "user": {
        "slug": "donny",
        "email": "donny@localhost.localdomain",
        "full_name": "Donny Cooper",
        "created_at": "2018-01-01T00:00:00Z"
      },
      "request_key": null,
      "grant_key": null
    }
  ]
}

Deletes a role type

DELETE /api/profile/{organization}/roles/describe/{role}/
        
Responses

204

Examples

DELETE /api/profile/cowork/roles/describe/manager

Lists roles of a specific type

GET /api/profile/{organization}/roles/{role}/
        

Lists the specified role assignments for an organization.

Query parameters
q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

user
object required

slug
string

Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.

email
string

E-mail address for the user

full_name
string

Full name for the contact (effectively first name followed by last name)

created_at
string

Date/time of creation (in ISO format)

grant_key
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

role_description
object required

created_at
string

Date/time of creation (in ISO format)

title
string

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

slug
string

Unique identifier shown in the URL bar

is_global
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

accept_request_api_url
string

remove_api_url
string

Examples

GET /api/profile/cowork/roles/manager/
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2018-01-01T00:00:00Z",
      "role_description": {
        "name": "Manager",
        "slug": "manager",
        "organization": {
          "slug": "cowork",
          "full_name": "ABC Corp.",
          "printable_name": "ABC Corp.",
          "created_at": "2018-01-01T00:00:00Z",
          "email": "support@localhost.localdomain"
        }
      },
      "user": {
        "slug": "alice",
        "email": "alice@localhost.localdomain",
        "full_name": "Alice Doe",
        "created_at": "2018-01-01T00:00:00Z"
      },
      "request_key": "1",
      "grant_key": null
    }
  ]
}

Creates a role

POST /api/profile/{organization}/roles/{role}/
        

Attaches a user to a role on an organization, typically granting permissions to the user with regards to managing an organization profile (see Flexible Security Framework).

Request body
slug
string

Username

email
string

E-mail of the invitee

full_name
string

Full name

message
string

Message to send along the invitation

Responses

200

created_at
string

user
object required

slug
string

Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.

email
string

E-mail address for the user

full_name
string

Full name for the contact (effectively first name followed by last name)

created_at
string

Date/time of creation (in ISO format)

grant_key
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

role_description
object required

created_at
string

Date/time of creation (in ISO format)

title
string

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

slug
string

Unique identifier shown in the URL bar

is_global
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

accept_request_api_url
string

remove_api_url
string

Examples

POST /api/profile/cowork/roles/manager/
{
  "slug": "xia"
}
responds
{
  "slug": "xia"
}

Re-sends role invite

POST /api/profile/{organization}/roles/{role}/{user}/
        

Re-sends the invite e-mail that the user was granted a role on the organization.

Responses

200

created_at
string

user
object required

slug
string

Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.

email
string

E-mail address for the user

full_name
string

Full name for the contact (effectively first name followed by last name)

created_at
string

Date/time of creation (in ISO format)

grant_key
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

role_description
object required

created_at
string

Date/time of creation (in ISO format)

title
string

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

slug
string

Unique identifier shown in the URL bar

is_global
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

accept_request_api_url
string

remove_api_url
string

Examples

POST /api/profile/cowork/roles/manager/xia/
responds
{
  "created_at": "2018-01-01T00:00:00Z",
  "role_description": {
    "created_at": "2018-01-01T00:00:00Z",
    "title": "Profile Manager",
    "slug": "manager",
    "is_global": true,
    "organization": {
      "slug": "cowork",
      "full_name": "ABC Corp.",
      "printable_name": "ABC Corp.",
      "created_at": "2018-01-01T00:00:00Z",
      "email": "support@localhost.localdomain"
    }
  },
  "user": {
    "slug": "alice",
    "email": "alice@localhost.localdomain",
    "full_name": "Alice Doe",
    "created_at": "2018-01-01T00:00:00Z"
  },
  "request_key": "1",
  "grant_key": null
}

Deletes a role

DELETE /api/profile/{organization}/roles/{role}/{user}/
        

Dettach a user from one or all roles with regards to an organization, typically resulting in revoking permissions from this user to manage part of an organization profile.

Responses

204

Examples

DELETE /api/profile/cowork/roles/manager/xia/

Grants a subscription request

POST /api/profile/{organization}/subscribers/accept/{request_key}/
        

Accepts a subscription request.

Responses

200

created_at
string

Date/time of creation (in ISO format)

ends_at
string

Date/time when the subscription period currently ends (in ISO format)

description
string

Free-form text description for the subscription

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

plan
object

slug
string

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period for the subscription

app_url
string

advance_discount
integer

Incremental discount for payment of multiple periods (in %%).

unit
string

organization
string

Provider of the plan

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Natural period length of a subscription to the plan (monthly, yearly, etc.)

renewal_type
string

Natural period for the subscription

is_not_priced
boolean

created_at
string

skip_optin_on_grant
boolean

True when a subscriber can automatically be subscribed to the plan by its provider. Otherwise the subscriber must manually accept the subscription. (defaults to False)

optin_on_request
boolean

True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)

auto_renew
boolean

The subscription is set to auto-renew at the end of the period

editable
string

True if the request user is able to update the subscription. Typically a manager for the plan provider.

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

request_key
string

Examples

POST /api/profile/xia/subscribers/accept/a00000d0a0000001234567890123456789012345
responds
{
  "created_at": "2019-01-01T00:00:00Z",
  "ends_at": "2020-01-01T00:00:00Z",
  "description": null,
  "organization": {
    "slug": "xia",
    "created_at": "2019-01-01T00:00:00Z",
    "full_name": "Xia Lee",
    "email": "xia@localhost.localdomain",
    "phone": "555-555-5555",
    "street_address": "350 Bay St.",
    "locality": "San Francisco",
    "region": "CA",
    "postal_code": "94133",
    "country": "US",
    "default_timezone": "UTC",
    "printable_name": "Xia Lee",
    "is_provider": false,
    "is_bulk_buyer": false,
    "type": "personal",
    "credentials": true,
    "extra": null
  },
  "plan": {
    "slug": "open-space",
    "title": "Open Space",
    "description": "open space desk",
    "is_active": true,
    "setup_amount": 0,
    "period_amount": 17999,
    "period_length": 1,
    "interval": "monthly",
    "advance_discount": 0,
    "unit": "cad",
    "organization": "cowork",
    "renewal_type": "auto-renew",
    "is_not_priced": false,
    "created_at": "2019-01-01T00:00:00Z",
    "skip_optin_on_grant": false,
    "optin_on_request": false,
    "extra": null
  },
  "auto_renew": true,
  "editable": true,
  "extra": null,
  "grant_key": null,
  "request_key": null
}

Returns the URL endpoint to which requests passing the access rules

GET /api/proxy/
        

are forwarded to, and the format in which the session information is encoded.

When running tests, you can retrieve the actual session information for a specific user through the /proxy/sessions/{user}/ API call.

Responses

200

slug
string

unique identifier for the site (also serves as subdomain)

entry_point
string

Entry point to which requests will be redirected to

session_backend
String

Format to encode session in the forwarded HTTP request

authentication
string

Restricted authentication and registration

welcome_email
boolean

Send a welcome e-mail to newly registered users

Examples

GET /api/proxy/
responds
{
  "slug": "cowork",
  "entry_point": "https://cowork.herokuapp.com/",
  "session_backend": 1
}

Updates forward end-point

PUT /api/proxy/
        

Updates the URL endpoint to which requests passing the access rules are forwarded to and/or the format in which the session information is encoded.

Request body
entry_point
string

Entry point to which requests will be redirected to

session_backend
String

Format to encode session in the forwarded HTTP request

authentication
string

Restricted authentication and registration

welcome_email
boolean

Send a welcome e-mail to newly registered users

Responses

200

slug
string

unique identifier for the site (also serves as subdomain)

entry_point
string

Entry point to which requests will be redirected to

session_backend
String

Format to encode session in the forwarded HTTP request

authentication
string

Restricted authentication and registration

welcome_email
boolean

Send a welcome e-mail to newly registered users

Examples

PUT /api/proxy/
{
  "entry_point": "https://cowork.herokuapp.com/",
  "session_backend": 1
}
responds
{
  "slug": "cowork",
  "entry_point": "https://cowork.herokuapp.com/",
  "session_backend": 1
}

Retrieves users engagement

GET /api/proxy/engagement/
        
Query parameters
page
integer

A page number within the paginated result set.

Responses

200

engagements
array

slug
string

count
integer

active_users
integer

Examples

GET proxy/engagement/users/
responds
{
  "active_users": 10,
  "engagements": []
}

Retrieves engagement metrics

GET /api/proxy/engagement/users/
        
Query parameters
page
integer

A page number within the paginated result set.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

username
string

Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.

engagements
string

Examples

GET /api/proxy/engagement/users/
responds
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "username": "alice",
      "engagements": [
        "app",
        "profile"
      ]
    },
    {
      "username": "kenneth",
      "engagements": [
        "app",
        "billing"
      ]
    }
  ]
}

Rotates session encoding key

PUT /api/proxy/key/
        

Rotates the key used to encode the session information forwarded to the application entry point.

Responses

200

enc_key
string

Key used to decrypt the encoded session information.

Examples

PUT /api/proxy/key/
responds
{
  "enc_key": "********"
}

Lists access rules

GET /api/proxy/rules
        

Queries a page (PAGE_SIZE records) of Rule.

Query parameters
page
integer

A page number within the paginated result set.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

rank
integer

Determines the order in which rules are considered

path
string

OpenAPI path against which requests are matched

allow
string

Method applied to grant or deny access

is_forward
boolean

When access is granted, should the request be forwarded

engaged
string

Tags to check if it is the first time a user engages

Examples

GET /api/proxy/rules
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "rank": 0,
      "path": "/",
      "allow": "authenticated",
      "is_forward": true,
      "engaged": "app"
    }
  ]
}

Creates an access rule

POST /api/proxy/rules
        
Request body
rank
integer required

Determines the order in which rules are considered

path
string required

OpenAPI path against which requests are matched

allow
string

Method applied to grant or deny access

is_forward
boolean

When access is granted, should the request be forwarded

engaged
string

Tags to check if it is the first time a user engages

Responses

200

Examples

POST /api/proxy/rules/
{
  "rank": 0,
  "path": "/",
  "allow": "authenticated",
  "is_forward": true,
  "engaged": ""
}

Retrieves an access rule

GET /api/proxy/rules{rule}
        
Responses

200

rank
integer

Determines the order in which rules are considered

path
string

OpenAPI path against which requests are matched

allow
string

Method applied to grant or deny access

is_forward
boolean

When access is granted, should the request be forwarded

engaged
string

Tags to check if it is the first time a user engages

Examples

GET /api/proxy/rules/app/
responds
{
  "rank": 0,
  "path": "/app/",
  "allow": "authenticated",
  "is_forward": true,
  "engaged": ""
}

Updates an access rule

PUT /api/proxy/rules{rule}
        
Request body
rank
integer required

Determines the order in which rules are considered

allow
string

Method applied to grant or deny access

is_forward
boolean

When access is granted, should the request be forwarded

engaged
string

Tags to check if it is the first time a user engages

Responses

200

rank
integer

Determines the order in which rules are considered

path
string

OpenAPI path against which requests are matched

allow
string

Method applied to grant or deny access

is_forward
boolean

When access is granted, should the request be forwarded

engaged
string

Tags to check if it is the first time a user engages

Examples

PUT /api/proxy/rules/app/
{
  "rank": 0,
  "path": "/app/",
  "allow": "authenticated",
  "is_forward": true,
  "engaged": ""
}
responds
{
  "rank": 0,
  "path": "/app/",
  "allow": "authenticated",
  "is_forward": true,
  "engaged": ""
}

Deletes an access rule

DELETE /api/proxy/rules{rule}
        
Responses

204

Examples

DELETE /api/proxy/rules/app/

Retrieves example session

GET /api/proxy/sessions/{user}/
        

Returns a session data for a user as it will be passed to the backend service.

Responses

200

forward_session
string

The session being forwarded

forward_session_header
string

The HTTP header that encodes the session

forward_url
string

The URL end point where the request is forwarded

Examples

GET /api/proxy/sessions/xia/
responds
{
  "forward_session": "{username: xia}",
  "forward_session_header": "Authorization: XXX",
  "forward_url": "https://cowork.herokuapp.com/"
}

Lists roles by user

GET /api/users/{user}/accessibles/
        

Lists all relations where an Organization is accessible by a User. Typically the user was granted specific permissions through a Role.

see Flexible Security Framework.

Query parameters
page
integer

A page number within the paginated result set.

q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

request_key
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

role_description
object required

created_at
string

Date/time of creation (in ISO format)

title
string

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

slug
string

Unique identifier shown in the URL bar

is_global
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

home_url
string

settings_url
string

accept_grant_api_url
string

remove_api_url
string

Examples

GET /api/users/alice/accessibles/
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "cowork",
      "created_at": "2018-01-01T00:00:00Z",
      "printable_name": "ABC Corp.",
      "email": "help@cowork.net",
      "role_description": {
        "slug": "cowork",
        "created_at": "2018-01-01T00:00:00Z",
        "title": "ABC Corp.",
        "is_global": true,
        "organization": null
      },
      "request_key": null,
      "accept_grant_api_url": null,
      "remove_api_url": "https://cowork.net/api/users/alice/accessibles/manager/cowork",
      "home_url": "https://cowork.net/app/",
      "settings_url": "https://cowork.net/profile/cowork/contact/"
    }
  ]
}

Requests a role

POST /api/users/{user}/accessibles/
        

Creates a request to attach a user to a role on an organization

see Flexible Security Framework.

Responses

200

created_at
string

request_key
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

role_description
object required

created_at
string

Date/time of creation (in ISO format)

title
string

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

slug
string

Unique identifier shown in the URL bar

is_global
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

home_url
string

settings_url
string

accept_grant_api_url
string

remove_api_url
string

Examples

POST /api/users/xia/accessibles/
{
  "slug": "cowork"
}
responds
{
  "slug": "cowork"
}

Accepts role invite

PUT /api/users/{user}/accessibles/accept/{verification_key}/
        

Accepts a role on an organization.

Responses

200

created_at
string

request_key
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

role_description
object required

created_at
string

Date/time of creation (in ISO format)

title
string

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

slug
string

Unique identifier shown in the URL bar

is_global
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

home_url
string

settings_url
string

accept_grant_api_url
string

remove_api_url
string

Examples

PUT /api/users/xia/accessibles/accept/0123456789abcef/
responds
{
  "created_at": "2018-01-01T00:00:00Z",
  "role_description": {
    "created_at": "2018-01-01T00:00:00Z",
    "title": "Profile Manager",
    "slug": "manager",
    "is_global": true,
    "organization": {
      "slug": "cowork",
      "full_name": "ABC Corp.",
      "printable_name": "ABC Corp.",
      "created_at": "2018-01-01T00:00:00Z",
      "email": "support@localhost.localdomain"
    }
  },
  "user": {
    "slug": "alice",
    "email": "alice@localhost.localdomain",
    "full_name": "Alice Doe",
    "created_at": "2018-01-01T00:00:00Z"
  },
  "request_key": "1",
  "grant_key": null
}

Lists roles of specific type by user

GET /api/users/{user}/accessibles/{role}/
        

Lists all relations where a User has a specified Role on an Organization.

see Flexible Security Framework.

Query parameters
q
string

A search term.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

request_key
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

role_description
object required

created_at
string

Date/time of creation (in ISO format)

title
string

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

slug
string

Unique identifier shown in the URL bar

is_global
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

home_url
string

settings_url
string

accept_grant_api_url
string

remove_api_url
string

Examples

GET /api/users/alice/accessibles/manager/
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "cowork",
      "created_at": "2018-01-01T00:00:00Z",
      "printable_name": "ABC Corp.",
      "email": "help@cowork.net",
      "role_description": {
        "slug": "cowork",
        "created_at": "2018-01-01T00:00:00Z",
        "title": "ABC Corp.",
        "is_global": true,
        "organization": null
      },
      "request_key": null,
      "accept_grant_api_url": null,
      "remove_api_url": "https://cowork.net/api/users/alice/accessibles/manager/cowork",
      "home_url": "https://cowork.net/app/",
      "settings_url": "https://cowork.net/profile/cowork/contact/"
    }
  ]
}

Requests a role of a specified type

POST /api/users/{user}/accessibles/{role}/
        

Creates a request to attach a user to an organization with a specified role.

see Flexible Security Framework.

Request body
organization
string required

message
string

Responses

200

organization
string

message
string

Examples

POST /api/users/xia/accessibles/manager/
{
  "slug": "cowork"
}
responds
{
  "slug": "cowork"
}

Re-sends request for role

POST /api/users/{user}/accessibles/{role}/{organization}/
        

Re-sends the request e-mail that the user is requested a role on the organization.

Responses

200

created_at
string

user
object required

slug
string

Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.

email
string

E-mail address for the user

full_name
string

Full name for the contact (effectively first name followed by last name)

created_at
string

Date/time of creation (in ISO format)

grant_key
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

role_description
object required

created_at
string

Date/time of creation (in ISO format)

title
string

Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.

slug
string

Unique identifier shown in the URL bar

is_global
string

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

accept_request_api_url
string

remove_api_url
string

Examples

POST /api/users/xia/accessibles/manager/cowork/
responds
{
  "created_at": "2018-01-01T00:00:00Z",
  "role_description": {
    "created_at": "2018-01-01T00:00:00Z",
    "title": "Profile Manager",
    "slug": "manager",
    "is_global": true,
    "organization": {
      "slug": "cowork",
      "full_name": "ABC Corp.",
      "printable_name": "ABC Corp.",
      "created_at": "2018-01-01T00:00:00Z",
      "email": "support@localhost.localdomain"
    }
  },
  "user": {
    "slug": "alice",
    "email": "alice@localhost.localdomain",
    "full_name": "Alice Doe",
    "created_at": "2018-01-01T00:00:00Z"
  },
  "request_key": "1",
  "grant_key": null
}

Deletes a role by type

DELETE /api/users/{user}/accessibles/{role}/{organization}/
        

Dettach a user from one or all roles with regards to an organization, typically resulting in revoking permissions from this user to manage part of an organization profile.

Responses

204

Examples

DELETE /api/users/xia/accessibles/manager/cowork/

Creates a new profile owned by user

POST /api/users/{user}/profiles/
        

This end-point creates a new profile whose manager is user and returns an error if the profile already exists.

If you want to request access to an already existing profile, see the accessibles end-point.

Request body
slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

default_timezone
string

Timezone to use when reporting metrics

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

extra
string

Extra meta data (can be stringify JSON)

type
string

One of 'organization', 'personal' or 'user'

Responses

200

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

default_timezone
string

Timezone to use when reporting metrics

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

extra
string

Extra meta data (can be stringify JSON)

type
string

One of 'organization', 'personal' or 'user'

Examples

POST /api/users/xia/profiles/
{
  "slug": "myproject",
  "full_name": "My Project"
}
responds
{
  "slug": "myproject",
  "full_name": "My Project"
}

Lists a provider plans

GET /api/profile/{organization}/plans/
        

Returns a PAGE_SIZE list of plans whose provider is {organization}.

Query parameters
page
integer

A page number within the paginated result set.

o
string

Which field to use when ordering the results.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

slug
string

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period for the subscription

app_url
string

advance_discount
integer

Incremental discount for payment of multiple periods (in %%).

unit
string

organization
string

Provider of the plan

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Natural period length of a subscription to the plan (monthly, yearly, etc.)

renewal_type
string

Natural period for the subscription

is_not_priced
boolean

created_at
string

skip_optin_on_grant
boolean

True when a subscriber can automatically be subscribed to the plan by its provider. Otherwise the subscriber must manually accept the subscription. (defaults to False)

optin_on_request
boolean

True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)

Examples

GET /api/profile/cowork/plans
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "managed",
      "title": "Managed",
      "description": "Ideal for growing organizations",
      "is_active": true,
      "setup_amount": 0,
      "period_amount": 2900,
      "period_length": 1,
      "period_type": "monthly",
      "advance_discount": 0,
      "unit": "usd",
      "is_not_priced": false,
      "renewal_type": "auto-renew",
      "created_at": "2019-01-01T00:00:00Z",
      "organization": "cowork",
      "extra": null,
      "skip_optin_on_grant": false,
      "optin_on_request": false
    }
  ]
}

Creates a subscription plan

POST /api/profile/{organization}/plans/
        

Creates a subscription plan for provider {organization}.

Request body
title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period for the subscription

advance_discount
integer

Incremental discount for payment of multiple periods (in %%).

unit
string

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Natural period length of a subscription to the plan (monthly, yearly, etc.)

renewal_type
string

Natural period for the subscription

is_not_priced
boolean

skip_optin_on_grant
boolean

True when a subscriber can automatically be subscribed to the plan by its provider. Otherwise the subscriber must manually accept the subscription. (defaults to False)

optin_on_request
boolean

True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)

Responses

200

slug
string

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period for the subscription

app_url
string

advance_discount
integer

Incremental discount for payment of multiple periods (in %%).

unit
string

organization
string

Provider of the plan

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Natural period length of a subscription to the plan (monthly, yearly, etc.)

renewal_type
string

Natural period for the subscription

is_not_priced
boolean

created_at
string

skip_optin_on_grant
boolean

True when a subscriber can automatically be subscribed to the plan by its provider. Otherwise the subscriber must manually accept the subscription. (defaults to False)

optin_on_request
boolean

True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)

Examples

POST /api/profile/cowork/plans
{
  "title": "Open Space",
  "description": "A desk in our coworking space",
  "is_active": false,
  "period_amount": 12000,
  "interval": "monthly"
}
responds
{
  "title": "Open Space",
  "description": "A desk in our coworking space",
  "is_active": false,
  "period_amount": 12000,
  "interval": "monthly"
}

Retrieves a subscription plan

GET /api/profile/{organization}/plans/{plan}/
        

Returns the {plan} for provider {organization}

The is_active boolean is used to activate a plan, enabling users to subscribe to it, or deactivate a plan, disabling users from subscribing to it.

Responses

200

slug
string

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period for the subscription

app_url
string

advance_discount
integer

Incremental discount for payment of multiple periods (in %%).

unit
string

organization
string

Provider of the plan

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Natural period length of a subscription to the plan (monthly, yearly, etc.)

renewal_type
string

Natural period for the subscription

is_not_priced
boolean

created_at
string

skip_optin_on_grant
boolean

True when a subscriber can automatically be subscribed to the plan by its provider. Otherwise the subscriber must manually accept the subscription. (defaults to False)

optin_on_request
boolean

True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)

Examples

GET /api/profile/cowork/plans/open-space
responds
{
  "title": "Open Space",
  "description": "A desk in our coworking space",
  "is_active": false,
  "period_amount": 12000,
  "interval": "monthly"
}

Updates a subscription plan

PUT /api/profile/{organization}/plans/{plan}/
        

Updates fields for {plan}. If the period_amount is modified, all subscriptions to this plan will be charged the period_amount on renewal.

The is_active boolean is used to activate a plan, enabling users to subscribe to it, or deactivate a plan, disabling users from subscribing to it.

Request body
title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period for the subscription

advance_discount
integer

Incremental discount for payment of multiple periods (in %%).

unit
string

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Natural period length of a subscription to the plan (monthly, yearly, etc.)

renewal_type
string

Natural period for the subscription

is_not_priced
boolean

skip_optin_on_grant
boolean

True when a subscriber can automatically be subscribed to the plan by its provider. Otherwise the subscriber must manually accept the subscription. (defaults to False)

optin_on_request
boolean

True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)

Responses

200

slug
string

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period for the subscription

app_url
string

advance_discount
integer

Incremental discount for payment of multiple periods (in %%).

unit
string

organization
string

Provider of the plan

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Natural period length of a subscription to the plan (monthly, yearly, etc.)

renewal_type
string

Natural period for the subscription

is_not_priced
boolean

created_at
string

skip_optin_on_grant
boolean

True when a subscriber can automatically be subscribed to the plan by its provider. Otherwise the subscriber must manually accept the subscription. (defaults to False)

optin_on_request
boolean

True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)

Examples

PUT /api/profile/cowork/plans/open-space
{
  "title": "Open Space"
}
responds
{
  "title": "Open Space",
  "description": "A desk in our coworking space",
  "is_active": false,
  "period_amount": 12000,
  "interval": "monthly"
}

Deletes a subscription plan

DELETE /api/profile/{organization}/plans/{plan}/
        

A plan can only be deleted when there are no subscriptions to it. Even if all subscriptions to a plan have expired, the plan cannot be deleted. It should be de-activated instead such that no customers can subscribes to it.

Responses

204

Examples

DELETE /api/profile/cowork/plans/open-space

Lists subscriptions to a plan

GET /api/profile/{organization}/plans/{plan}/subscriptions/
        

Returns a PAGE_SIZE records of subscriptions to {plan} provided by {organization}.

Query parameters
page
integer

A page number within the paginated result set.

o
string

Which field to use when ordering the results.

q
string

A search term.

Responses

200

count
integer

Total number of items in the dataset

previous
string

URL to previous page of results

next
string

URL to next page of results

results
array

items in current page

created_at
string

Date/time of creation (in ISO format)

ends_at
string

Date/time when the subscription period currently ends (in ISO format)

description
string

Free-form text description for the subscription

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

plan
object

slug
string

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period for the subscription

app_url
string

advance_discount
integer

Incremental discount for payment of multiple periods (in %%).

unit
string

organization
string

Provider of the plan

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Natural period length of a subscription to the plan (monthly, yearly, etc.)

renewal_type
string

Natural period for the subscription

is_not_priced
boolean

created_at
string

skip_optin_on_grant
boolean

True when a subscriber can automatically be subscribed to the plan by its provider. Otherwise the subscriber must manually accept the subscription. (defaults to False)

optin_on_request
boolean

True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)

auto_renew
boolean

The subscription is set to auto-renew at the end of the period

editable
string

True if the request user is able to update the subscription. Typically a manager for the plan provider.

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

request_key
string

Examples

GET /api/profile/cowork/plans/premium/subscriptions/
responds
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "full_name": "Xia Lee",
      "created_at": "2016-01-14T23:16:55Z",
      "ends_at": "2017-01-14T23:16:55Z"
    }
  ]
}

Subscribes to a plan through the provider

POST /api/profile/{organization}/plans/{plan}/subscriptions/
        

Subscribes a customer to the {plan} provided by {organization}.

Request body
organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

default_timezone
string

Timezone to use when reporting metrics

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

extra
string

Extra meta data (can be stringify JSON)

type
string

One of 'organization', 'personal' or 'user'

message
string

Responses

200

created_at
string

Date/time of creation (in ISO format)

ends_at
string

Date/time when the subscription period currently ends (in ISO format)

description
string

Free-form text description for the subscription

organization
object required

slug
string

Unique identifier shown in the URL bar

full_name
string

Full name

printable_name
string

picture
string

Profile picture

type
string

One of 'organization', 'personal' or 'user'

credentials
string

created_at
string

Date/time of creation (in ISO format)

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The organization can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy (what is it?)

extra
string

Extra meta data (can be stringify JSON)

plan
object

slug
string

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period for the subscription

app_url
string

advance_discount
integer

Incremental discount for payment of multiple periods (in %%).

unit
string

organization
string

Provider of the plan

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Natural period length of a subscription to the plan (monthly, yearly, etc.)

renewal_type
string

Natural period for the subscription

is_not_priced
boolean

created_at
string

skip_optin_on_grant
boolean

True when a subscriber can automatically be subscribed to the plan by its provider. Otherwise the subscriber must manually accept the subscription. (defaults to False)

optin_on_request
boolean

True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)

auto_renew
boolean

The subscription is set to auto-renew at the end of the period

editable
string

True if the request user is able to update the subscription. Typically a manager for the plan provider.

extra
string

Extra meta data (can be stringify JSON)

grant_key
string