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:
- JSON Web Token through the /auth/ API
- HTTP Cookie through the /login/ HTML page
- API Key downloaded from a user profile page
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
To learn more about authenticating to a DjaoApp service, visit How to authenticate with the API on the command line?
- Logs a user in
- Retrieves user associated to an activation key
- Activates a user
- Logs a user out
- Emails a password reset link
- Registers a user
- Confirms a password reset
- Refreshes a JSON Web Token
- Verifies a JSON Web Token
- Sends a contact-us message
- Re-sends an activation link
- Resets a user secret API key
- Changes a user password
- Updates a user public RSA key
Logs a user in
POST /api/auth/
Returns a JSON Web Token that can be used in requests that require authentication.
Request body
Username to identify the account
Secret password for the account
One-time code. This field will be checked against an expected code when multi-factor authentication (MFA) is enabled.
Responses
200
Token used to authenticate user on every HTTP request
Examples
POST /api/auth/responds{ "username": "donny", "password": "yoyo" }
{ "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A" }
Retrieves user associated to an activation key
GET /api/auth/activate/{verification_key}/
Retrieves information about a user based on an activation key.
Responses
200
Username
Full name
Picture
Primary e-mail to contact user
date at which the account was created
True if the user has valid login credentials
Username
Full name
Examples
GET /api/auth/activate/0123456789abcef0123456789abcef/{ "slug": "joe1", "username": "joe1", "email": "joe1@localhost.localdomain", "full_name": "Joe Act", "printable_name": "Joe Act", "created_at": "2020-05-30T00:00:00Z" }
Activates a user
POST /api/auth/activate/{verification_key}/
Activates a new user and returns a JSON Web Token that can subsequently be used to authenticate the new user in HTTP requests.
Request body
Username to identify the account
Password with which a user can authenticate with the service
Full name (effectively first name followed by last name)
Responses
200
Token used to authenticate user on every HTTP request
Examples
POST /api/auth/activate/0123456789abcef0123456789abcef/responds{ "username": "joe1", "new_password": "yoyo", "full_name": "Joe Card1" }
{ "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6 ImpvZTEiLCJlbWFpbCI6ImpvZSsxQGRqYW9kamluLmNvbSIsImZ1bGxfbmFtZ SI6IkpvZSAgQ2FyZDEiLCJleHAiOjE1Mjk2NTUyMjR9.GFxjU5AvcCQbVylF1P JwcBUUMECj8AKxsHtRHUSypco" }
Logs a user out
POST /api/auth/logout/
Removes all cookies associated with the session.
This API endpoint is only useful when the user is using Cookie-based authentication. Tokens expire; they cannot be revoked.
Responses
200
Examples
POST /api/auth/logout/Emails a password reset link
POST /api/auth/recover/
The user is uniquely identified by her email address.
Request body
Primary e-mail to contact user
Responses
200
Primary e-mail to contact user
Examples
POST /api/auth/recover/responds{ "email": "xia@localhost.localdomain" }
{ "email": "xia@localhost.localdomain" }
Registers a user
POST /api/auth/register/
Creates a new user and returns a JSON Web Token that can subsequently be used to authenticate the new user in HTTP requests.
Request body
Username to identify the account
Password with which a user can authenticate with the service
Primary e-mail to contact user
Full name (effectively first name followed by last name)
Responses
200
Token used to authenticate user on every HTTP request
Examples
POST /api/auth/register/responds{ "username": "joe1", "password": "yoyo", "email": "joe+1@example.com", "full_name": "Joe Card1" }
{ "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImpvZTEiLCJlbWFpbCI6ImpvZSsxQGRqYW9kamluLmNvbSIsImZ1bGxfbmFtZSI6IkpvZSAgQ2FyZDEiLCJleHAiOjE1Mjk2NTUyMjR9.GFxjU5AvcCQbVylF1PJwcBUUMECj8AKxsHtRHUSypco" }
Confirms a password reset
POST /api/auth/reset/{uidb64}/{token}/
Sets a new password after a recover password was triggered and returns a JSON Web Token that can subsequently be used to authenticate the new user in HTTP requests.
Request body
New password for the user referenced in the URL
Responses
200
Token used to authenticate user on every HTTP request
Examples
POST /api/auth/reset/0123456789abcef0123456789abcef/abc123/responds{ "new_password": "yoyo", "new_password2": "yoyo" }
{ "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 used to authenticate user on every HTTP request
Responses
200
Token used to authenticate user on every HTTP request
Examples
POST /api/auth/tokens/responds{ "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A" }
{ "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5Njk1NjA1fQ.-uuZb8R68jWw1Tc9FJocOWe1KHFklRffXbH0Rg6d_0c" }
Verifies a JSON Web Token
POST /api/auth/tokens/verify/
The authenticated user and the user associated to the token should be identical.
Request body
Token used to authenticate user on every HTTP request
Responses
200
Token used to authenticate user on every HTTP request
Examples
POST /api/auth/tokens/verify/responds{ "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A" }
{ "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A" }
Sends a contact-us message
POST /api/contact/
Emails a free form contact-us message from a customer to the provider
Request body
Responses
200
Describes the reason for the error in plain text
Examples
POST /api/contact/responds{ "email": "joe+1@example.com", "full_name": "Joe Card1", "message": "Can I request a demo?" }
{ "detail": "Your request has been sent. We will reply within24 hours. Thank you." }
Re-sends an activation link
POST /api/users/{user}/activate/
Re-sends an activation e-mail if the user is not already activated.
The template for the e-mail sent to the user can be found in notification/verification.eml.
Responses
200
Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.
Profile picture
E-mail address
Date/time of creation (in ISO format)
True if the user has valid login credentials
Examples
POST /api/users/donny/activate/{ "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 of the user making the HTTP request
Responses
200
Secret API Key used to authenticate user on every HTTP request
Examples
POST /api/users/donny/api-keys/responds{ "password": "secret" }
{ "secret": "tgLwDw5ErQ2pQr5TTdAzSYjvZenHC9pSy7fB3sXWERzynbG5zG6h 67pTN4dh7fpy" }
Changes a user password
PUT /api/users/{user}/password/
Request body
New password for the user referenced in the URL
Password of the user making the HTTP request
Responses
200
Describes the reason for the error in plain text
Examples
PUT /api/users/donny/password/responds{ "password": "yeye", "new_password": "yoyo" }
{ "detail": "Password updated successfully." }
Updates a user public RSA key
PUT /api/users/{user}/ssh-keys/
Request body
Password of the user making the HTTP request
New public key for the user referenced in the URL
Responses
200
Describes the reason for the error in plain text
Examples
PUT /api/users/donny/ssh-keys/responds{ "pubkey": "ssh-rsa AAAAB3N...", "password": "secret" }
{ "detail": "Public key updated successfully." }
Billing
This section contains APIs to manage the checkout, billing and accounting workflows, including shopping carts, coupons, charges and balance statements.
- Lists processor charges
- Retrieves a single processor charge
- Re-sends a charge receipt
- Refunds a processor charge
- Lists ledger transactions
- Retrieves a customer balance
- Cancels a balance due
- Retrieves a payout account
- Retrieves a payment method
- Updates a payment method
- Deletes a payment method
- Retrieves a user cart for checkout
- Checkouts a user cart
- Lists discount codes
- Retrieves a discount code
- Updates a discount code
- Deletes a discount code
- Lists subscriber transactions
- Lists provider receivables
- Lists provider payouts
- Inserts an offline transactions.
- Adds an item into a cart
- Removes an item from a cart
- Redeems a discount code
- Uploads multiple discount codes into a cart
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
A page number within the paginated result set.
Which field to use when ordering the results.
A search term.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
Total amount in currency unit
Three-letter ISO 4217 code for currency unit (ex: usd)
Amount and unit in a commonly accepted readable format
Description for the charge as appears on billing statements
Last 4 digits of the credit card used
Expiration date of the credit card used
Current state (i.e. created, done, failed, disputed)
Examples
GET /api/billing/charges?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc{ "count": 1, "unit": "usd", "total": "112120", "next": null, "previous": null, "results": [ { "created_at": "2016-01-01T00:00:02Z", "readable_amount": "$1121.20", "amount": 112120, "unit": "usd", "description": "Charge for subscription to cowork open-space", "last4": "1234", "exp_date": "2016-06-01", "processor_key": "ch_XAb124EF", "state": "DONE" } ] }
Retrieves a single processor charge
GET /api/billing/charges/{organization}/
Pass through to the processor and returns details about a Charge.
Responses
200
Date/time of creation (in ISO format)
Total amount in currency unit
Three-letter ISO 4217 code for currency unit (ex: usd)
Amount and unit in a commonly accepted readable format
Description for the charge as appears on billing statements
Last 4 digits of the credit card used
Expiration date of the credit card used
Current state (i.e. created, done, failed, disputed)
Examples
GET /api/billing/charges/ch_XAb124EF/{ "created_at": "2016-01-01T00:00:01Z", "readable_amount": "$1121.20", "amount": 112120, "unit": "usd", "description": "Charge for subscription to cowork open-space", "last4": "1234", "exp_date": "2016-06-01", "processor_key": "ch_XAb124EF", "state": "DONE" }
Re-sends a charge receipt
POST /api/billing/charges/{organization}/email/
Email the charge receipt to the customer email address on file.
The service sends a duplicate e-mail receipt for charge ch_XAb124EF to the e-mail address of the customer, i.e. joe@localhost.localdomain.
Responses
200
Charge identifier (i.e. matches the URL {charge} parameter)
E-mail address to which the receipt was sent.
Examples
POST /api/billing/charges/ch_XAb124EF/email/{ "charge_id": "ch_XAb124EF", "email": "joe@localhost.localdomain" }
Refunds a processor charge
POST /api/billing/charges/{organization}/refund/
Partially or totally refund all or a subset of line items on a Charge.
Request body
Line item index counting from zero.
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
Date/time of creation (in ISO format)
Total amount in currency unit
Three-letter ISO 4217 code for currency unit (ex: usd)
Amount and unit in a commonly accepted readable format
Description for the charge as appears on billing statements
Last 4 digits of the credit card used
Expiration date of the credit card used
Current state (i.e. created, done, failed, disputed)
Examples
POST /api/billing/charges/ch_XAb124EF/refund/responds{ "lines": [ { "num": 0, "refunded_amount": 4000 }, { "num": 1, "refunded_amount": 82120 } ] }
{ "created_at": "2016-01-01T00:00:05Z", "readable_amount": "$1121.20", "amount": 112120, "unit": "usd", "description": "Charge for subscription to cowork open-space", "last4": "1234", "exp_date": "2016-06-01", "processor_key": "ch_XAb124EF", "state": "DONE" }
Lists ledger transactions
GET /api/billing/transactions/
Queries a page (PAGE_SIZE records) of Transaction from the ledger.
The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).
Query results can be ordered by natural fields (o) in either ascending or descending order (ot).
Query parameters
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
Free-form text description for the transaction
Amount being transfered
True if the transaction is indentified as a debit in the API context
Source account from which funds are withdrawn
Source organization from which funds are withdrawn
Amount withdrawn from source in orig_unit
Three-letter ISO 4217 code for source currency unit (ex: usd)
Target account to which funds are deposited
Target organization to which funds are deposited
Amount deposited into target in dest_unit
Three-letter ISO 4217 code for target currency unit (ex: usd)
Examples
GET /api/billing/transactions?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc{ "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/{ "balance_amount": "1200", "balance_unit": "usd" }
Cancels a balance due
DELETE /api/billing/{organization}/balance/
Cancel the balance for a provider organization. This will create a transaction for this balance cancellation. A manager can use this endpoint to cancel balance dues that is known impossible to be recovered (e.g. an external bank or credit card company act).
The endpoint returns the transaction created to cancel the balance due.
Responses
204
Examples
DELETE /api/billing/cowork/balance/Retrieves a 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
Name of the deposit account
Last 4 characters of the deposit account identifier
Amount available to transfer to the provider deposit account
Three-letter ISO 4217 code for currency unit (ex: usd)
Examples
GET /api/billing/cowork/bank/{ "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
Last 4 digits of the credit card on file
Expiration date of the credit card on file
Examples
GET /api/billing/cowork/card/{ "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
Processor token to retrieve the payment method
Full name
E-mail address for the account
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Responses
200
Last 4 digits of the credit card on file
Expiration date of the credit card on file
Examples
PUT /api/billing/cowork/card/responds{ "token": "xyz" }
{ "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 /api/billing/cowork/card/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
Subscription lines and options refer to.
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
The subscription is set to auto-renew at the end of the period
True if the request user is able to update the subscription. Typically a manager for the plan provider.
Extra meta data (can be stringify JSON)
Line items to charge on checkout.
Date/time of creation (in ISO format)
Free-form text description for the transaction
Amount being transfered
True if the transaction is indentified as a debit in the API context
Source account from which funds are withdrawn
Source organization from which funds are withdrawn
Amount withdrawn from source in orig_unit
Three-letter ISO 4217 code for source currency unit (ex: usd)
Target account to which funds are deposited
Target organization to which funds are deposited
Amount deposited into target in dest_unit
Three-letter ISO 4217 code for target currency unit (ex: usd)
Options to replace line items.
Date/time of creation (in ISO format)
Free-form text description for the transaction
Amount being transfered
True if the transaction is indentified as a debit in the API context
Source account from which funds are withdrawn
Source organization from which funds are withdrawn
Amount withdrawn from source in orig_unit
Three-letter ISO 4217 code for source currency unit (ex: usd)
Target account to which funds are deposited
Target organization to which funds are deposited
Amount deposited into target in dest_unit
Three-letter ISO 4217 code for target currency unit (ex: usd)
Examples
GET /api/billing/xia/checkout{ "results": [ { "subscription": { "created_at": "2016-06-21T23:24:09.242925Z", "ends_at": "2016-10-21T23:24:09.229768Z", "description": null, "organization": { "slug": "xia", "full_name": "Xia", "printable_name": "Xia", "created_at": "2012-08-14T23:16:55Z", "email": "xia@localhost.localdomain" }, "plan": { "slug": "basic", "title": "Basic", "description": "Basic Plan", "is_active": true, "setup_amount": 0, "period_amount": 2000, "period_type": "monthly", "app_url": "/app/" }, "auto_renew": true }, "lines": [ { "created_at": "2016-06-21T23:42:13.863739Z", "description": "Subscription to basic until 2016/11/21 (1 month)", "amount": "$20.00", "is_debit": false, "orig_account": "Receivable", "orig_organization": "cowork", "orig_amount": 2000, "orig_unit": "usd", "dest_account": "Payable", "dest_organization": "xia", "dest_amount": 2000, "dest_unit": "usd" } ], "options": [] } ] }
Checkouts a user cart
POST /api/billing/{organization}/checkout/
Places an order for the subscription items in the cart and creates a Charge on the {organization} payment card.
If the charge fails a balance is due, to be collected later.
The cart is manipulated through various API endpoints:
/api/cart/redeem/ applies a coupon code for a potential discount.
/api/cart/ adds or updates a cart item.
/api/cart/{plan} removes a cart item.
Request body
selected plan option during checkout
attaches the payment card to the Organization when true
one-time token generated by the processorfrom the payment card.
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Responses
200
Date/time of creation (in ISO format)
Total amount in currency unit
Three-letter ISO 4217 code for currency unit (ex: usd)
Amount and unit in a commonly accepted readable format
Description for the charge as appears on billing statements
Last 4 digits of the credit card used
Expiration date of the credit card used
Current state (i.e. created, done, failed, disputed)
Examples
POST /api/billing/xia/checkoutresponds{ "remember_card": true, "processor_token": "tok_23prgoqpstf56todq" }
{ "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
A page number within the paginated result set.
Which field to use when ordering the results.
A search term.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier per provider, typically used in URLs
Type of discount (percentage or currency unit)
Amount of the discount
Date/time of creation (in ISO format)
Date/time at which the coupon code expires (in ISO format)
Free-form text description for the coupon
Number of times the coupon can be used
Examples
GET /api/billing/cowork/coupons?o=code&ot=asc&q=DIS{ "count": 2, "next": null, "previous": null, "results": [ { "code": "DIS100", "discount_type": "percentage", "amount": 10000, "created_at": "2014-01-01T09:00:00Z", "ends_at": null, "description": null }, { "code": "DIS50", "discount_type": "percentage", "amount": 5000, "created_at": "2014-01-01T09:00:00Z", "ends_at": null, "description": null } ] }
Retrieves a discount code
GET /api/billing/{organization}/coupons/{coupon}/
Responses
200
Unique identifier per provider, typically used in URLs
Type of discount (percentage or currency unit)
Amount of the discount
Date/time of creation (in ISO format)
Date/time at which the coupon code expires (in ISO format)
Free-form text description for the coupon
Number of times the coupon can be used
Examples
GET /api/billing/cowork/coupons/DIS100{ "code": "DIS100", "discount_type": "percentage", "amount": 10000, "created_at": "2014-01-01T09:00:00Z", "ends_at": null, "description": null }
Updates a discount code
PUT /api/billing/{organization}/coupons/{coupon}/
Request body
Type of discount (percentage or currency unit)
Amount of the discount
Date/time at which the coupon code expires (in ISO format)
Free-form text description for the coupon
Number of times the coupon can be used
Responses
200
Unique identifier per provider, typically used in URLs
Type of discount (percentage or currency unit)
Amount of the discount
Date/time of creation (in ISO format)
Date/time at which the coupon code expires (in ISO format)
Free-form text description for the coupon
Number of times the coupon can be used
Examples
PUT /api/billing/cowork/coupons/DIS100responds{ "discount_type": "percentage", "amount": 10000, "ends_at": null, "description": null }
{ "code": "DIS100", "discount_type": "percentage", "amount": 10000, "ends_at": null, "description": null }
Deletes a discount code
DELETE /api/billing/{organization}/coupons/{coupon}/
Only coupons which have never been applied to an oder will be permanently deleted. Coupons which have already be used at least once will be de-activated and still available for performance measurements.
Responses
204
Examples
DELETE /api/billing/cowork/coupons/DIS100Lists 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
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
Free-form text description for the transaction
Amount being transfered
True if the transaction is indentified as a debit in the API context
Source account from which funds are withdrawn
Source organization from which funds are withdrawn
Amount withdrawn from source in orig_unit
Three-letter ISO 4217 code for source currency unit (ex: usd)
Target account to which funds are deposited
Target organization to which funds are deposited
Amount deposited into target in dest_unit
Three-letter ISO 4217 code for target currency unit (ex: usd)
Examples
GET /api/billing/xia/history?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc{ "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
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
Free-form text description for the transaction
Amount being transfered
True if the transaction is indentified as a debit in the API context
Source account from which funds are withdrawn
Source organization from which funds are withdrawn
Amount withdrawn from source in orig_unit
Three-letter ISO 4217 code for source currency unit (ex: usd)
Target account to which funds are deposited
Target organization to which funds are deposited
Amount deposited into target in dest_unit
Three-letter ISO 4217 code for target currency unit (ex: usd)
Examples
GET /api/billing/cowork/receivables?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc{ "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
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
Free-form text description for the transaction
Amount being transfered
True if the transaction is indentified as a debit in the API context
Source account from which funds are withdrawn
Source organization from which funds are withdrawn
Amount withdrawn from source in orig_unit
Three-letter ISO 4217 code for source currency unit (ex: usd)
Target account to which funds are deposited
Target organization to which funds are deposited
Amount deposited into target in dest_unit
Three-letter ISO 4217 code for target currency unit (ex: usd)
Examples
GET /api/billing/cowork/transfers?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc{ "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
The subscription the offline transaction refers to.
Date/time of creation (in ISO format)
Free-form text description for the transaction
Responses
200
The subscription the offline transaction refers to.
Date/time of creation (in ISO format)
Free-form text description for the transaction
Examples
POST /api/billing/cowork/transfers/import/responds{ "created_at": "2020-05-30T00:00:00Z", "amount": "10.00", "descr": "Paid by check", "subscription": "demo562-open-plus" }
{ "created_at": "2020-05-30T00:00:00Z", "amount": "10.00", "descr": "Paid by check", "subscription": "demo562-open-plus" }
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
The plan to add into the request.user cart.
Full name of the person that will benefit from the subscription (GroupBuy)
Responses
200
The plan to add into the request.user cart.
Full name of the person that will benefit from the subscription (GroupBuy)
Examples
POST /api/cart/responds{ "plan": "open-space", "option": 1 }
{ "plan": "open-space", "option": 1 }
Removes an item from a cart
DELETE /api/cart/
Removes an item from the request.user cart.
Responses
204
Examples
DELETE /api/cart/?plan=open-spaceRedeems a discount code
POST /api/cart/redeem/
Redeems a Coupon and applies the discount to the eligible items in the cart.
Request body
Coupon code to redeem
Responses
200
Describes the reason for the error in plain text
Examples
POST /api/cart/redeemresponds{ "code": "LABORDAY" }
{ "detail": "Coupon 'LABORDAY' was successfully applied." }
Uploads multiple discount codes into a cart
POST /api/cart/{plan}/upload/
Add a Plan into the subscription cart of multiple users as per the content of an uploaded file.
This works bulk fashion of /cart/ endpoint. The uploaded file must be a CSV containing the fields first_name, last_name and email. The CSV file must not contain a header line, only data.
Responses
200
Examples
POST /api/cart/basic/upload/{ "created": [ { "first_name": "Joe", "last_name": "Smith", "email": "joesmith@example.com" }, { "first_name": "Marie", "last_name": "Johnson", "email": "mariejohnson@example.com" } ], "updated": [], "failed": [] }
Remove tags from an editable node
PUT /api/themes/editables/{slug}/remove-tags/
Remove tags from a PageElement.
Request body
Responses
200
Examples
PUT /api/editables/_my-element_/reomve-tagsresponds{ "tag": "sometag" }
{}
Metrics
The metrics APIs crunch the numbers and return various insight into the performance for the business. They are used to implement a balances dashboard for example.
- Retrieves a balance sheet
- Retrieves row headers for a balance sheet
- Creates a row in a balance sheet
- Retrieves a row in a balance sheet
- Updates a row in a balance sheet
- Deletes a row in a balance sheet
- Lists top of funnel registered users
- Lists active subscriptions
- Retrieves a default balance sheet
- Lists churned subscriptions
- Retrieves performance of a discount code
- Retrieves 12-month trailing customer counts
- Retrieves 12-month trailing revenue
- Retrieves 12-month trailing plans performance
- Retrieves recently active users
- Retrieves news and items to take care of.
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
The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)
Three-letter ISO 4217 code for currency unit (ex: usd)
Title for the table
Unique key in the table for the data series
Filter on the Transaction accounts
Datapoints in the serie
Examples
GET /api/metrics/balances/taxes/{ "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
A page number within the paginated result set.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Title for the row
Filter on the Transaction accounts
Absolute position of the row in the list of rows for the table
Examples
GET /api/metrics/balances/taxes/lines/{ "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 for the row
Filter on the Transaction accounts
Absolute position of the row in the list of rows for the table
Responses
200
Title for the row
Filter on the Transaction accounts
Absolute position of the row in the list of rows for the table
Examples
POST /api/metrics/balances/taxes/lines/responds{ "title": "Sales", "selector": "Receivable", "rank": 1 }
{ "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 for the row
Filter on the Transaction accounts
Absolute position of the row in the list of rows for the table
Examples
GET /api/metrics/balances/taxes/lines/1/{ "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 for the row
Filter on the Transaction accounts
Absolute position of the row in the list of rows for the table
Responses
200
Title for the row
Filter on the Transaction accounts
Absolute position of the row in the list of rows for the table
Examples
PUT /api/metrics/balances/taxes/lines/1/responds{ "title": "Sales", "selector": "Receivable", "rank": 1 }
{ "title": "Sales", "selector": "Receivable", "rank": 1 }
Deletes a row in a balance sheet
DELETE /api/metrics/balances/{report}/lines/{rank}/
Deletes a row reported on a balance sheet named {report}.
Responses
204
Examples
DELETE /api/metrics/balances/taxes/lines/1/Lists top of funnel registered users
GET /api/metrics/registered/
Lists all User which have no associated role or a role to an Organization which has no Subscription, active or inactive.
The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).
Query results can be ordered by natural fields (o) in either ascending or descending order (ot).
Query parameters
A page number within the paginated result set.
Which field to use when ordering the results.
A search term.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.
E-mail address for the user
Full name for the contact (effectively first name followed by last name)
Date/time of creation (in ISO format)
Examples
GET /api/metrics/registered?o=created_at&ot=desc{ "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
A page number within the paginated result set.
Which field to use when ordering the results.
A search term.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
The subscription is set to auto-renew at the end of the period
True if the request user is able to update the subscription. Typically a manager for the plan provider.
Extra meta data (can be stringify JSON)
Examples
GET /api/metrics/cowork/active?o=created_at&ot=desc{ "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
A page number within the paginated result set.
Responses
200
The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)
Three-letter ISO 4217 code for currency unit (ex: usd)
Title for the table
Unique key in the table for the data series
Filter on the Transaction accounts
Datapoints in the serie
Examples
GET /api/metrics/cowork/balances{ "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
A page number within the paginated result set.
Which field to use when ordering the results.
A search term.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
The subscription is set to auto-renew at the end of the period
True if the request user is able to update the subscription. Typically a manager for the plan provider.
Extra meta data (can be stringify JSON)
Examples
GET /api/metrics/cowork/churned?o=created_at&ot=desc{ "count": 1, "next": null, "previous": null, "results": [ { "created_at": "2016-01-14T23:16:55Z", "ends_at": "2017-01-14T23:16:55Z", "description": null, "organization": { "slug": "xia", "printable_name": "Xia Lee" }, "plan": { "slug": "open-space", "title": "Open Space", "description": "open space desk, High speed internet- Ethernet or WiFi, Unlimited printing,Unlimited scanning, Unlimited fax service(send and receive)", "is_active": true, "setup_amount": 0, "period_amount": 17999, "interval": 4, "app_url": "http://localhost:8020/app" }, "auto_renew": true } ] }
Retrieves performance of a discount code
GET /api/metrics/{organization}/coupons/{coupon}/
Queries a page (PAGE_SIZE records) of Coupon usage.
The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).
The result queryset can be ordered by passing an o (field name) and ot (asc or desc) parameter.
Query parameters
Which field to use when ordering the results.
A search term.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.
E-mail address for the user
Full name for the contact (effectively first name followed by last name)
Date/time of creation (in ISO format)
Full name of the person that will benefit from the subscription (GroupBuy)
Examples
GET /api/metrics/cowork/coupons/DIS100/{ "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
A page number within the paginated result set.
Responses
200
The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)
Three-letter ISO 4217 code for currency unit (ex: usd)
Title for the table
Unique key in the table for the data series
Filter on the Transaction accounts
Datapoints in the serie
Examples
GET /api/metrics/cowork/customers{ "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
A page number within the paginated result set.
Responses
200
The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)
Three-letter ISO 4217 code for currency unit (ex: usd)
Title for the table
Unique key in the table for the data series
Filter on the Transaction accounts
Datapoints in the serie
Examples
GET /api/metrics/cowork/funds/{ "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
A page number within the paginated result set.
Responses
200
The scale of the number reported in the tables (ex: 1000 when numbers are reported in thousands of dollars)
Three-letter ISO 4217 code for currency unit (ex: usd)
Title for the table
Unique key in the table for the data series
Filter on the Transaction accounts
Datapoints in the serie
Examples
GET /api/metrics/cowork/plans{ "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
A page number within the paginated result set.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Examples
GET /api/proxy/recent/{ "count": 1, "next": null, "previous": null, "results": [ { "printable_name": "Alice Cooper", "descr": "recently logged in", "created_at": "2019-07-15T20:40:29.509572Z", "slug": "alice" } ] }
Retrieves news and items to take care of.
GET /api/todos/
Query parameters
A page number within the paginated result set.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
User that created the activity
Free form text description of the activity
Account the activity is associated to
Examples
GET /api/todos/{ "count": 1, "next": null, "previous": null, "results": [ { "created_at": "20200530T00:00:00Z", "created_by": "djaoapp", "text": "connect processor", "account": null } ] }
Profile
This section contains APIs to manage the identity, such as name or email address, of users and organizations registered to the site.
- Searches billing and login profiles
- Searches billing profiles
- Searches login profiles
- Creates a user profile
- Updates a login profile
- Deletes a login profile
- Lists activities for a contact
- Records new activity with a contact
- Signs a consent agreement
- Lists billing profiles
- Creates a billing profile
- Retrieves a billing profile
- Updates a billing profile
- Deletes a billing profile
- Lists user profiles
- Creates a user profile
- Retrieves a login profile
- Updates a login profile
- Deletes a login profile
- Changes a user notifications preferences
- List billing profiles owned by user
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
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Examples
GET /api/accounts/?o=created_at{ "count": 1, "next": null, "previous": null, "results": [ { "slug": "xia", "full_name": "Xia Lee", "email": "xia@localhost.localdomain", "created_at": "2016-01-14T23:16:55Z", "printable_name": "Xia Lee" } ] }
Searches billing profiles
GET /api/accounts/profiles/
Queries a page (PAGE_SIZE records) of candidate profiles based of a search criteria (q).
This API differs from /api/profile in that it is designed to be used in auto-completion input fields instead of designed to list all profiles.
The queryset can be ordered by a field by adding an HTTP query parameter o= followed by the field name. A sequence of fields can be used to create a complete ordering by adding a sequence of o HTTP query parameters. To reverse the natural order of a field, prefix the field name by a minus (-) sign.
Query parameters
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Examples
GET /api/accounts/profiles/?q=xia{ "count": 1, "next": null, "previous": null, "results": [ { "slug": "xia", "full_name": "Xia Lee", "email": "xia@localhost.localdomain", "created_at": "2016-01-14T23:16:55Z", "printable_name": "Xia Lee" } ] }
Searches login profiles
GET /api/accounts/users/
Queries a page (PAGE_SIZE records) of User.
The queryset can be filtered to a range of dates ([start_at, ends_at]) and for at least one field to match a search term (q).
Query results can be ordered by natural fields (o) in either ascending or descending order (ot).
Query parameters
A page number within the paginated result set.
Which field to use when ordering the results.
A search term.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.
E-mail address for the user
Full name for the contact (effectively first name followed by last name)
Date/time of creation (in ISO format)
Examples
GET /api/accounts/users/?o=created_at&ot=desc{ "count": 1, "next": null, "previous": null, "results": [ { "slug": "alice", "email": "alice@djaodjin.com", "full_name": "Alice Cooper", "created_at": "2014-01-01T00:00:00Z" } ] }
Creates a user profile
POST /api/contacts/
Request body
Profile picture
E-mail address
Full name (effectively first name followed by last name)
Short casual name used to address the contact
Extra meta data (can be stringify JSON)
Responses
200
Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.
Profile picture
E-mail address
Date/time of creation (in ISO format)
True if the user has valid login credentials
Full name (effectively first name followed by last name)
Short casual name used to address the contact
Extra meta data (can be stringify JSON)
Date/time of creation (in ISO format)
User that created the activity
Free form text description of the activity
Account the activity is associated to
Examples
POST /api/users/responds{ "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "nick_name": "Xia" }
{ "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "nick_name": "Xia" }
Updates a login profile
PUT /api/contacts/{user}/
Request body
Profile picture
E-mail address
Full name (effectively first name followed by last name)
Short casual name used to address the contact
Extra meta data (can be stringify JSON)
Responses
200
Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.
Profile picture
E-mail address
Date/time of creation (in ISO format)
True if the user has valid login credentials
Full name (effectively first name followed by last name)
Short casual name used to address the contact
Extra meta data (can be stringify JSON)
Date/time of creation (in ISO format)
User that created the activity
Free form text description of the activity
Account the activity is associated to
Examples
PUT /api/users/xia/responds{ "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "nick_name": "Xia" }
{ "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "nick_name": "Xia" }
Examples
DELETE /api/users/xia/Lists activities for a contact
GET /api/contacts/{user}/activities/
Returns PAGE_SIZE activity records for a user.
Query parameters
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
User that created the activity
Free form text description of the activity
Account the activity is associated to
Examples
GET /api/contacts/xia/activities{ "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
Free form text description of the activity
Account the activity is associated to
Responses
200
Date/time of creation (in ISO format)
User that created the activity
Free form text description of the activity
Account the activity is associated to
Examples
POST /api/contacts/xia/activities/responds{ "text": "Phone call", "account": null }
{ "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
I have read and understand these terms and conditions
Responses
200
I have read and understand these terms and conditions
Examples
POST /api/legal/terms-of-use/sign/responds{ "read_terms": true }
{ "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
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Examples
GET /api/profile/?o=created_at&ot=desc{ "count": 1, "next": null, "previous": null, "results": [ { "slug": "xia", "full_name": "Xia Lee", "email": "xia@localhost.localdomain", "created_at": "2016-01-14T23:16:55Z", "printable_name": "Xia Lee" } ] }
Creates a billing profile
POST /api/profile/
Request body
Unique identifier shown in the URL bar
Full name
Timezone to use when reporting metrics
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Extra meta data (can be stringify JSON)
One of 'organization', 'personal' or 'user'
Responses
200
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Examples
POST /api/profile/responds{ "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "type": "personal" }
{ "slug": "xia", "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "printable_name": "Xia Lee", "type": "personal", "credentials": true, "default_timezone": "America/Los_Angeles", "phone": "", "street_address": "", "locality": "", "region": "", "postal_code": "", "country": "US", "is_bulk_buyer": false, "extra": null }
Retrieves a billing profile
GET /api/profile/{organization}/
Responses
200
Unique identifier shown in the URL bar
Date/time of creation (in ISO format)
Full name
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
The subscription is set to auto-renew at the end of the period
Profile picture
Examples
GET /api/profile/xia/{ "created_at": "2018-01-01T00:00:00Z", "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "printable_name": "Xia Lee", "slug": "xia", "phone": "555-555-5555", "street_address": "185 Berry St #550", "locality": "San Francisco", "region": "CA", "postal_code": "", "country": "US", "default_timezone": "Europe/Kiev", "is_provider": false, "is_bulk_buyer": false, "type": "", "picture": "", "subscriptions": [ { "created_at": "2018-01-01T00:00:00Z", "ends_at": "2019-01-01T00:00:00Z", "plan": "open-space", "auto_renew": true } ] }
Updates a billing profile
PUT /api/profile/{organization}/
Request body
Unique identifier shown in the URL bar
Full name
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Responses
200
Unique identifier shown in the URL bar
Date/time of creation (in ISO format)
Full name
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
The subscription is set to auto-renew at the end of the period
Profile picture
Examples
PUT /api/profile/xia/responds{ "email": "xia@locahost.localdomain", "full_name": "Xia Lee" }
{ "created_at": "2018-01-01T00:00:00Z", "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "printable_name": "Xia Lee", "slug": "xia", "subscriptions": [ { "created_at": "2018-01-01T00:00:00Z", "ends_at": "2019-01-01T00:00:00Z", "plan": "open-space", "auto_renew": true } ] }
Deletes a billing profile
DELETE /api/profile/{organization}/
We anonymize the organization instead of purely deleting it from the database because we don't want to loose history on subscriptions and transactions.
Responses
204
Examples
DELETE /api/profile/xia/Lists user profiles
GET /api/users/
Queries a page (PAGE_SIZE records) of organization and user profiles.
The queryset can be filtered for at least one field to match a search term (q).
The queryset can be ordered by a field by adding an HTTP query parameter o= followed by the field name. A sequence of fields can be used to create a complete ordering by adding a sequence of o HTTP query parameters. To reverse the natural order of a field, prefix the field name by a minus (-) sign.
Query parameters
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.
Profile picture
E-mail address
Date/time of creation (in ISO format)
True if the user has valid login credentials
Examples
GET /api/users/?q=xia{ "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
Profile picture
E-mail address
Full name (effectively first name followed by last name)
Short casual name used to address the contact
Extra meta data (can be stringify JSON)
Responses
200
Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.
Profile picture
E-mail address
Date/time of creation (in ISO format)
True if the user has valid login credentials
Full name (effectively first name followed by last name)
Short casual name used to address the contact
Extra meta data (can be stringify JSON)
Date/time of creation (in ISO format)
User that created the activity
Free form text description of the activity
Account the activity is associated to
Examples
POST /api/users/responds{ "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "nick_name": "Xia" }
{ "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "nick_name": "Xia" }
Retrieves a login profile
GET /api/users/{user}/
Retrieves details on one single user profile with slug {user}.
Responses
200
Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.
Profile picture
E-mail address
Date/time of creation (in ISO format)
True if the user has valid login credentials
Full name (effectively first name followed by last name)
Short casual name used to address the contact
Extra meta data (can be stringify JSON)
Date/time of creation (in ISO format)
User that created the activity
Free form text description of the activity
Account the activity is associated to
Examples
GET /api/users/xia{ "slug": "xia", "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "nick_name": "Xia", "created_at": "2018-01-01T00:00:00Z", "activities": [ { "created_at": "2018-01-01T00:00:00Z", "created_by": "alice", "text": "Phone call", "account": null }, { "created_at": "2018-01-02T00:00:00Z", "created_by": "alice", "text": "Follow up e-mail", "account": "cowork" } ] }
Updates a login profile
PUT /api/users/{user}/
Request body
Profile picture
E-mail address
Full name (effectively first name followed by last name)
Short casual name used to address the contact
Extra meta data (can be stringify JSON)
Responses
200
Unique identifier shown in the URL bar, effectively the username for profiles with login credentials.
Profile picture
E-mail address
Date/time of creation (in ISO format)
True if the user has valid login credentials
Full name (effectively first name followed by last name)
Short casual name used to address the contact
Extra meta data (can be stringify JSON)
Date/time of creation (in ISO format)
User that created the activity
Free form text description of the activity
Account the activity is associated to
Examples
PUT /api/users/xia/responds{ "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "nick_name": "Xia" }
{ "email": "xia@locahost.localdomain", "full_name": "Xia Lee", "nick_name": "Xia" }
Examples
DELETE /api/users/xia/Changes a user notifications preferences
PUT /api/users/{user}/notifications/
Request body
Responses
200
Examples
POST /api/users/donny/notifications/responds{ "notifications": [ "user_registered_notice" ] }
{ "notifications": [ "user_registered_notice" ] }
List billing profiles owned by user
GET /api/users/{user}/profiles/
Queries a page (PAGE_SIZE records) of organization and user profiles.
The queryset can be filtered for at least one field to match a search term (q).
The queryset can be ordered by a field by adding an HTTP query parameter o= followed by the field name. A sequence of fields can be used to create a complete ordering by adding a sequence of o HTTP query parameters. To reverse the natural order of a field, prefix the field name by a minus (-) sign.
Query parameters
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Examples
GET /api/users/xia/profiles/?o=created_at{ "count": 1, "next": null, "previous": null, "results": [ { "slug": "xia", "full_name": "Xia Lee", "email": "xia@localhost.localdomain", "printable_name": "Xia Lee", "created_at": "2016-01-14T23:16:55Z" } ] }
Roles & rules
This section contains APIs to manage the checkout, billing and accounting workflows, including shopping carts, coupons, charges and balance statements.
- Lists roles for an organization
- Lists role types
- Creates a role type
- Retrieves a role type
- Updates a role type
- Deletes a role type
- Lists roles of a specific type
- Creates a role
- Re-sends role invite
- Deletes a role
- Grants a subscription request
- Returns the URL endpoint to which requests passing the access rules
- Updates forward end-point
- Retrieves users engagement
- Retrieves engagement metrics
- Rotates session encoding key
- Lists access rules
- Creates an access rule
- Retrieves an access rule
- Updates an access rule
- Deletes an access rule
- Retrieves example session
- Lists roles by user
- Requests a role
- Accepts role invite
- Lists roles of specific type by user
- Requests a role of a specified type
- Re-sends request for role
- Deletes a role by type
- Creates a new profile owned by user
Lists roles for an organization
GET /api/profile/{organization}/roles/
Query parameters
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.
E-mail address for the user
Full name for the contact (effectively first name followed by last name)
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
GET /api/profile/cowork/roles/{ "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``.
Query parameters
A page number within the paginated result set.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
GET /api/profile/cowork/roles/describe/{ "count": 2, "next": null, "previous": null, "results": [ { "created_at": "2018-01-01T00:00:00Z", "title": "Managers", "slug": "manager", "is_global": true }, { "created_at": "2018-01-01T00:00:00Z", "title": "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.
Request body
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Extra meta data (can be stringify JSON)
Responses
200
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
POST /api/profile/cowork/roles/describe/responds{ "title": "Support" }
{ "created_at": "2018-01-01T00:00:00Z", "title": "Support", "slug": "support", "is_global": false, "roles": [] }
Retrieves a role type
GET /api/profile/{organization}/roles/describe/{role}/
Responses
200
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
GET /api/profile/cowork/roles/describe/manager{ "created_at": "2018-01-01T00:00:00Z", "slug": "manager", "title": "Profile Managers", "is_global": true, "roles": [ { "created_at": "2018-01-01T00:00:00Z", "user": { "slug": "donny", "email": "donny@localhost.localdomain", "full_name": "Donny Cooper", "created_at": "2018-01-01T00:00:00Z" }, "request_key": null, "grant_key": null } ] }
Updates a role type
PUT /api/profile/{organization}/roles/describe/{role}/
Request body
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Extra meta data (can be stringify JSON)
Responses
200
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
PUT /api/profile/cowork/roles/describe/managerresponds{ "title": "Profile managers" }
{ "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 } ] }
Examples
DELETE /api/profile/cowork/roles/describe/managerLists roles of a specific type
GET /api/profile/{organization}/roles/{role}/
Lists the specified role assignments for an organization.
Query parameters
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.
E-mail address for the user
Full name for the contact (effectively first name followed by last name)
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
GET /api/profile/cowork/roles/manager/{ "count": 1, "next": null, "previous": null, "results": [ { "created_at": "2018-01-01T00:00:00Z", "role_description": { "name": "Manager", "slug": "manager", "organization": { "slug": "cowork", "full_name": "ABC Corp.", "printable_name": "ABC Corp.", "created_at": "2018-01-01T00:00:00Z", "email": "support@localhost.localdomain" } }, "user": { "slug": "alice", "email": "alice@localhost.localdomain", "full_name": "Alice Doe", "created_at": "2018-01-01T00:00:00Z" }, "request_key": "1", "grant_key": null } ] }
Creates a role
POST /api/profile/{organization}/roles/{role}/
Attaches a user to a role on an organization, typically granting permissions to the user with regards to managing an organization profile (see Flexible Security Framework).
Request body
Username
E-mail of the invitee
Full name
Message to send along the invitation
Responses
200
Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.
E-mail address for the user
Full name for the contact (effectively first name followed by last name)
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
POST /api/profile/cowork/roles/manager/responds{ "slug": "xia" }
{ "slug": "xia" }
Re-sends role invite
POST /api/profile/{organization}/roles/{role}/{user}/
Re-sends the invite e-mail that the user was granted a role on the organization.
Responses
200
Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.
E-mail address for the user
Full name for the contact (effectively first name followed by last name)
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
POST /api/profile/cowork/roles/manager/xia/{ "created_at": "2018-01-01T00:00:00Z", "role_description": { "created_at": "2018-01-01T00:00:00Z", "title": "Profile Manager", "slug": "manager", "is_global": true, "organization": { "slug": "cowork", "full_name": "ABC Corp.", "printable_name": "ABC Corp.", "created_at": "2018-01-01T00:00:00Z", "email": "support@localhost.localdomain" } }, "user": { "slug": "alice", "email": "alice@localhost.localdomain", "full_name": "Alice Doe", "created_at": "2018-01-01T00:00:00Z" }, "request_key": "1", "grant_key": null }
Deletes a role
DELETE /api/profile/{organization}/roles/{role}/{user}/
Dettach a user from one or all roles with regards to an organization, typically resulting in revoking permissions from this user to manage part of an organization profile.
Responses
204
Examples
DELETE /api/profile/cowork/roles/manager/xia/Grants a subscription request
POST /api/profile/{organization}/subscribers/accept/{request_key}/
Accepts a subscription request.
Responses
200
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
The subscription is set to auto-renew at the end of the period
True if the request user is able to update the subscription. Typically a manager for the plan provider.
Extra meta data (can be stringify JSON)
Examples
None None{ "created_at": "2019-01-01T00:00:00Z", "ends_at": "2020-01-01T00:00:00Z", "description": null, "organization": { "slug": "xia", "created_at": "2019-01-01T00:00:00Z", "full_name": "Xia Lee", "email": "xia@localhost.localdomain", "phone": "555-555-5555", "street_address": "350 Bay St.", "locality": "San Francisco", "region": "CA", "postal_code": "94133", "country": "US", "default_timezone": "UTC", "printable_name": "Xia Lee", "is_provider": false, "is_bulk_buyer": false, "type": "personal", "credentials": true, "extra": null }, "plan": { "slug": "open-space", "title": "Open Space", "description": "open space desk", "is_active": true, "setup_amount": 0, "period_amount": 17999, "period_length": 1, "interval": "monthly", "unit": "cad", "organization": "cowork", "renewal_type": "auto-renew", "is_not_priced": false, "created_at": "2019-01-01T00:00:00Z", "skip_optin_on_grant": false, "optin_on_request": false, "extra": null }, "auto_renew": true, "editable": true, "extra": null, "grant_key": null, "request_key": null }
Returns the URL endpoint to which requests passing the access rules
GET /api/proxy/
are forwarded to, and the format in which the session information is encoded.
When running tests, you can retrieve the actual session information for a specific user through the /proxy/sessions/{user}/ API call.
Responses
200
unique identifier for the site (also serves as subdomain)
Entry point to which requests will be redirected to
Format to encode session in the forwarded HTTP request
Restricted authentication and registration
Send a welcome e-mail to newly registered users
Examples
GET /api/proxy/{ "slug": "cowork", "entry_point": "https://cowork.herokuapp.com/", "session_backend": 1 }
Updates forward end-point
PUT /api/proxy/
Updates the URL endpoint to which requests passing the access rules are forwarded to and/or the format in which the session information is encoded.
Request body
Entry point to which requests will be redirected to
Format to encode session in the forwarded HTTP request
Restricted authentication and registration
Send a welcome e-mail to newly registered users
Responses
200
unique identifier for the site (also serves as subdomain)
Entry point to which requests will be redirected to
Format to encode session in the forwarded HTTP request
Restricted authentication and registration
Send a welcome e-mail to newly registered users
Examples
PUT /api/proxy/responds{ "entry_point": "https://cowork.herokuapp.com/", "session_backend": 1 }
{ "slug": "cowork", "entry_point": "https://cowork.herokuapp.com/", "session_backend": 1 }
Retrieves users engagement
GET /api/proxy/engagement/
Query parameters
A page number within the paginated result set.
Responses
200
Examples
GET /api/proxy/engagement/{ "active_users": 10, "engagements": [] }
Retrieves engagement metrics
GET /api/proxy/engagement/users/
Query parameters
A page number within the paginated result set.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.
Examples
GET /api/proxy/engagement/users/{ "count": 2, "next": null, "previous": null, "results": [ { "username": "alice", "engagements": [ "app", "profile" ] }, { "username": "kenneth", "engagements": [ "app", "billing" ] } ] }
Rotates session encoding key
POST /api/proxy/key/
Rotates the key used to encode the session information forwarded to the application entry point.
Responses
200
Key used to decrypt the encoded session information.
Examples
POST /api/proxy/key/{ "enc_key": "********" }
Lists access rules
GET /api/proxy/rules
Queries a page (PAGE_SIZE records) of Rule.
Query parameters
A page number within the paginated result set.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Determines the order in which rules are considered
OpenAPI path against which requests are matched
Method applied to grant or deny access
When access is granted, should the request be forwarded
Tags to check if it is the first time a user engages
Examples
GET /api/proxy/rules{ "count": 1, "next": null, "previous": null, "results": [ { "rank": 0, "path": "/", "allow": "authenticated", "is_forward": true, "engaged": "app" } ] }
Creates an access rule
POST /api/proxy/rules
Request body
Determines the order in which rules are considered
OpenAPI path against which requests are matched
Method applied to grant or deny access
When access is granted, should the request be forwarded
Tags to check if it is the first time a user engages
Responses
200
Examples
POST /api/proxy/rules/{ "rank": 0, "path": "/", "allow": "authenticated", "is_forward": true, "engaged": "" }
Retrieves an access rule
GET /api/proxy/rules{rule}
Responses
200
Determines the order in which rules are considered
OpenAPI path against which requests are matched
Method applied to grant or deny access
When access is granted, should the request be forwarded
Tags to check if it is the first time a user engages
Examples
GET /api/proxy/rules/app/{ "rank": 0, "path": "/app/", "allow": "authenticated", "is_forward": true, "engaged": "" }
Updates an access rule
PUT /api/proxy/rules{rule}
Request body
Determines the order in which rules are considered
Method applied to grant or deny access
When access is granted, should the request be forwarded
Tags to check if it is the first time a user engages
Responses
200
Determines the order in which rules are considered
OpenAPI path against which requests are matched
Method applied to grant or deny access
When access is granted, should the request be forwarded
Tags to check if it is the first time a user engages
Examples
PUT /api/proxy/rules/app/responds{ "rank": 0, "path": "/app/", "allow": "authenticated", "is_forward": true, "engaged": "" }
{ "rank": 0, "path": "/app/", "allow": "authenticated", "is_forward": true, "engaged": "" }
Examples
DELETE /api/proxy/rules/app/Retrieves example session
GET /api/proxy/sessions/{user}/
Returns a session data for a user as it will be passed to the backend service.
Responses
200
The session being forwarded
The HTTP header that encodes the session
The URL end point where the request is forwarded
Examples
GET /api/proxy/sessions/xia/{ "forward_session": "{username: xia}", "forward_session_header": "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzbHVnIjoieGlhIiwicHJpbnRhYmxlX25hbWUiOiJYaWEgTGVlIiwicGljdHVyZSI6bnVsbCwiZW1haWwiOiJzbWlyb2xvKzExQGRqYW9kamluLmNvbSIsImNyZWF0ZWRfYXQiOiIyMDIxLTAxLTAxVDAwOjAwOjAwWiIsImNyZWRlbnRpYWxzIjp0cnVlLCJ1c2VybmFtZSI6InhpYSIsImZ1bGxfbmFtZSI6IlhpYSBMZWUiLCJleHAiOjE2MzI5MzM0NDJ9.ZFA3-LH3O7z7JVZdpBLz0AbnZd-zFtqiehk40Jc5uya", "forward_url": "https://cowork.herokuapp.com/" }
Lists roles by user
GET /api/users/{user}/accessibles/
Lists all relations where an Organization is accessible by a User. Typically the user was granted specific permissions through a Role.
Query parameters
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
GET /api/users/alice/accessibles/{ "count": 1, "next": null, "previous": null, "results": [ { "slug": "cowork", "created_at": "2018-01-01T00:00:00Z", "printable_name": "ABC Corp.", "email": "help@cowork.net", "role_description": { "slug": "manager", "created_at": "2018-01-01T00:00:00Z", "title": "Profile Manager", "is_global": true, "organization": null }, "request_key": null, "accept_grant_api_url": null, "remove_api_url": "https://cowork.net/api/users/alice/accessibles/manager/cowork", "home_url": "https://cowork.net/app/", "settings_url": "https://cowork.net/profile/cowork/contact/" } ] }
Requests a role
POST /api/users/{user}/accessibles/
Creates a request to attach a user to a role on an organization
Request body
Responses
200
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
POST /api/users/xia/accessibles/responds{ "slug": "cowork" }
{ "organization": { "slug": "cowork", "full_name": "Cowork", "printable_name": "Cowork", "picture": null, "type": "organization", "credentials": false }, "created_at": "2020-06-06T04:55:41.766938Z", "request_key": "53a1b0657c7cf738514bf791e6f20f36429e57aa", "role_description": null, "home_url": "/app/cowork/", "settings_url": "/profile/cowork/contact/", "accept_grant_api_url": null, "remove_api_url": "/api/users/xia/accessibles/manager/cowork" }
Accepts role invite
PUT /api/users/{user}/accessibles/accept/{verification_key}/
Accepts a role on an organization.
Responses
200
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
PUT /api/users/xia/accessibles/accept/0123456789abcef/{ "created_at": "2018-01-01T00:00:00Z", "role_description": { "created_at": "2018-01-01T00:00:00Z", "title": "Profile Manager", "slug": "manager", "is_global": true, "organization": { "slug": "cowork", "full_name": "ABC Corp.", "printable_name": "ABC Corp.", "created_at": "2018-01-01T00:00:00Z", "email": "support@localhost.localdomain" } }, "user": { "slug": "alice", "email": "alice@localhost.localdomain", "full_name": "Alice Doe", "created_at": "2018-01-01T00:00:00Z" }, "request_key": "1", "grant_key": null }
Lists roles of specific type by user
GET /api/users/{user}/accessibles/{role}/
Lists all relations where a User has a specified Role on an Organization.
Query parameters
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
GET /api/users/alice/accessibles/manager/{ "count": 1, "next": null, "previous": null, "results": [ { "slug": "cowork", "created_at": "2018-01-01T00:00:00Z", "printable_name": "ABC Corp.", "email": "help@cowork.net", "role_description": { "slug": "manager", "created_at": "2018-01-01T00:00:00Z", "title": "Profile manager", "is_global": true, "organization": null }, "request_key": null, "accept_grant_api_url": null, "remove_api_url": "https://cowork.net/api/users/alice/accessibles/manager/cowork", "home_url": "https://cowork.net/app/", "settings_url": "https://cowork.net/profile/cowork/contact/" } ] }
Requests a role of a specified type
POST /api/users/{user}/accessibles/{role}/
Creates a request to attach a user to an organization with a specified role.
Request body
Responses
200
Examples
POST /api/users/xia/accessibles/manager/responds{ "slug": "cowork" }
{ "organization": { "slug": "cowork", "full_name": "Cowork", "printable_name": "Cowork", "picture": null, "type": "organization", "credentials": false }, "created_at": "2020-06-06T04:55:41.766938Z", "request_key": "53a1b0657c7cf738514bf791e6f20f36429e57aa", "role_description": { "slug": "manager", "created_at": "2018-01-01T00:00:00Z", "title": "Profile manager", "is_global": true, "organization": null }, "home_url": "/app/cowork/", "settings_url": "/profile/cowork/contact/", "accept_grant_api_url": null, "remove_api_url": "/api/users/xia/accessibles/manager/cowork" }
Re-sends request for role
POST /api/users/{user}/accessibles/{role}/{organization}/
Re-sends the request e-mail that the user is requesting a role on the organization.
Responses
200
Effectively the username. The variable is named `slug` such that front-end code can be re-used between Organization and User records.
E-mail address for the user
Full name for the contact (effectively first name followed by last name)
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Date/time of creation (in ISO format)
Unique identifier shown in the URL bar
Short description of the role. Grammatical rules to pluralize the title might be used in User Interfaces.
Automatically grants the role without requiring a user to accept it.
Automatically adds the role when a user and profile share the same e-mail domain.
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Examples
POST /api/users/xia/accessibles/manager/cowork/{ "created_at": "2018-01-01T00:00:00Z", "role_description": { "created_at": "2018-01-01T00:00:00Z", "title": "Profile Manager", "slug": "manager", "is_global": true, "organization": { "slug": "cowork", "full_name": "ABC Corp.", "printable_name": "ABC Corp.", "created_at": "2018-01-01T00:00:00Z", "email": "support@localhost.localdomain" } }, "user": { "slug": "alice", "email": "alice@localhost.localdomain", "full_name": "Alice Doe", "created_at": "2018-01-01T00:00:00Z" }, "request_key": "1", "grant_key": null }
Deletes a role by type
DELETE /api/users/{user}/accessibles/{role}/{organization}/
Dettach a user from one or all roles with regards to an organization, typically resulting in revoking permissions from this user to manage part of an organization profile.
Responses
204
Examples
DELETE /api/users/xia/accessibles/manager/cowork/Creates a new profile owned by user
POST /api/users/{user}/profiles/
This end-point creates a new profile whose manager is user and returns an error if the profile already exists.
If you want to request access to an already existing profile, see the accessibles end-point.
Request body
Unique identifier shown in the URL bar
Full name
Timezone to use when reporting metrics
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Extra meta data (can be stringify JSON)
One of 'organization', 'personal' or 'user'
Responses
200
Unique identifier shown in the URL bar
Full name
Timezone to use when reporting metrics
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Extra meta data (can be stringify JSON)
One of 'organization', 'personal' or 'user'
Examples
POST /api/users/xia/profiles/responds{ "slug": "myproject", "full_name": "My Project" }
{ "slug": "myproject", "full_name": "My Project" }
Subscriptions
This section contains APIs to manage subscription plans and subscribers to those plans.
- Lists active plans
- Lists a provider plans
- Creates a subscription plan
- Retrieves a subscription plan
- Updates a subscription plan
- Deletes a subscription plan
- Lists subscriptions to a plan
- Subscribes to a plan through the provider
- Retrieves a subscription through the provider
- Updates a subscription through the provider
- Unsubscribes through the provider
- Lists subscribers for a provider
- Lists subscriptions
- Retrieves a subscription
- Unsubscribes at a future date
- Unsubscribes
Lists active plans
GET /api/pricing/
Returns a PAGE_SIZE list of plans.
Query parameters
A page number within the paginated result set.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
Examples
GET /api/pricing/{ "count": 1, "next": null, "previous": null, "results": [ { "slug": "managed", "title": "Managed", "description": "Ideal for growing organizations", "is_active": true, "setup_amount": 0, "period_amount": 2900, "period_length": 1, "period_type": "monthly", "unit": "usd", "is_not_priced": false, "renewal_type": "auto-renew", "created_at": "2019-01-01T00:00:00Z", "organization": "cowork", "extra": null, "skip_optin_on_grant": false, "optin_on_request": false } ] }
Lists a provider plans
GET /api/profile/{organization}/plans/
Returns a PAGE_SIZE list of plans whose provider is {organization}.
Query parameters
A page number within the paginated result set.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
Examples
GET /api/profile/cowork/plans{ "count": 1, "next": null, "previous": null, "results": [ { "slug": "managed", "title": "Managed", "description": "Ideal for growing organizations", "is_active": true, "setup_amount": 0, "period_amount": 2900, "period_length": 1, "period_type": "monthly", "unit": "usd", "is_not_priced": false, "renewal_type": "auto-renew", "created_at": "2019-01-01T00:00:00Z", "organization": "cowork", "extra": null, "skip_optin_on_grant": false, "optin_on_request": false } ] }
Creates a subscription plan
POST /api/profile/{organization}/plans/
Creates a subscription plan for provider {organization}.
Request body
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Responses
200
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
Examples
POST /api/profile/cowork/plansresponds{ "title": "Open Space", "description": "A desk in our coworking space", "is_active": false, "period_amount": 12000, "interval": "monthly" }
{ "title": "Open Space", "description": "A desk in our coworking space", "is_active": false, "period_amount": 12000, "interval": "monthly" }
Retrieves a subscription plan
GET /api/profile/{organization}/plans/{plan}/
Returns the {plan} for provider {organization}
The is_active boolean is used to activate a plan, enabling users to subscribe to it, or deactivate a plan, disabling users from subscribing to it.
Responses
200
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
Examples
GET /api/profile/cowork/plans/open-space{ "title": "Open Space", "description": "A desk in our coworking space", "is_active": false, "period_amount": 12000, "interval": "monthly" }
Updates a subscription plan
PUT /api/profile/{organization}/plans/{plan}/
Updates fields for {plan}. If the period_amount is modified, all subscriptions to this plan will be charged the period_amount on renewal.
The is_active boolean is used to activate a plan, enabling users to subscribe to it, or deactivate a plan, disabling users from subscribing to it.
Request body
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Responses
200
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
Examples
PUT /api/profile/cowork/plans/open-spaceresponds{ "title": "Open Space" }
{ "title": "Open Space", "description": "A desk in our coworking space", "is_active": false, "period_amount": 12000, "interval": "monthly" }
Deletes a subscription plan
DELETE /api/profile/{organization}/plans/{plan}/
A plan can only be deleted when there are no subscriptions to it. Even if all subscriptions to a plan have expired, the plan cannot be deleted. It should be de-activated instead such that no customers can subscribes to it.
Responses
204
Examples
DELETE /api/profile/cowork/plans/open-spaceLists subscriptions to a plan
GET /api/profile/{organization}/plans/{plan}/subscriptions/
Returns a PAGE_SIZE records of subscriptions to {plan} provided by {organization}.
Query parameters
A page number within the paginated result set.
Which field to use when ordering the results.
A search term.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
The subscription is set to auto-renew at the end of the period
True if the request user is able to update the subscription. Typically a manager for the plan provider.
Extra meta data (can be stringify JSON)
Examples
GET /api/profile/cowork/plans/premium/subscriptions/{ "count": 1, "next": null, "previous": null, "results": [ { "slug": "xia", "full_name": "Xia Lee", "created_at": "2016-01-14T23:16:55Z", "ends_at": "2017-01-14T23:16:55Z" } ] }
Subscribes to a plan through the provider
POST /api/profile/{organization}/plans/{plan}/subscriptions/
Subscribes a customer to the {plan} provided by {organization}.
Request body
Unique identifier shown in the URL bar
Full name
Timezone to use when reporting metrics
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Extra meta data (can be stringify JSON)
One of 'organization', 'personal' or 'user'
Responses
200
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
The subscription is set to auto-renew at the end of the period
True if the request user is able to update the subscription. Typically a manager for the plan provider.
Extra meta data (can be stringify JSON)
Examples
POST /api/profile/cowork/plans/premium/subscriptions/responds{ "organization": { "slug": "xia" } }
{ "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": "monthly", "app_url": "http://localhost:8020/app" }, "auto_renew": true }
Retrieves a subscription through the provider
GET /api/profile/{organization}/plans/{plan}/subscriptions/{subscriber}/
Returns the subscription of {subscriber} to {plan} from provider {organization}.
Responses
200
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
The subscription is set to auto-renew at the end of the period
True if the request user is able to update the subscription. Typically a manager for the plan provider.
Extra meta data (can be stringify JSON)
Examples
GET /api/profile/cowork/plans/open-space/subscriptions/xia/{ "created_at": "2019-01-01T00:00:00Z", "ends_at": "2020-01-01T00:00:00Z", "description": null, "organization": { "slug": "xia", "created_at": "2019-01-01T00:00:00Z", "full_name": "Xia Lee", "email": "xia@localhost.localdomain", "phone": "555-555-5555", "street_address": "350 Bay St.", "locality": "San Francisco", "region": "CA", "postal_code": "94133", "country": "US", "default_timezone": "UTC", "printable_name": "Xia Lee", "is_provider": false, "is_bulk_buyer": false, "type": "personal", "credentials": true, "extra": null }, "plan": { "slug": "open-space", "title": "Open Space", "description": "open space desk", "is_active": true, "setup_amount": 0, "period_amount": 17999, "period_length": 1, "interval": "monthly", "unit": "cad", "organization": "cowork", "renewal_type": "auto-renew", "is_not_priced": false, "created_at": "2019-01-01T00:00:00Z", "skip_optin_on_grant": false, "optin_on_request": false, "extra": null }, "auto_renew": true, "editable": true, "extra": null, "grant_key": null, "request_key": null }
Updates a subscription through the provider
PUT /api/profile/{organization}/plans/{plan}/subscriptions/{subscriber}/
Updates the subscription of {subscriber} to {plan} from provider {organization}.
Request body
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
The subscription is set to auto-renew at the end of the period
Extra meta data (can be stringify JSON)
Responses
200
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
The subscription is set to auto-renew at the end of the period
True if the request user is able to update the subscription. Typically a manager for the plan provider.
Extra meta data (can be stringify JSON)
Examples
PUT /api/profile/cowork/plans/open-space/subscriptions/xia/responds{ "ends_at": "2020-01-01T00:00:00Z", "description": "extended after call with customer" }
{ "created_at": "2019-01-01T00:00:00Z", "ends_at": "2020-01-01T00:00:00Z", "description": null, "organization": { "slug": "xia", "created_at": "2019-01-01T00:00:00Z", "full_name": "Xia Lee", "email": "xia@localhost.localdomain", "phone": "555-555-5555", "street_address": "350 Bay St.", "locality": "San Francisco", "region": "CA", "postal_code": "94133", "country": "US", "default_timezone": "UTC", "printable_name": "Xia Lee", "is_provider": false, "is_bulk_buyer": false, "type": "personal", "credentials": true, "extra": null }, "plan": { "slug": "open-space", "title": "Open Space", "description": "open space desk", "is_active": true, "setup_amount": 0, "period_amount": 17999, "period_length": 1, "interval": "monthly", "unit": "cad", "organization": "cowork", "renewal_type": "auto-renew", "is_not_priced": false, "created_at": "2019-01-01T00:00:00Z", "skip_optin_on_grant": false, "optin_on_request": false, "extra": null }, "auto_renew": true, "editable": true, "extra": null, "grant_key": null, "request_key": null }
Unsubscribes through the provider
DELETE /api/profile/{organization}/plans/{plan}/subscriptions/{subscriber}/
Unsubscribes {subscriber} from {plan} provided by {organization}.
Responses
204
Examples
DELETE /api/profile/cowork/plans/open-space/subscriptions/xia/Lists subscribers for a provider
GET /api/profile/{organization}/subscribers/
Returns a PAGE_SIZE list of subscriber profiles which have or had a subscription to a plan provided by {organization}.
Query parameters
A page number within the paginated result set.
A search term.
Which field to use when ordering the results.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Examples
GET /api/profile/cowork/subscribers/?o=created_at&ot=desc{ "count": 1, "next": null, "previous": null, "results": [ { "slug": "xia", "full_name": "Xia Lee", "email": "xia@localhost.localdomain", "created_at": "2016-01-14T23:16:55Z", "ends_at": "2017-01-14T23:16:55Z" } ] }
Lists subscriptions
GET /api/profile/{organization}/subscriptions/
Returns a PAGE_SIZE list of subscriptions past and present for subscriber {organization}.
The queryset can be further refined to match a search filter (q) and sorted on specific fields (o).
Query parameters
A page number within the paginated result set.
Which field to use when ordering the results.
A search term.
Responses
200
Total number of items in the dataset
URL to previous page of results
URL to next page of results
items in current page
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
The subscription is set to auto-renew at the end of the period
True if the request user is able to update the subscription. Typically a manager for the plan provider.
Extra meta data (can be stringify JSON)
Examples
GET /api/profile/cowork/subscriptions/?o=created_at&ot=desc{ "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, "period_type": "monthly", "app_url": "http://localhost:8020/app" }, "auto_renew": true } ] }
Retrieves a subscription
GET /api/profile/{organization}/subscriptions/{subscribed_plan}/
Returns the subscription of {organization} to {subscribed_plan}.
Responses
200
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
The subscription is set to auto-renew at the end of the period
True if the request user is able to update the subscription. Typically a manager for the plan provider.
Extra meta data (can be stringify JSON)
Examples
GET /api/profile/xia/subscriptions/open-space/{ "created_at": "2019-01-01T00:00:00Z", "ends_at": "2020-01-01T00:00:00Z", "description": null, "organization": { "slug": "xia", "created_at": "2019-01-01T00:00:00Z", "full_name": "Xia Lee", "email": "xia@localhost.localdomain", "phone": "555-555-5555", "street_address": "350 Bay St.", "locality": "San Francisco", "region": "CA", "postal_code": "94133", "country": "US", "default_timezone": "UTC", "printable_name": "Xia Lee", "is_provider": false, "is_bulk_buyer": false, "type": "personal", "credentials": true, "extra": null }, "plan": { "slug": "open-space", "title": "Open Space", "description": "open space desk", "is_active": true, "setup_amount": 0, "period_amount": 17999, "period_length": 1, "interval": "monthly", "unit": "cad", "organization": "cowork", "renewal_type": "auto-renew", "is_not_priced": false, "created_at": "2019-01-01T00:00:00Z", "skip_optin_on_grant": false, "optin_on_request": false, "extra": null }, "auto_renew": true, "editable": true, "extra": null, "grant_key": null, "request_key": null }
Unsubscribes at a future date
PUT /api/profile/{organization}/subscriptions/{subscribed_plan}/
Unsubscribes {organization} from {subscribed_plan} at a future date.
Request body
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
The subscription is set to auto-renew at the end of the period
Extra meta data (can be stringify JSON)
Responses
200
Date/time of creation (in ISO format)
Date/time when the subscription period currently ends (in ISO format)
Free-form text description for the subscription
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Date/time of creation (in ISO format)
E-mail address
Phone number
Street address
City/Town
State/Province/County
Zip/Postal code
Country
Timezone to use when reporting metrics
The organization can fulfill the provider side of a subscription.
Enable GroupBuy
Extra meta data (can be stringify JSON)
Title for the plan
Free-form text description for the plan
True when customers can subscribe to the plan
One-time amount to pay when the subscription starts
Amount billed every period
Natural period for the subscription
Discounts when periods are paid in advance.
Type of discount (periods, percentage or currency unit)
Amount of the discount
Contract length associated with the period
Provider of the plan
Unique identifier shown in the URL bar
Full name
Profile picture
One of 'organization', 'personal' or 'user'
Extra meta data (can be stringify JSON)
Natural period length of a subscription to the plan (monthly, yearly, etc.)
Natural period for the subscription
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)
True when a provider must manually accept a subscription to the plan initiated by a subscriber. (defaults to False)
Discounted amount for the first period
The subscription is set to auto-renew at the end of the period
True if the request user is able to update the subscription. Typically a manager for the plan provider.
Extra meta data (can be stringify JSON)
Examples
PUT /api/profile/xia/subscriptions/open-space/responds{ "ends_at": "2020-01-01T00:00:00Z" }
{ "created_at": "2019-01-01T00:00:00Z", "ends_at": "2020-01-01T00:00:00Z", "description": null, "organization": { "slug": "xia", "created_at": "2019-01-01T00:00:00Z", "full_name": "Xia Lee", "email": "xia@localhost.localdomain", "phone": "555-555-5555", "street_address": "350 Bay St.", "locality": "San Francisco", "region": "CA", "postal_code": "94133", "country": "US", "default_timezone": "UTC", "printable_name": "Xia Lee", "is_provider": false, "is_bulk_buyer": false, "type": "personal", "credentials": true, "extra": null }, "plan": { "slug": "open-space", "title": "Open Space", "description": "open space desk", "is_active": true, "setup_amount": 0, "period_amount": 17999, "period_length": 1, "interval": "monthly", "unit": "cad", "organization": "cowork", "renewal_type": "auto-renew", "is_not_priced": false, "created_at": "2019-01-01T00:00:00Z", "skip_optin_on_grant": false, "optin_on_request": false, "extra": null }, "auto_renew": true, "editable": true, "extra": null, "grant_key": null, "request_key": null }
Unsubscribes
DELETE /api/profile/{organization}/subscriptions/{subscribed_plan}/
Unsubscribes {organization} from {subscribed_plan}.
Responses
204
Examples
DELETE /api/profile/xia/subscriptions/open-space/Themes
This section contains APIs to upload new templates for all pages, from login to checkout, or reset to the default theme.
Sends a test notification e-mail
POST /api/notifications/{template}/
Responses
200
Describes the reason for the error in plain text
Examples
POST /api/notifications/contact_requested_notice/{ "detail": "Test email sent to xia@example.com" }
Uploads a theme package
POST /api/themes/
Uploads a theme package with templates that will override the default ones. See references and tutorials on creating themes for details on the theme package structure and customizing the default templates.
Responses
200
Examples
None NoneRemoves custom theme
DELETE /api/themes/
Removes the custom theme templates and assets.
Pages will be using the default theme after a reset.
Responses
204
Examples
DELETE /api/themes