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.

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

201

token
string
Token used to authenticate user on every HTTP request

400

detail
string
Describes the reason for the error in plain text

Examples

POST https://cowork.djaoapp.com/api/auth/ HTTP/1.1
{
  "username": "donny",
  "password": "yoyo"
}

responds

{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"}

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.

Request body
token
string required
Token used to authenticate user on every HTTP request
Responses

201

token
string
Token used to authenticate user on every HTTP request

Examples

POST https://cowork.djaoapp.com/api/auth/logout/  HTTP/1.1
{
  "token": "670yoaq34rotlgqpoxzmw435Alrdf"
}

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

201

email
string
Primary e-mail to contact user

Examples

POST https://cowork.djaoapp.com/api/auth/recover/ HTTP/1.1
{
    "email": "xia@localhost.localdomain"
}

responds

{
    "email": "xia@localhost.localdomain"
}

Registers a user

POST /api/auth/register/
        

Creates a new user and optionally an associated billing or organization profile.

This end point 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)
organization_name
string
Organization name that owns the billing, registered with the user as profile manager
street_address
string
Street address for the billing profile
locality
string
City/Town for the billing profile
region
string
State/Province/County for the billing profile
postal_code
string
Zip/Postal Code for the billing profile
country
string
Country for the billing profile
phone
string
Phone number for the billing profile
Responses

201

token
string
Token used to authenticate user on every HTTP request

400

detail
string
Describes the reason for the error in plain text

Examples

POST https://cowork.djaoapp.com/api/auth/register/ HTTP/1.1
{
  "username": "joe1",
  "password": "yoyo",
  "email": "joe+1@example.com",
  "full_name": "Joe Card1"
}

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

201

token
string
Token used to authenticate user on every HTTP request

Examples

POST https://cowork.djaoapp.com/api/tokens/ HTTP/1.1
{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"
}

responds

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5Njk1NjA1fQ.-uuZb8R68jWw1Tc9FJocOWe1KHFklRffXbH0Rg6d_0c"
}

Retrieves temporary credentials

GET /api/auth/tokens/realms/
        

Gets temporary credentials to access S3 directly from the browser.

Responses

200

location
string
URL to upload files
acl
string
ACL (i.e. private or public-read)
policy
string
Policy
signature
string
Signature
security_token
string
Security token
x_amz_credential
string
AMZ Credential
x_amz_date
string
AMZ Date

Examples

GET  /api/auth/realms/cowork/ HTTP/1.1

responds

{
    "location": "",
    "access_key": "",
    "acl": "private",
    "policy": "",
    "signature": "",
    "security_token": "",
    "x_amz_credential": "",
    "x_amz_date": ""
}

Retrieves temporary credentials

GET /api/auth/tokens/realms/{organization}/
        

Gets temporary credentials to access S3 directly from the browser.

Responses

200

location
string
URL to upload files
acl
string
ACL (i.e. private or public-read)
policy
string
Policy
signature
string
Signature
security_token
string
Security token
x_amz_credential
string
AMZ Credential
x_amz_date
string
AMZ Date

Examples

GET  /api/auth/realms/cowork/ HTTP/1.1

responds

{
    "location": "",
    "access_key": "",
    "acl": "private",
    "policy": "",
    "signature": "",
    "security_token": "",
    "x_amz_credential": "",
    "x_amz_date": ""
}

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

400

detail
string
Describes the reason for the error in plain text

Examples

POST https://cowork.djaoapp.com/api/tokens/verify/ HTTP/1.1
{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"
}

responds

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"
}

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

201

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

400

detail
string
Describes the reason for the error in plain text

Examples

POST https://cowork.djaoapp.com/api/users/donny/activate/ HTTP/1.1

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.

Request body
password
string required
Password of the user making the HTTP request
Responses

201

secret
string
Secret API Key used to authenticate user on every HTTP request

Examples

POST https://cowork.djaoapp.com/api/users/donny/api-keys/  HTTP/1.1

responds

{
    "secret": "tgLwDw5ErQ2pQr5TTdAzSYjvZenHC9pSy7fB3sXWERzynbG5zG6h67pTN4dh7fpy"
}

Changes a user password

PUT /api/users/{user}/password/
        
Request body
password
string required
Password of the user making the HTTP request
new_password
string required
New password for the user referenced in the URL
Responses

200

Examples

PUT https://cowork.djaoapp.com/api/users/donny/password/ HTTP/1.1
{
  "password": "yeye"
}

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

pubkey
string
New public key for the user referenced in the URL

Examples

PUT https://cowork.djaoapp.com/api/users/donny/ssh-keys/  HTTP/1.1
{
  "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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

o
string

sort by description, amount, Full name, created_at. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

q
string

search for matching text in description, processor_key, customer__full_name

page
integer

A page number within the paginated result set.

Responses

200

total
integer
The sum of all Charge amount (in unit)
count
integer
The number of records
next
string
API end point to get the next pageof records matching the query
previous
string
API end point to get the previous pageof records matching the query
results
array of Charge
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
state
string
Current state (i.e. created, done, failed, disputed)

Examples

GET https://cowork.djaoapp.com/api/billing/charges?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1

Retrieves the list of charges that were created before 2015-07-05T07:00:00.000Z, sort them by date in descending order.

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": "12/2016",
        "processor_key": "ch_XAb124EF",
        "state": "DONE"
    }]
}

Retrieves a single processor charge

GET /api/billing/charges/{charge}/
        

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
state
string
Current state (i.e. created, done, failed, disputed)

Examples

GET https://cowork.djaoapp.com/api/billing/charges/ch_XAb124EF/ HTTP/1.1

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": "12/2016",
    "processor_key": "ch_XAb124EF",
    "state": "DONE"
}

Re-sends a charge receipt

POST /api/billing/charges/{charge}/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

201

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 https://cowork.djaoapp.com/api/billing/charges/ch_XAb124EF/email/  HTTP/1.1

responds

{
    "charge_id": "ch_XAb124EF",
    "email": "joe@localhost.localdomain"
}

Refunds a processor charge

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

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

Request body
lines
array of RefundChargeItem required
num
integer required
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
state
string
Current state (i.e. created, done, failed, disputed)

400

detail
string
Describes the reason for the error in plain text

Examples

POST https://cowork.djaoapp.com/api/billing/charges/ch_XAb124EF/refund/ HTTP/1.1
{
    "lines": [
      {
          "num": 0,
          "refunded_amount": 4000
      },
      {
          "num": 1,
          "refunded_amount": 82120
      }
  ]
}

Refunds $40 and $821.20 from first and second line item on the receipt respectively. The API call responds with the Charge.

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": "12/2016",
    "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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

q
string

search for matching text in descr, orig_organization__full_name, dest_organization__full_name

o
string

sort by description, amount, dest_organization, dest_account, orig_organization, orig_account, created_at. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

Responses

200

balance
integer
balance of all transactions in cents (i.e. 100ths) of unit
unit
integer
three-letter ISO 4217 code for currency unit (ex: usd)
count
integer
The number of records
next
string
API end point to get the next pageof records matching the query
previous
string
API end point to get the previous pageof records matching the query
results
array of Transaction
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 https://cowork.djaoapp.com/api/billing/transactions?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1

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/ HTTP/1.1

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 https://cowork.djaoapp.com/api/billing/cowork/balance/ HTTP/1.1

Retrieves a payout account

GET /api/billing/{organization}/bank/
        

Pass through that calls the processor API to retrieve some details about the deposit account associated to a provider (if that information is available through the payment processor backend API).

This API does not trigger payment of a subscriber to a provider. Checkout of a subscription cart is done either through the HTML page or API end point.

Responses

200

bank_name
string
Name of the deposit account
last4
string
Last 4 characters of the deposit account identifier
balance_amount
integer
Amount available to transfer to the provider deposit account
balance_unit
string
Three-letter ISO 4217 code for currency unit (ex: usd)

Examples

GET https://cowork.djaoapp.com/api/billing/cowork/bank/ HTTP/1.1

responds

{
  "bank_name": "Stripe Test Bank",
  "last4": "***-htrTZ",
  "balance_amount": 0,
  "balance_unit": "usd"
}

Retrieves a payment method

GET /api/billing/{organization}/card/
        

Pass through to the processor to retrieve some details about the payment method (ex: credit card) associated to a subscriber.

Responses

200

last4
string
Last 4 digits of the credit card on file
exp_date
string
Expiration date of the credit card on file

Examples

GET https://cowork.djaoapp.com/api/billing/cowork/card/ HTTP/1.1

responds

{
  "last4": "1234",
  "exp_date": "12/2019"
}

Updates a payment method

PUT /api/billing/{organization}/card/
        

Pass through to the processor to update some details about the payment method (ex: credit card) associated to a subscriber.

Request body
last4
string required
Last 4 digits of the credit card on file
exp_date
string required
Expiration date of the credit card on file
Responses

200

last4
string
Last 4 digits of the credit card on file
exp_date
string
Expiration date of the credit card on file

Examples

PUT https://cowork.djaoapp.com/api/billing/cowork/card/ HTTP/1.1
{
  "token": "xyz"
}

responds

{
  "last4": "1234",
  "exp_date": "12/2019"
}

Deletes a payment method

DELETE /api/billing/{organization}/card/
        

Pass through to the processor to remove the payment method (ex: credit card) associated to a subscriber.

Responses

204

Examples

DELETE https://cowork.djaoapp.com/api/billing/cowork/card/ HTTP/1.1

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 of Invoicable
subscription
Subscription
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
Organization
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'
credentials
string
extra
string
Extra meta data (can be stringify JSON)
plan
Plan
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
interval
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)
lines
array of Transaction
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)
Line items to charge on checkout.
options
array of Transaction
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 to replace line items.

Examples

GET https://cowork.djaoapp.com/api/billing/xia/checkout HTTP/1.1

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,
          "interval":4,
          "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.

Request body
items
array of CheckoutItem
option
integer required
selected plan option during checkout
remember_card
boolean
attaches the payment card to the Organization when true
processor_token
string
one-time token generated by the processorfrom the payment card.
street_address
string
Street address
locality
string
City/Town
region
string
State/Province/County
postal_code
string
Zip/Postal code
country
string
Country
Responses

201

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
state
string
Current state (i.e. created, done, failed, disputed)

Examples

POST https://cowork.djaoapp.com/api/billing/xia/checkout HTTP/1.1
{
    "remember_card": true,
    "processor_token": "tok_23prgoqpstf56todq"
}

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
o
string

sort by code, created_at, description, ends_at, percent. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

q
string

search for matching text in code, description, percent, organization__full_name

start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Coupon
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

Examples

GET https://cowork.djaoapp.com/api/billing/cowork/coupons?o=code&ot=asc&q=DIS HTTP/1.1

retrieves the list of Coupon for provider cowork where code matches 'DIS', ordered by code in ascending order.

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
        }
    ]
}

Creates a discount code

POST /api/billing/{organization}/coupons/
        

Customers will be able to use the code until ends_at to subscribe to plans from the Coupon's provider at a discount.

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
Responses

201

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

Examples

POST https://cowork.djaoapp.com/api/billing/cowork/coupons HTTP/1.1
{
  "code": "DIS100",
  "percent": 100,
  "ends_at": null,
  "description": null
}

responds

{
  "code": "DIS100",
  "percent": 100,
  "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

Examples

GET https://cowork.djaoapp.com/api/billing/cowork/coupons/DIS100 HTTP/1.1

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
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

Examples

PUT https://cowork.djaoapp.com/api/billing/cowork/coupons/DIS100 HTTP/1.1
{
    "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 https://cowork.djaoapp.com/api/billing/cowork/coupons/DIS100 HTTP/1.1

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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

q
string

search for matching text in descr, orig_organization__full_name, dest_organization__full_name

o
string

sort by description, amount, dest_organization, dest_account, orig_organization, orig_account, created_at. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Transaction
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 https://cowork.djaoapp.com/api/billing/xia/history?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1

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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

q
string

search for matching text in descr, orig_organization__full_name, dest_organization__full_name

o
string

sort by description, amount, dest_organization, dest_account, orig_organization, orig_account, created_at. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Transaction
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 https://cowork.djaoapp.com/api/billing/cowork/receivables?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1

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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

q
string

search for matching text in descr, orig_organization__full_name, dest_organization__full_name

o
string

sort by description, amount, dest_organization, dest_account, orig_organization, orig_account, created_at. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Transaction
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 https://cowork.djaoapp.com/api/billing/cowork/transfers?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1

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
string required
descr
string
Free-form text description for the transaction
Responses

201

subscription
string
The subscription the offline transaction refers to.
created_at
string
Date/time of creation (in ISO format)
amount
string
descr
string
Free-form text description for the transaction

Examples

POST https://cowork.djaoapp.com/api/billing/cowork/transfers/import/ HTTP/1.1
{
    "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

201

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 https://cowork.djaoapp.com/api/cart/ HTTP/1.1
{
    "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 https://cowork.djaoapp.com/api/cart/?plan=open-space HTTP/1.1

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 https://cowork.djaoapp.com/api/redeem HTTP/1.1
{
    "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.

Request body
created
string required
updated
string required
failed
string required
Responses

201

created
string
updated
string
failed
string

Examples

Content of names.csv:

System Message: WARNING/2 (<string>, line 4)

Cannot analyze code. No Pygments lexer found for "csv".

.. code-block:: csv
    Joe,Smith,joesmith@example.com
    Marie,Johnson,mariejohnson@example.com
POST https://cowork.djaoapp.com/api/cart/basic/upload/ HTTP/1.1
Content-Disposition: form-data; name="file"; filename="names.csv"
Content-Type: text/csv

responds

{
    "created": [
        {
            "first_name": "Joe",
            "last_name": "Smith",
            "email": "joesmith@example.com"
        },
        {
            "first_name": "Marie",
            "last_name": "Johnson",
            "email": "mariejohnson@example.com"
        }
    ],
    "updated": [],
    "failed": []
}

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 of Table
key
string
Unique key in the table for the data series
selector
string
Filter on the Transaction accounts
values
string
Datapoints in the serie

Examples

GET https://cowork.djaoapp.com/api/metrics/balances/taxes/ HTTP/1.1

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
next
string
previous
string
results
array of BalanceLine
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/ HTTP/1.1

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

201

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 https://cowork.djaoapp.com/api/metrics/balances/taxes/lines/ HTTP/1.1
{
  "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/ HTTP/1.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 https://cowork.djaoapp.com/api/metrics/balances/taxes/lines/1/ HTTP/1.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 https://cowork.djaoapp.com/api/metrics/balances/taxes/lines/1/ HTTP/1.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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

o
string

sort by first_name, last_name, email, created_at. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

q
string

search for matching text in first_name, last_name, email

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of User
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 HTTP/1.1

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
o
string

sort by organization, plan, created_at, ends_at. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

q
string

search for matching text in organization__slug, organization__full_name, organization__email, organization__phone, organization__street_address, organization__locality, organization__region, organization__postal_code, organization__country, plan__title

start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Subscription
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
Organization
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'
credentials
string
extra
string
Extra meta data (can be stringify JSON)
plan
Plan
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
interval
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)

Examples

GET https://cowork.djaoapp.com/api/metrics/cowork/active?o=created_at&ot=desc HTTP/1.1

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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Metrics
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 of Table
key
string
Unique key in the table for the data series
selector
string
Filter on the Transaction accounts
values
string
Datapoints in the serie

Examples

GET https://cowork.djaoapp.com/api/metrics/cowork/balances HTTP/1.1

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
o
string

sort by organization, plan, created_at, ends_at. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

q
string

search for matching text in organization__slug, organization__full_name, organization__email, organization__phone, organization__street_address, organization__locality, organization__region, organization__postal_code, organization__country, plan__title

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Subscription
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
Organization
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'
credentials
string
extra
string
Extra meta data (can be stringify JSON)
plan
Plan
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
interval
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)

Examples

GET https://cowork.djaoapp.com/api/metrics/cowork/churned?o=created_at&ot=desc HTTP/1.1

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.

Responses

200

created_at
string
Date/time of creation (in ISO format)
user
User
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 https://cowork.djaoapp.com/api/metrics/cowork/coupons/DIS100/ HTTP/1.1

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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Metrics
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 of Table
key
string
Unique key in the table for the data series
selector
string
Filter on the Transaction accounts
values
string
Datapoints in the serie

Examples

GET https://cowork.djaoapp.com/api/metrics/cowork/customers HTTP/1.1

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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Metrics
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 of Table
key
string
Unique key in the table for the data series
selector
string
Filter on the Transaction accounts
values
string
Datapoints in the serie

Examples

GET https://cowork.djaoapp.com/api/metrics/cowork/funds/ HTTP/1.1

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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Metrics
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 of Table
key
string
Unique key in the table for the data series
selector
string
Filter on the Transaction accounts
values
string
Datapoints in the serie

Examples

GET https://cowork.djaoapp.com/api/metrics/cowork/plans HTTP/1.1

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
next
string
previous
string
results
array of Activity
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 https://cowork.djaoapp.com/api/proxy/recent/ HTTP/1.1

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"
    }
  ]
}

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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

q
string

search for matching text in slug, full_name, email, phone, street_address, locality, region, postal_code, country, username, first_name, last_name

o
string

sort by u, r. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Organization
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'
credentials
string
extra
string
Extra meta data (can be stringify JSON)

Examples

GET https://cowork.djaoapp.com/api/accounts/?o=created_at HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [{
        "slug": "xia",
        "full_name": "Xia Lee",
        "printable_name": "Xia Lee",
        "created_at": "2016-01-14T23:16:55Z"
    }]
}

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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

q
string

search for matching text in slug, full_name, email, phone, street_address, locality, region, postal_code, country, username, first_name, last_name

o
string

sort by u, r. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Organization
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'
credentials
string
extra
string
Extra meta data (can be stringify JSON)

Examples

GET https://cowork.djaoapp.com/api/accounts/profile/?q=xia HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [{
        "slug": "xia",
        "full_name": "Xia Lee",
        "printable_name": "Xia Lee",
        "created_at": "2016-01-14T23:16:55Z"
    }]
}

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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

o
string

sort by first_name, last_name, email, created_at. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

q
string

search for matching text in first_name, last_name, email

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of User
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 HTTP/1.1

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 activities for a contact

GET /api/contacts/{user}/activities/
        
Query parameters
q
string

A search term.

o
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Activity
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 https://cowork.djaoapp.com/api/contacts/xia/activities HTTP/1.1

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

201

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 https://cowork.djaoapp.com/api/contacts/xia/activities/ HTTP/1.1
{
  "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

201

read_terms
boolean
I have read and understand these terms and conditions
last_signed
string

Examples

POST https://cowork.djaoapp.com/api/legal/terms-of-use/sign/ HTTP/1.1
{
  "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
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

q
string

search for matching text in slug, full_name, email, phone, street_address, locality, region, postal_code, country, username, first_name, last_name

o
string

sort by u, r. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Organization
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'
credentials
string
extra
string
Extra meta data (can be stringify JSON)

Examples

GET https://cowork.djaoapp.com/api/profile/?o=created_at&ot=desc HTTP/1.1

responds

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [{
        "slug": "xia",
        "full_name": "Xia Lee",
        "printable_name": "Xia Lee",
        "created_at": "2016-01-14T23:16:55Z"
    }]
}

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

201

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 https://cowork.djaoapp.com/api/profile/ HTTP/1.1
{
  "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'
credentials
string
extra
string
Extra meta data (can be stringify JSON)
activities
array of Activity
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
subscriptions
array of WithSubscription
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

Examples

GET https://cowork.djaoapp.com/api/profile/xia/ HTTP/1.1

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": "",
    "extra": "",
    "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'
credentials
string
extra
string
Extra meta data (can be stringify JSON)
activities
array of Activity
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
subscriptions
array of WithSubscription
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

Examples

PUT https://cowork.djaoapp.com/api/profile/xia/ HTTP/1.1

responds

{
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee"
}

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 https://cowork.djaoapp.com/api/profile/xia/ HTTP/1.1

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
q
string

A search term.

o
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Contact
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 https://cowork.djaoapp.com/api/users/?q=xia HTTP/1.1

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
Responses

201

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 https://cowork.djaoapp.com/api/users/ HTTP/1.1
{
  "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}/
        
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 of Activity
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 https://cowork.djaoapp.com/api/users/donny HTTP/1.1

responds

{
  "username": "donny",
  "email": "donny.smith@locahost.localdomain",
  "full_name": "Donny Smith"
}

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 of Activity
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 https://cowork.djaoapp.com/api/users/xia/ HTTP/1.1
{
  "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 https://cowork.djaoapp.com/api/users/xia/ HTTP/1.1

Changes a user notifications preferences

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

200

notifications
array of array

Examples

POST https://cowork.djaoapp.com/api/users/donny/notifications/ HTTP/1.1
{
  "notifications": ["user_registered_notice"]
}

responds

{
  "notifications": ["user_registered_notice"]
}

Lists roles for an organization

GET /api/profile/{organization}/roles/
        
Query parameters
start_at
string

date/time in ISO format after which records were created.

ends_at
string

date/time in ISO format before which records were created.

q
string

search for matching text in organization__slug, organization__full_name, organization__email, user__username, user__email, role_description__title, role_description__slug

o
string

sort by full_name, username, role_name, grant_key, request_key, created_at. If a field is preceded bya minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

Responses

200

count
integer
next
string
previous
string
results
array of Role
created_at
string
user
User
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)
organization
Organization
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'
credentials
string
extra
string
Extra meta data (can be stringify JSON)
role_description
string
accept_request_api_url
string
remove_api_url
string

Examples

GET https://cowork.djaoapp.com/api/profile/cowork/roles/ HTTP/1.1

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

count
integer
next
string
previous
string
results
array of RoleDescriptionCRUD
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
roles
string

Examples

GET https://cowork.djaoapp.com/api/profile/cowork/roles/describe/ HTTP/1.1

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",
            "name": "Contributors",
            "slug": "contributor",
            "is_global": false,
            "roles": []
        }
    ]
}

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

201

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
roles
string

Examples

POST https://cowork.djaoapp.com/api/profile/cowork/roles/describe/ HTTP/1.1
{
    "title": "Managers"
}

responds

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "created_at": "2018-01-01T00:00:00Z",
            "name": "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",
            "name": "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
roles
string

Examples

GET https://cowork.djaoapp.com/api/profile/cowork/roles/describe/manager HTTP/1.1

responds

{
    "created_at": "2018-01-01T00:00:00Z",
    "name": "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
        }
    ]
}

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
roles
string

Examples

PUT https://cowork.djaoapp.com/api/profile/cowork/roles/describe/manager HTTP/1.1
{
    "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 https://cowork.djaoapp.com/api/profile/cowork/roles/describe/manager HTTP/1.1

Lists roles of a specific type

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

Lists the specified role assignments for an organization.

Responses

200

created_at
string
user
User
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)
organization
Organization
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'
credentials
string
extra
string
Extra meta data (can be stringify JSON)
role_description
string
accept_request_api_url
string
remove_api_url
string

Examples

GET https://cowork.djaoapp.com/api/profile/cowork/roles/manager/ HTTP/1.1

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).

Query parameters
force
boolean

Forces invite of user/organization that could not be found

Request body
slug
string required
email
string
message
string
Responses

201

slug
string
email
string
message
string

Examples

POST https://cowork.djaoapp.com/api/profile/cowork/roles/manager/ HTTP/1.1
{
  "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.

Request body
request_key
string
grant_key
string
role_description
RoleDescription
title
string required
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
slug
string required
Unique identifier shown in the URL bar
organization
Organization
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)
user
User
slug
string required
Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.
created_at
string
Date/time of creation (in ISO format)
Responses

201

created_at
string
role_description
RoleDescription
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
Organization
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'
credentials
string
extra
string
Extra meta data (can be stringify JSON)
user
User
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

POST https://cowork.djaoapp.com/api/profile/cowork/roles/manager/xia/ HTTP/1.1

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 https://cowork.djaoapp.com/api/profile/cowork/roles/manager/xia/ HTTP/1.1

Grants a subscription request

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

Accepts a subscription request.

Request body
ends_at
string required
Date/time when the subscription period currently ends (in ISO format)
description
string
Free-form text description for the subscription
organization
Organization
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)
plan
Plan
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
interval
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)
auto_renew
boolean
The subscription is set to auto-renew at the end of the period
extra
string
Extra meta data (can be stringify JSON)
Responses

201

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
Organization
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'
credentials
string
extra
string
Extra meta data (can be stringify JSON)
plan
Plan
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
interval
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)

Examples

POST https://cowork.djaoapp.com/api/profile/xia/subscribers/accept/a00000d0a0000001234567890123456789012345 HTTP/1.1

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"