Powered by © 2024 DjaoDjin. All rights reserved. Legal.

Profiles, Billing and Access Control API Reference

Once you have registered an account on djaodjin.com and created a site, the following Application Programmable Interface (API) will be available on your site to provide profiles, billing and service access control - i.e. the administrative features required to run Software, as-a-Service, on the Internet.

Most API end points require authentication. Three methods of authentication are supported:

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

Browse the API endpoints alphabetically, or by ...

OpenAPI Schema

workflows

roles

models

By workflows

Auth & credentials

This section contains APIs related to authenticating users such as registration, login, updating a user password, etc.

Billing

This section contains APIs to manage the checkout, billing and accounting workflows, including shopping carts, coupons, charges and balance statements.

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.

Profile

This section contains APIs to manage the identity, such as name or email address, of users and organizations registered to the site.

Roles & rules

This section contains APIs to manage roles and access rules.

Subscriptions

This section contains APIs to manage subscriptions.

Themes

This section contains APIs to upload new templates for all pages, from login to checkout, or reset to the default theme.

By roles

Visitors

This section contains APIs related to unauthenticated users.

Users

This section contains APIs related to authenticated users.

Subscribers

This section contains APIs related to subscribers.

Providers

This section contains APIs related to providers.

Broker

This section contains APIs related to the broker.

By datamodels

Users

This section contains APIs related to users.

A user represents a individual (or bot) with login credentials. Technically a user, after authentication, holds a session token that is passed to the server on each HTTP request. Users call API end points, and hold permissions to do so, through roles on organization and personal profiles.

Users are required to sign the terms of use of a site.

Profiles

This section contains APIs related to billing profiles.

A billing, sometimes called an organization profile, has no login credentials. It typically represents a legal entity that can be charged for service. Users can operate on billing profiles (ex: subscribe the organization to a plan) though roles they hold on an billing profile.

Depending on its relationship within a workflow, a billing profile is referred as either a subscriber, a provider or the broker.

Roles

This section contains APIs related to roles.

A role is a relationship between a user and a billing or personal profile - shorten to profile later on - that grant the user certain permissions to act on the profile. Permissions are not directly tied to the Role object, but rather to an abstract representation of the role called a RoleDescription.

It is not uncommon in casual conversation to use role to mean RoleDescription when talking about permissions as the end result is about the same. None-the-less, the workflows involved to grant a role to a user, such as opt-ins and double opt-ins can only be set on the RoleDescription, affecting all role objects using that RoleDescription.

Plans

This section contains APIs related to subscription plans.

Billing profiles subscribe to one or many provider plans, hence becoming subscribers of that provider.

Subscriptions

This section contains APIs related to subscriptions.

The subscription model defines the relationship between a subscriber and a provider through a plan.

Carts

This section contains APIs related to cart items.

In order to pay for a subscription, a billing profile will add plans to a cart, then checkout that cart, entering a payment method in the process.

Charges

This section contains APIs related to charges.

Payments for subscriptions results in charges on the payment processor.

Coupons

This section contains APIs related to ad-hoc discounts.

Transactions

This section contains APIs related to transactions.

Transactions are recorded in an append-only double-entry book keeping ledger.

Site

This section contains APIs related to site theme and operations.

Alphabetical

API version

endpoint 
GET /api

Retrieves version of the API

Responses
version
string

Version of the API being used

 

Examples 
curl https://livedemo.djaoapp.com/api
responds 
{
  "version": "2024-03-15.3"
}

Searches profile and user accounts

endpoint 
GET /api/accounts

Returns a list of 5 candidate profiles or user accounts based of a search criteria (q).

The API is designed to be used in typeahead input fields. As such it only returns results when the number of candidates is less than 5.

If you need to list all profiles, please see Lists billing profiles

The queryset can be further refined by a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

The API is typically used in pages for the support team to quickly locate an account. For example, it is used within the HTML provider dashboard page as present in the default theme.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, full_name, email, phone, street_address, locality, region, postal_code, country, username, first_name, last_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

Total number of items in the results

results
array

Items in the queryset

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/accounts?q=xi
responds 
{
  "count": 1,
  "results": [
    {
      "slug": "xia",
      "printable_name": "Xia Lee",
      "picture": null,
      "type": "personal",
      "credentials": true
    }
  ]
}

Searches profiles

endpoint 
GET /api/accounts/profiles

Returns a list of 5 candidate profiles based of a search criteria (q).

The API is designed to be used in typeahead input fields. As such it only returns results when the number of candidates is less than 5.

If you need to list all profiles, please see Lists billing profiles

The queryset can be further refined by a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

The API is typically used within an HTML connected profiles page as present in the default theme.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, full_name, email, phone, street_address, locality, region, postal_code, country, username, first_name, last_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

Total number of items in the results

results
array

Items in the queryset

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/accounts/profiles?q=xi
responds 
{
  "count": 1,
  "results": [
    {
      "slug": "xia",
      "printable_name": "Xia Lee",
      "picture": null,
      "type": "personal",
      "credentials": true
    }
  ]
}

Creates a shadow profile

endpoint 
POST /api/accounts/profiles

Creates a profile that is not associated to any user.

Request body
slug
string

Unique identifier shown in the URL bar

picture
string

URL location of the profile picture

type
string

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

full_name
string required

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The profile can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy

extra
string

Extra meta data (can be stringify JSON)

Responses
slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

full_name
string

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The profile can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy

extra
string

Extra meta data (can be stringify JSON)

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"email": "xia@locahost.localdomain", "full_name": "Xia Lee", "type": "personal"}' https://livedemo.djaoapp.com/api/accounts/profiles
responds 
{
  "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 profile summary

endpoint 
GET /api/accounts/profiles/{profile}

While the profiles typeahead API returns a list of profiles summary based on search criteria, if you already know the unique slug of a profile, you can get the same summary by using this API.

Responses
slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/accounts/profiles/xia
responds 
{
  "slug": "xia",
  "printable_name": "Xia Lee",
  "picture": null,
  "type": "organization",
  "credentials": true
}

Searches users

endpoint 
GET /api/accounts/users

Returns a list of 5 candidate users based of a search criteria (q).

The API is designed to be used in typeahead input fields. As such it only returns results when the number of candidates is less than 5.

If you need to list all users, please see Lists user accounts

The queryset can be further refined by a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

The API is typically used within an HTML profile role page as present in the default theme.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: username, first_name, last_name, email, slug, full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

Total number of items in the results

results
array

Items in the queryset

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/accounts/users?q=ali
responds 
{
  "count": 1,
  "results": [
    {
      "slug": "alice",
      "username": "alice",
      "printable_name": "Alice Cooper",
      "picture": null
    }
  ]
}

List legal agreements (broker)

endpoint 
GET /api/agreements

List all legal agreements a user might be requested to sign. This is a convenience API for authenticated broker profile managers. For listing legal agreements publicly, see GET /api/legal.

Query parameters
o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, title. searches all fields when unspecified.

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier shown in the URL bar

title
string

Short description of the agreement

updated_at
string

Date/time the agreement was last updated (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/agreements
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "terms-of-use",
      "title": "Terms of Use",
      "updated_at": "2023-08-16T00:00:00Z"
    }
  ]
}

Creates a legal agreement

endpoint 
POST /api/agreements

Creates a new legal agreement a user might be requested to sign.

All users visiting an URL decorated with an "Agreed to {agreement}" access control rule will be prompted to sign the agreement.

Request body
title
string required

Short description of the agreement

updated_at
string

Date/time of update (in ISO 8601 format)

Responses
slug
string

Unique identifier shown in the URL bar

title
string

Short description of the agreement

updated_at
string

Date/time the agreement was last updated (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Terms of Use"}' https://livedemo.djaoapp.com/api/agreements
responds 
{
  "slug": "terms-of-use",
  "title": "Terms of Use",
  "updated_at": "2023-08-16T00:00:00Z"
}

Retrieves a legal agreement (broker)

endpoint 
GET /api/agreements/{document}

Retrieves the text of legal agreement a user might be requested to sign. This is a convenience API for authenticated broker profile managers. For retrieving the text of a legal agreement publicly, see GET /api/legal/{agreement}.

Responses
slug
string

Unique identifier shown in the URL bar

title
string

Short description of the agreement

updated_at
string

Date/time the agreement was last updated (in ISO format)

text
string

Text of the agreement

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/agreements/terms-of-use
responds 
{
  "slug": "terms-of-use",
  "title": "Terms of Use",
  "updated_at": "2023-08-16T00:00:00Z",
  "text": "..."
}

Updates a legal agreement

endpoint 
PUT /api/agreements/{document}

Updates the latest modification date of a legal agreement a user might be requested to sign.

All users visiting an URL decorated with an "Agreed to {agreement}" access control rule will be prompted to sign the agreement again if the last time they signed is older that the updated_at date set here.

Request body
title
string required

Short description of the agreement

updated_at
string required

Date/time of update (in ISO 8601 format)

Responses
slug
string

Unique identifier shown in the URL bar

title
string

Short description of the agreement

updated_at
string

Date/time the agreement was last updated (in ISO format)

text
string

Text of the agreement

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Terms of Use", "updated_at": "2023-08-16T00:00:00Z"}' https://livedemo.djaoapp.com/api/agreements/terms-of-use
responds 
{
  "slug": "terms-of-use",
  "title": "Terms of Use",
  "updated_at": "2023-08-16T00:00:00Z",
  "text": "..."
}

Deletes a legal agreement

endpoint 
DELETE /api/agreements/{document}

Deletes a legal agreement a user might be requested to sign.

This will remove the agreement as well as all user signatures of it.

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/agreements/terms-of-use

Authenticates a user

endpoint 
POST /api/auth

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

The API is typically used within an HTML login page as present in the default theme.

Query parameters
cookie
boolean

True when a cookie session should additionally be created

Request body
password
string

Password of the user making the HTTP request

otp_code
integer

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

email_code
integer

Email verification code.

phone_code
integer

Phone verification code.

username
string required

Username, e-mail address or phone number to identify the account

Responses
token
string

Token used to authenticate user on every HTTP request

detail
string

Describes the reason for the error in plain text

 

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"username": "donny", "password": "yoyo"}' https://livedemo.djaoapp.com/api/auth
responds 
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"
}

Retrieves contact from an activation key

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

Retrieves information about a contact or user associated to the activation key.

This API is typically used to pre-populate a registration form when a user was invited to the site by another user.

The response is usually presented in an HTML activate page as present in the default theme.

Responses
slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

 

Examples 
curl https://livedemo.djaoapp.com/api/auth/activate/16793aa72a4c7ae94b50b20c2eca52df5b0fe2c6
responds 
{
  "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

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

Query parameters
cookie
boolean

True when a cookie session should additionally be created

Request body
slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

email_code
integer

Email verification code

phone_code
integer

Phone verification code

new_password
string required

Password with which a user can authenticate with the service

Responses
token
string

Token used to authenticate user on every HTTP request

detail
string

Describes the reason for the error in plain text

 

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"username": "joe1", "email": "joe1@locahost.localdomain", "new_password": "yoyo", "full_name": "Joe Card1"}' https://livedemo.djaoapp.com/api/auth/activate/16793aa72a4c7ae94b50b20c2eca52df5b0fe2c6
responds 
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6    ImpvZTEiLCJlbWFpbCI6ImpvZSsxQGRqYW9kamluLmNvbSIsImZ1bGxfbmFtZ    SI6IkpvZSAgQ2FyZDEiLCJleHAiOjE1Mjk2NTUyMjR9.GFxjU5AvcCQbVylF1P    JwcBUUMECj8AKxsHtRHUSypco"
}

Logs a user out

endpoint 
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 
curl -H 'Authorization: Bearer JWT auth token' -X POST https://livedemo.djaoapp.com/api/auth/logout

Sends a verification link

endpoint 
POST /api/auth/recover

Sends a one time code to verify an e-mail or phone number.

The user is uniquely identified by her email address or phone number.

The API is typically used within an HTML recover credentials page as present in the default theme.

Request body
email
string required

Email or phone number to recover the account

Responses
email
string

Email or phone number to recover the account

 

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"email": "xia@localhost.localdomain"}' https://livedemo.djaoapp.com/api/auth/recover
responds 
{
  "email": "xia@localhost.localdomain"
}

Registers a user

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

The API is typically used within an HTML register page as present in the default theme.

Query parameters
cookie
boolean

True when a cookie session should additionally be created

Request body
slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string required

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

email_code
integer

Email verification code

phone_code
integer

Phone verification code

new_password
string

Password with which a user can authenticate with the service

organization_name
string

Organization name that owns the billing, registered with the user as profile manager

street_address
string

Street address for the billing profile

locality
string

City/Town for the billing profile

region
string

State/Province/County for the billing profile

postal_code
string

Zip/Postal Code for the billing profile

country
string

Country for the billing profile

type
string

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

terms-of-use
string

Terms Of Use

security
string

Security Policy

Responses
token
string

Token used to authenticate user on every HTTP request

detail
string

Describes the reason for the error in plain text

 

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"email": "joe+1@example.com", "full_name": "Joe Card1", "new_password": "yoyo", "username": "joe1"}' https://livedemo.djaoapp.com/api/auth/register
responds 
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImpvZTEiLCJlbWFpbCI6ImpvZSsxQGRqYW9kamluLmNvbSIsImZ1bGxfbmFtZSI6IkpvZSAgQ2FyZDEiLCJleHAiOjE1Mjk2NTUyMjR9.GFxjU5AvcCQbVylF1PJwcBUUMECj8AKxsHtRHUSypco"
}

Resets a user password

endpoint 
POST /api/auth/reset/{verification_key}

Resets a user password, hence triggering an activation workflow the next time a user attempts to login.

Responses

201
detail
string

Describes the reason for the error in plain text

 

Examples 
curl -X POST https://livedemo.djaoapp.com/api/auth/reset/16793aa72a4c7ae94b50b20c2eca52df5b0fe2c6
responds 
{}

Refreshes a JSON Web Token

endpoint 
POST /api/auth/tokens

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

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

Request body
token
string required

Token used to authenticate user on every HTTP request

Responses
token
string

Token used to authenticate user on every HTTP request

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"}' https://livedemo.djaoapp.com/api/auth/tokens
responds 
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5Njk1NjA1fQ.-uuZb8R68jWw1Tc9FJocOWe1KHFklRffXbH0Rg6d_0c"
}

Verifies a JSON Web Token

endpoint 
POST /api/auth/tokens/verify

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

Request body
token
string required

Token used to authenticate user on every HTTP request

Responses
token
string

Token used to authenticate user on every HTTP request

detail
string

Describes the reason for the error in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"}' https://livedemo.djaoapp.com/api/auth/tokens/verify
responds 
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"
}

Lists active cart items

endpoint 
GET /api/billing/cartitems

Returns a list of page_size cart items that haven't been checked out yet.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: user__username, user__first_name, user__last_name, user__email. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

user
object

User the cart belongs to

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

claim_code
string

Code used to assign the cart item to a user in group buy

plan
object

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/cartitems
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2023-10-11T21:20:06.444545-05:00",
      "user": {
        "username": "xia",
        "slug": "xia",
        "email": "xia@example.com",
        "full_name": "Xia Lee",
        "created_at": "2023-09-06T21:49:28.003319-05:00",
        "last_login": "2023-10-11T03:31:10.138177-05:00"
      },
      "plan": {
        "slug": "basic",
        "title": "Basic"
      },
      "option": 0,
      "use": null,
      "quantity": 1,
      "sync_on": null,
      "full_name": "Xia Lee",
      "email": "xia@example.com",
      "detail": null
    }
  ]
}

Creates a cart item

endpoint 
POST /api/billing/cartitems

This endpoint lets broker to add items into a user cart.

Request body
user
string required

The user for whom the cart item is being created

plan
string required

The plan to add into the request.user cart.

option
integer

Index in the list of discounts for advance payments

use
string

The use charge to add into the request.user cart.

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

Responses
created_at
string

Date/time of creation (in ISO format)

user
object

User the cart belongs to

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

claim_code
string

Code used to assign the cart item to a user in group buy

plan
object

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"user": "xia", "plan": "basic"}' https://livedemo.djaoapp.com/api/billing/cartitems
responds 
{
  "user": {
    "username": "xia",
    "slug": "xia",
    "email": "xia@example.com",
    "full_name": "Xia Lee",
    "created_at": "2023-09-06T21:49:28.003319-05:00",
    "last_login": "2023-10-11T03:31:10.138177-05:00"
  },
  "plan": {
    "slug": "basic",
    "title": "Basic"
  },
  "created_at": "2023-10-12T05:47:17.421103-05:00",
  "option": 3,
  "use": null,
  "quantity": 50,
  "sync_on": "",
  "full_name": "Xia Lee",
  "email": "xia@example.com",
  "detail": "Cart item created"
}

Lists a user active cart items

endpoint 
GET /api/billing/cartitems/user/{user}

Returns a list of page_size cart items that a specified user hasn't checked out yet.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: user__username, user__first_name, user__last_name, user__email. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

user
object

User the cart belongs to

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

claim_code
string

Code used to assign the cart item to a user in group buy

plan
object

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/cartitems/user/xia
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2023-10-11T23:49:59.485511-05:00",
      "user": {
        "username": "xia",
        "slug": "xia",
        "email": "xia@example.com",
        "full_name": "Xia Lee",
        "created_at": "2023-09-06T21:49:28.003319-05:00",
        "last_login": "2023-10-11T03:31:10.138177-05:00"
      },
      "plan": {
        "slug": "basic",
        "title": "Basic"
      },
      "option": 0,
      "use": null,
      "quantity": 2,
      "sync_on": null,
      "full_name": "",
      "email": null,
      "id": 137
    }
  ]
}

Retrieves a cart item

endpoint 
GET /api/billing/cartitems/{cartitem_id}

Returns a single cart item based on its primary key.

This API endpoint is intended for broker to analyze and modify active cart items as necessary when responding to support requests.

Responses
created_at
string

Date/time of creation (in ISO format)

user
object

User the cart belongs to

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

claim_code
string

Code used to assign the cart item to a user in group buy

plan
object

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/cartitems/{cartitem_id}
responds 
{
  "user": {
    "username": "xia",
    "slug": "xia",
    "email": "xia@example.com",
    "full_name": "Xia Lee",
    "created_at": "2023-09-06T21:49:28.003319-05:00",
    "last_login": "2023-10-11T03:31:10.138177-05:00"
  },
  "plan": {
    "slug": "basic",
    "title": "Basic"
  },
  "created_at": "2023-10-11T23:22:54.407880-05:00",
  "option": 3,
  "use": null,
  "quantity": 50,
  "sync_on": null,
  "full_name": "Xia Lee",
  "email": "xia@example.com"
}

Updates a cart item

endpoint 
PUT /api/billing/cartitems/{cartitem_id}

Updates a single cart item based on its primary key.

This API endpoint is intended for broker to analyze and modify active cart items as necessary when responding to support requests.

Request body
option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

Responses
created_at
string

Date/time of creation (in ISO format)

user
object

User the cart belongs to

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

claim_code
string

Code used to assign the cart item to a user in group buy

plan
object

Plan in the cart (if any)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"option": 2, "quantity": 25}' https://livedemo.djaoapp.com/api/billing/cartitems/{cartitem_id}
responds 
{
  "created_at": "2023-10-12T02:04:49.151044-05:00",
  "user": {
    "slug": "xia",
    "email": "xia@example.com",
    "full_name": "Xia Lee",
    "created_at": "2023-09-06T21:58:07.969908-05:00",
    "last_login": "2023-10-12T01:49:13.092566-05:00"
  },
  "plan": {
    "slug": "basic",
    "title": "Basic"
  },
  "option": 2,
  "use": null,
  "quantity": 25,
  "sync_on": "",
  "full_name": "",
  "email": "",
  "detail": "Cart item updated"
}

Deletes a cart item

endpoint 
DELETE /api/billing/cartitems/{cartitem_id}

Deletes a single cart item based on its primary key.

This API endpoint is intended for broker to analyze and modify active cart items as necessary when responding to support requests.

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/billing/cartitems/{cartitem_id}

Lists processor charges

endpoint 
GET /api/billing/charges

Returns a list of page_size charges that were created on the payment processor (ex: Stripe).

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: description, processor_key, customer__full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
balance_amount
integer

The sum of all record amounts (in unit)

balance_unit
integer

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

count
integer

Total number of items in the results

next
string

API end point to get the next pageof results matching the query

previous
string

API end point to get the previous pageof results matching the query

results
array

Items in the queryset

created_at
string

Date/time of creation (in ISO format)

amount
integer

Total amount in currency unit

unit
string

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

readable_amount
string

Amount and unit in a commonly accepted readable format

description
string

Description for the charge as appears on billing statements

last4
string

Last 4 digits of the credit card used

exp_date
string

Expiration date of the credit card used

processor_key
string

Unique identifier returned by the payment processor

state
string

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

detail
string

Feedback for the user in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/charges?start_at=2015-07-05T07:00:00.000Z\&o=date\&ot=desc
responds 
{
  "count": 1,
  "balance_amount": "112120",
  "balance_unit": "usd",
  "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"
    }
  ]
}

Lists ledger transactions

endpoint 
GET /api/billing/transactions

Returns a list of page_size transactions.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: description, dest_profile, dest_profile__full_name, orig_profile, orig_profile__full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
start_at
string

Start of the date range for which the balance was computed

ends_at
string

End of the date range for which the balance was computed

balance_amount
integer

balance of all transactions in cents (i.e. 100ths) of unit

balance_unit
integer

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

count
integer

Total number of items in the results

next
string

API end point to get the next pageof results matching the query

previous
string

API end point to get the previous pageof results matching the query

results
array

Items in the queryset

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

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

orig_account
string

Source account from which funds are withdrawn

orig_profile
object

Billing profile from which funds are withdrawn

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

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

dest_account
string

Target account to which funds are deposited

dest_profile
object

Billing profile to which funds are deposited

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/transactions?start_at=2015-07-05T07:00:00.000Z\&o=date\&ot=desc
responds 
{
  "start_at": "2015-07-05T07:00:00.000Z",
  "ends_at": "2017-03-30T18:10:12.962859Z",
  "balance_amount": 11000,
  "balance_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_profile": {
        "slug": "xia",
        "printable_name": "Xia",
        "picture": null,
        "type": "personal",
        "credentials": true
      },
      "orig_amount": 112120,
      "orig_unit": "usd",
      "dest_account": "Funds",
      "dest_profile": {
        "slug": "stripe",
        "printable_name": "Stripe",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "dest_amount": 112120,
      "dest_unit": "usd"
    }
  ]
}

Retrieves a customer balance

endpoint 
GET /api/billing/{profile}/balance

Get the statement balance due for a billing profile.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: description, dest_profile, dest_profile__full_name, orig_profile, orig_profile__full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
start_at
string

Start of the date range for which the balance was computed

ends_at
string

End of the date range for which the balance was computed

balance_amount
integer

balance of all transactions in cents (i.e. 100ths) of unit

balance_unit
integer

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

count
integer

Total number of items in the results

next
string

API end point to get the next pageof results matching the query

previous
string

API end point to get the previous pageof results matching the query

results
array

Items in the queryset

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

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

orig_account
string

Source account from which funds are withdrawn

orig_profile
object

Billing profile from which funds are withdrawn

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

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

dest_account
string

Target account to which funds are deposited

dest_profile
object

Billing profile to which funds are deposited

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/xia/balance
responds 
{
  "balance_amount": "1200",
  "balance_unit": "usd",
  "start_at": "2023-01-01T00:00:00Z",
  "ends_at": "2023-06-01T23:42:13.863739Z",
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "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_profile": {
        "slug": "cowork",
        "printable_name": "Coworking Space",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "orig_amount": 2000,
      "orig_unit": "usd",
      "dest_account": "Payable",
      "dest_profile": {
        "slug": "xia",
        "printable_name": "Xia Lee",
        "picture": null,
        "type": "personal",
        "credentials": true
      },
      "dest_amount": 2000,
      "dest_unit": "usd"
    }
  ]
}

Adds to the order balance

endpoint 
POST /api/billing/{profile}/balance

This API endpoint can be used to add use charges to a subscriber invoice while charging the subscriber at a later date.

Request body
plan
string required

The plan to add into the request.user cart.

option
integer

Index in the list of discounts for advance payments

use
string

The use charge to add into the request.user cart.

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

Responses
created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

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

orig_account
string

Source account from which funds are withdrawn

orig_profile
object

Billing profile from which funds are withdrawn

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

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

dest_account
string

Target account to which funds are deposited

dest_profile
object

Billing profile to which funds are deposited

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"plan": "basic", "use": "requests"}' https://livedemo.djaoapp.com/api/billing/xia/balance
responds 
{
  "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_profile": {
    "slug": "cowork",
    "printable_name": "Coworking Space",
    "picture": null,
    "type": "organization",
    "credentials": false
  },
  "orig_amount": 2000,
  "orig_unit": "usd",
  "dest_account": "Payable",
  "dest_profile": {
    "slug": "xia",
    "printable_name": "Xia Lee",
    "picture": null,
    "type": "personal",
    "credentials": true
  },
  "dest_amount": 2000,
  "dest_unit": "usd"
}

Cancels a balance due

endpoint 
DELETE /api/billing/{profile}/balance

Cancel the balance due by profile. This will create a transaction for this balance cancellation. A provider 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).

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/billing/xia/balance

Retrieves a payout account

endpoint 
GET /api/billing/{profile}/bank

Pass through that calls the payment 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
bank_name
string

Name of the deposit account

last4
string

Last 4 characters of the deposit account identifier

balance_amount
integer

Amount available to transfer to the provider deposit account

balance_unit
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/cowork/bank
responds 
{
  "bank_name": "Stripe Test Bank",
  "last4": "***-htrTZ",
  "balance_amount": 0,
  "balance_unit": "usd"
}

Retrieves a payment method

endpoint 
GET /api/billing/{profile}/card

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

When you wish to update the payment method on file through a Strong Customer Authentication (SCA) workflow, the payment processor will require a token generated by the server. That token can be retrieved in the processor.STRIPE_INTENT_SECRET field when the API is called with ?update=1 query parameters.

The API is typically used within an HTML update payment method page as present in the default theme.

Query parameters
update
boolean

Adds context to update a payment method on file.

Responses
processor
object

Keys to authenticate the client with the payment processor

STRIPE_PUB_KEY
string

Processor public key (Stripe)

STRIPE_INTENT_SECRET
string

PaymentIntent or SetupIntent secret for SCA (Stripe)

STRIPE_ACCOUNT
string

Connected account identifier (Stripe)

last4
string

Last 4 digits of the credit card on file

exp_date
string

Expiration date of the credit card on file

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/xia/card
responds 
{
  "last4": "1234",
  "exp_date": "12/2019"
}

Updates a payment method

endpoint 
PUT /api/billing/{profile}/card

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

The API is typically used within an HTML update payment method page as present in the default theme.

Request body
token
string required

Processor token to retrieve the payment method

full_name
string

Full name

email
string

E-mail address for the account

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

Responses
processor
object

Keys to authenticate the client with the payment processor

STRIPE_PUB_KEY
string

Processor public key (Stripe)

STRIPE_INTENT_SECRET
string

PaymentIntent or SetupIntent secret for SCA (Stripe)

STRIPE_ACCOUNT
string

Connected account identifier (Stripe)

last4
string

Last 4 digits of the credit card on file

exp_date
string

Expiration date of the credit card on file

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"token": "xyz"}' https://livedemo.djaoapp.com/api/billing/xia/card
responds 
{
  "last4": "1234",
  "exp_date": "12/2019"
}

Deletes a payment method

endpoint 
DELETE /api/billing/{profile}/card

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

The API is typically used within an HTML update payment method page as present in the default theme.

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/billing/xia/card

Retrieves a processor charge

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

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

Responses
created_at
string

Date/time of creation (in ISO format)

amount
integer

Total amount in currency unit

unit
string

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

readable_amount
string

Amount and unit in a commonly accepted readable format

description
string

Description for the charge as appears on billing statements

last4
string

Last 4 digits of the credit card used

exp_date
string

Expiration date of the credit card used

processor_key
string

Unique identifier returned by the payment processor

state
string

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

detail
string

Feedback for the user in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/xia/charges/ch_XAb124EF
responds 
{
  "created_at": "2016-01-01T00:00:01Z",
  "readable_amount": "$1121.20",
  "amount": 112120,
  "unit": "usd",
  "description": "Charge for subscription to cowork open-space",
  "last4": "1234",
  "exp_date": "2016-06-01",
  "processor_key": "ch_XAb124EF",
  "state": "DONE"
}

Re-sends a charge receipt

endpoint 
POST /api/billing/{profile}/charges/{charge}/email

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

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

Responses
charge_id
string

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

email
string

E-mail address to which the receipt was sent.

detail
string

Feedback for the user in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST https://livedemo.djaoapp.com/api/billing/xia/charges/ch_XAb124EF/email
responds 
{
  "charge_id": "ch_XAb124EF",
  "email": "joe@localhost.localdomain"
}

Refunds a processor charge

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

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

Request body
lines
array required

Line items in a charge to be refunded

num
integer required

Line item index counting from zero.

refunded_amount
integer

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

Responses
created_at
string

Date/time of creation (in ISO format)

amount
integer

Total amount in currency unit

unit
string

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

readable_amount
string

Amount and unit in a commonly accepted readable format

description
string

Description for the charge as appears on billing statements

last4
string

Last 4 digits of the credit card used

exp_date
string

Expiration date of the credit card used

processor_key
string

Unique identifier returned by the payment processor

state
string

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

detail
string

Feedback for the user in plain text

detail
string

Describes the reason for the error in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"lines": [{"num": 0, "refunded_amount": 4000}, {"num": 1, "refunded_amount": 82120}]}' https://livedemo.djaoapp.com/api/billing/xia/charges/ch_XAb124EF/refund
responds 
{
  "created_at": "2016-01-01T00:00:05Z",
  "readable_amount": "$1121.20",
  "amount": 112120,
  "unit": "usd",
  "description": "Charge for subscription to cowork open-space",
  "last4": "1234",
  "exp_date": "2016-06-01",
  "processor_key": "ch_XAb124EF",
  "state": "DONE"
}

Retrieves a cart for checkout

endpoint 
GET /api/billing/{profile}/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.

The API is typically used within an HTML checkout page as present in the default theme.

Responses
processor
object

Keys to authenticate the client with the payment processor

STRIPE_PUB_KEY
string

Processor public key (Stripe)

STRIPE_INTENT_SECRET
string

PaymentIntent or SetupIntent secret for SCA (Stripe)

STRIPE_ACCOUNT
string

Connected account identifier (Stripe)

results
array

Items that will be charged

subscription
object

Subscription lines and options refer to.

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

lines
array

Line items to charge on checkout.

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

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

orig_account
string

Source account from which funds are withdrawn

orig_profile
object

Billing profile from which funds are withdrawn

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

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

dest_account
string

Target account to which funds are deposited

dest_profile
object

Billing profile to which funds are deposited

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

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

options
array

Options to replace line items.

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

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

orig_account
string

Source account from which funds are withdrawn

orig_profile
object

Billing profile from which funds are withdrawn

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

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

dest_account
string

Target account to which funds are deposited

dest_profile
object

Billing profile to which funds are deposited

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/xia/checkout
responds 
{
  "results": [
    {
      "subscription": {
        "created_at": "2016-06-21T23:24:09.242925Z",
        "ends_at": "2016-10-21T23:24:09.229768Z",
        "description": null,
        "profile": {
          "slug": "xia",
          "printable_name": "Xia Lee",
          "picture": null,
          "type": "personal",
          "credentials": true
        },
        "plan": {
          "slug": "basic",
          "title": "Basic"
        },
        "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_profile": {
            "slug": "cowork",
            "printable_name": "Coworking Space",
            "picture": null,
            "type": "organization",
            "credentials": false
          },
          "orig_amount": 2000,
          "orig_unit": "usd",
          "dest_account": "Payable",
          "dest_profile": {
            "slug": "xia",
            "printable_name": "Xia Lee",
            "picture": null,
            "type": "personal",
            "credentials": true
          },
          "dest_amount": 2000,
          "dest_unit": "usd"
        }
      ],
      "options": []
    }
  ]
}

Checkouts a cart

endpoint 
POST /api/billing/{profile}/checkout

Places an order for the subscription items in the cart and creates a Charge on the billing profile payment method.

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

The cart is manipulated through various API endpoints:

The API is typically used within an HTML checkout page as present in the default theme.

Request body
items
array

List of indices, one per subscription that has multiple advance discount options

option
integer required

selected plan option during checkout

remember_card
boolean

attaches the payment method to the profile when true

processor_token
string

one-time token generated by the processorfrom the payment card.

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

Responses
created_at
string

Date/time of creation (in ISO format)

amount
integer

Total amount in currency unit

unit
string

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

readable_amount
string

Amount and unit in a commonly accepted readable format

description
string

Description for the charge as appears on billing statements

last4
string

Last 4 digits of the credit card used

exp_date
string

Expiration date of the credit card used

processor_key
string

Unique identifier returned by the payment processor

state
string

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

detail
string

Feedback for the user in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"remember_card": true, "processor_token": "tok_23prgoqpstf56todq"}' https://livedemo.djaoapp.com/api/billing/xia/checkout
responds 
{
  "created_at": "2016-06-21T23:42:44.270977Z",
  "processor_key": "pay_5lK5TacFH3gbKe",
  "amount": 2000,
  "unit": "usd",
  "description": "Charge pay_5lK5TacFH3gblP on credit card of Xia",
  "last4": "1234",
  "exp_date": "2016-06-01",
  "state": "created"
}

Lists discount codes

endpoint 
GET /api/billing/{profile}/coupons

Returns a list of page_size coupons created by a provider profile.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

The API is typically used within an HTML coupons page as present in the default theme.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: amount, code, description, discount_type, profile, profile__full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

code
string

Unique identifier per provider, typically used in URLs

discount_type
string

Type of discount ('percentage', 'currency', or 'period')

discount_value
integer

Amount of the discount

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the coupon

nb_attempts
integer

Number of times the coupon can be used

plan
object

Coupon will only apply to this plan

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/cowork/coupons?o=code\&ot=asc\&q=DIS
responds 
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "code": "DIS100",
      "discount_type": "percentage",
      "discount_value": 10000,
      "created_at": "2014-01-01T09:00:00Z",
      "ends_at": null,
      "description": null
    },
    {
      "code": "DIS50",
      "discount_type": "percentage",
      "discount_value": 5000,
      "created_at": "2014-01-01T09:00:00Z",
      "ends_at": null,
      "description": null
    }
  ]
}

Creates a discount code

endpoint 
POST /api/billing/{profile}/coupons

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

The API is typically used within an HTML coupons page as present in the default theme.

Request body
code
string required

Unique identifier per provider, typically used in URLs

discount_type
string required

Type of discount ('percentage', 'currency', or 'period')

discount_value
integer required

Amount of the discount

ends_at
string

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

description
string

Free-form text description for the coupon

nb_attempts
integer

Number of times the coupon can be used

plan
string

Coupon will only apply to this plan

Responses
code
string

Unique identifier per provider, typically used in URLs

discount_type
string

Type of discount ('percentage', 'currency', or 'period')

discount_value
integer

Amount of the discount

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the coupon

nb_attempts
integer

Number of times the coupon can be used

plan
object

Coupon will only apply to this plan

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"code": "DIS100", "discount_type": "percentage", "discount_value": 10000, "ends_at": null, "description": null}' https://livedemo.djaoapp.com/api/billing/cowork/coupons
responds 
{
  "code": "DIS100",
  "discount_type": "percentage",
  "discount_value": 10000,
  "ends_at": null,
  "description": null
}

Retrieves a discount code

endpoint 
GET /api/billing/{profile}/coupons/{coupon}

The API is typically used within an HTML coupons page as present in the default theme.

Responses
code
string

Unique identifier per provider, typically used in URLs

discount_type
string

Type of discount ('percentage', 'currency', or 'period')

discount_value
integer

Amount of the discount

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the coupon

nb_attempts
integer

Number of times the coupon can be used

plan
object

Coupon will only apply to this plan

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/cowork/coupons/DIS100
responds 
{
  "code": "DIS100",
  "discount_type": "percentage",
  "discount_value": 10000,
  "created_at": "2014-01-01T09:00:00Z",
  "ends_at": null,
  "description": null
}

Updates a discount code

endpoint 
PUT /api/billing/{profile}/coupons/{coupon}

The API is typically used within an HTML coupons page as present in the default theme.

Request body
code
string

Unique identifier per provider, typically used in URLs

discount_type
string required

Type of discount ('percentage', 'currency', or 'period')

discount_value
integer

Amount of the discount

ends_at
string

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

description
string

Free-form text description for the coupon

nb_attempts
integer

Number of times the coupon can be used

plan
string

Coupon will only apply to this plan

Responses
code
string

Unique identifier per provider, typically used in URLs

discount_type
string

Type of discount ('percentage', 'currency', or 'period')

discount_value
integer

Amount of the discount

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the coupon

nb_attempts
integer

Number of times the coupon can be used

plan
object

Coupon will only apply to this plan

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"discount_type": "percentage", "discount_value": 10000, "ends_at": null, "description": null}' https://livedemo.djaoapp.com/api/billing/cowork/coupons/DIS100
responds 
{
  "code": "DIS100",
  "discount_type": "percentage",
  "discount_value": 10000,
  "ends_at": null,
  "description": null
}

Deletes a discount code

endpoint 
DELETE /api/billing/{profile}/coupons/{coupon}

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

The API is typically used within an HTML coupons page as present in the default theme.

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/billing/cowork/coupons/DIS100

Lists subscriber transactions

endpoint 
GET /api/billing/{profile}/history

Returns a list of page_size transactions associated to a billing profile while the profile acts as a subscriber.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

The API is typically used within an HTML billing history page as present in the default theme.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: description, dest_profile, dest_profile__full_name, orig_profile, orig_profile__full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
start_at
string

Start of the date range for which the balance was computed

ends_at
string

End of the date range for which the balance was computed

balance_amount
integer

balance of all transactions in cents (i.e. 100ths) of unit

balance_unit
integer

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

count
integer

Total number of items in the results

next
string

API end point to get the next pageof results matching the query

previous
string

API end point to get the previous pageof results matching the query

results
array

Items in the queryset

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

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

orig_account
string

Source account from which funds are withdrawn

orig_profile
object

Billing profile from which funds are withdrawn

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

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

dest_account
string

Target account to which funds are deposited

dest_profile
object

Billing profile to which funds are deposited

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/xia/history?start_at=2015-07-05T07:00:00.000Z
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "start_at": "2015-01-01T00:00:00Z",
  "ends_at": "2016-01-01T00:00:00Z",
  "balance_unit": "usd",
  "balance_amount": 11000,
  "results": [
    {
      "created_at": "2015-08-01T00:00:00Z",
      "description": "Charge for 4 periods",
      "amount": "($356.00)",
      "is_debit": true,
      "orig_account": "Liability",
      "orig_profile": {
        "slug": "xia",
        "printable_name": "Xia",
        "picture": null,
        "type": "personal",
        "credentials": true
      },
      "orig_amount": 112120,
      "orig_unit": "usd",
      "dest_account": "Funds",
      "dest_profile": {
        "slug": "stripe",
        "printable_name": "Stripe",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "dest_amount": 112120,
      "dest_unit": "usd"
    }
  ]
}

Lists provider receivables

endpoint 
GET /api/billing/{profile}/receivables

Returns a list of page_size transactions marked as receivables associated to a billing profile while the profile acts as a provider.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

This API endpoint is typically used to find all sales for a provider, whether it was paid or not.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: description, dest_profile, dest_profile__full_name, orig_profile, orig_profile__full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
start_at
string

Start of the date range for which the balance was computed

ends_at
string

End of the date range for which the balance was computed

balance_amount
integer

balance of all transactions in cents (i.e. 100ths) of unit

balance_unit
integer

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

count
integer

Total number of items in the results

next
string

API end point to get the next pageof results matching the query

previous
string

API end point to get the previous pageof results matching the query

results
array

Items in the queryset

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

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

orig_account
string

Source account from which funds are withdrawn

orig_profile
object

Billing profile from which funds are withdrawn

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

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

dest_account
string

Target account to which funds are deposited

dest_profile
object

Billing profile to which funds are deposited

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/cowork/receivables?start_at=2015-07-05T07:00:00.000Z
responds 
{
  "count": 1,
  "balance_amount": "112120",
  "balance_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-premium",
      "amount": "112120",
      "is_debit": false,
      "orig_account": "Funds",
      "orig_profile": {
        "slug": "stripe",
        "printable_name": "Stripe",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "orig_amount": 112120,
      "orig_unit": "usd",
      "dest_account": "Funds",
      "dest_profile": {
        "slug": "cowork",
        "printable_name": "Coworking Space",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "dest_amount": 112120,
      "dest_unit": "usd"
    }
  ]
}

Lists provider payouts

endpoint 
GET /api/billing/{profile}/transfers

Returns a list of page_size transactions associated to a billing profile while the profile acts as a provider.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

The API is typically used within an HTML funds page as present in the default theme.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: description, dest_profile, dest_profile__full_name, orig_profile, orig_profile__full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
start_at
string

Start of the date range for which the balance was computed

ends_at
string

End of the date range for which the balance was computed

balance_amount
integer

balance of all transactions in cents (i.e. 100ths) of unit

balance_unit
integer

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

count
integer

Total number of items in the results

next
string

API end point to get the next pageof results matching the query

previous
string

API end point to get the previous pageof results matching the query

results
array

Items in the queryset

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

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

orig_account
string

Source account from which funds are withdrawn

orig_profile
object

Billing profile from which funds are withdrawn

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

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

dest_account
string

Target account to which funds are deposited

dest_profile
object

Billing profile to which funds are deposited

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/billing/cowork/transfers?start_at=2015-07-05T07:00:00.000Z
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2015-08-01T00:00:00Z",
      "description": "Charge <a href='/billing/cowork/receipt/1123'>1123</a> distribution for demo562-premium",
      "amount": "$1121.20",
      "is_debit": false,
      "orig_account": "Funds",
      "orig_profile": {
        "slug": "stripe",
        "printable_name": "Stripe",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "orig_amount": 112120,
      "orig_unit": "usd",
      "dest_account": "Funds",
      "dest_profile": {
        "slug": "cowork",
        "printable_name": "Coworking Space",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "dest_amount": 112120,
      "dest_unit": "usd"
    }
  ]
}

Creates an offline transaction

endpoint 
POST /api/billing/{profile}/transfers/import

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

Request body
subscription
string required

The subscription the offline transaction refers to.

created_at
string required

Date/time of creation (in ISO 8601 format)

amount
string required

Total amount in currency unit

descr
string

Free-form text description for the transaction

Responses
detail
string

Describes the result of the action in human-readable form

results
array

transactions being created by the import

created_at
string

Date/time of creation (in ISO format)

description
string

Free-form text description for the transaction

amount
string

Amount being transfered

is_debit
string

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

orig_account
string

Source account from which funds are withdrawn

orig_profile
object

Billing profile from which funds are withdrawn

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

orig_amount
integer

Amount withdrawn from source in orig_unit

orig_unit
string

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

dest_account
string

Target account to which funds are deposited

dest_profile
object

Billing profile to which funds are deposited

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

dest_amount
integer

Amount deposited into target in dest_unit

dest_unit
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"created_at": "2020-05-30T00:00:00Z", "amount": "10.00", "descr": "Paid by check", "subscription": "xia:premium"}' https://livedemo.djaoapp.com/api/billing/cowork/transfers/import
responds 
{
  "detail": "Transaction imported successfully.",
  "results": [
    {
      "created_at": "2020-05-30T00:00:00Z",
      "description": "Paid by check (alice)",
      "amount": "$10.00",
      "is_debit": false,
      "orig_account": "Receivable",
      "orig_profile": {
        "slug": "djaoapp",
        "printable_name": "DjaoApp",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "orig_amount": 1000,
      "orig_unit": "usd",
      "dest_account": "Payable",
      "dest_profile": {
        "slug": "xia",
        "printable_name": "Xia",
        "picture": null,
        "type": "personal",
        "credentials": true
      },
      "dest_amount": 1000,
      "dest_unit": "usd"
    },
    {
      "created_at": "2020-05-30T00:00:00Z",
      "description": "Paid by check (alice)",
      "amount": "$10.00",
      "is_debit": false,
      "orig_account": "Liability",
      "orig_profile": {
        "slug": "xia",
        "printable_name": "Xia",
        "picture": null,
        "type": "personal",
        "credentials": true
      },
      "orig_amount": 1000,
      "orig_unit": "usd",
      "dest_account": "Funds",
      "dest_profile": {
        "slug": "djaoapp",
        "printable_name": "DjaoApp",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "dest_amount": 1000,
      "dest_unit": "usd"
    },
    {
      "created_at": "2020-05-30T00:00:00Z",
      "description": "Keep a balanced ledger",
      "amount": "$10.00",
      "is_debit": false,
      "orig_account": "Payable",
      "orig_profile": {
        "slug": "xia",
        "printable_name": "Xia",
        "picture": null,
        "type": "personal",
        "credentials": true
      },
      "orig_amount": 1000,
      "orig_unit": "usd",
      "dest_account": "Liability",
      "dest_profile": {
        "slug": "xia",
        "printable_name": "Xia",
        "picture": null,
        "type": "personal",
        "credentials": true
      },
      "dest_amount": 1000,
      "dest_unit": "usd"
    },
    {
      "created_at": "2020-05-30T00:00:00Z",
      "description": "Paid by check (alice)",
      "amount": "$10.00",
      "is_debit": false,
      "orig_account": "Backlog",
      "orig_profile": {
        "slug": "djaoapp",
        "printable_name": "DjaoApp",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "orig_amount": 1000,
      "orig_unit": "usd",
      "dest_account": "Receivable",
      "dest_profile": {
        "slug": "djaoapp",
        "printable_name": "DjaoApp",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "dest_amount": 1000,
      "dest_unit": "usd"
    },
    {
      "created_at": "2020-05-30T00:00:00Z",
      "description": "Paid by check (alice) - Keep a balanced ledger",
      "amount": "$0.20",
      "is_debit": false,
      "orig_account": "Funds",
      "orig_profile": {
        "slug": "djaoapp",
        "printable_name": "DjaoApp",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "orig_amount": 20,
      "orig_unit": "usd",
      "dest_account": "Offline",
      "dest_profile": {
        "slug": "djaoapp",
        "printable_name": "DjaoApp",
        "picture": null,
        "type": "organization",
        "credentials": false
      },
      "dest_amount": 20,
      "dest_unit": "usd"
    }
  ]
}

Adds an item to the user cart

endpoint 
POST /api/cart

Adds a plan into the cart of the user identified through the HTTP request.

The cart can later be checked out and paid by a billing profile, either through the HTML checkout 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.

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 billing profile for another profile to be subscribed (see GroupBuy orders).

Request body
plan
string required

The plan to add into the request.user cart.

option
integer

Index in the list of discounts for advance payments

use
string

The use charge to add into the request.user cart.

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

Responses
created_at
string

Date/time of creation (in ISO format)

user
object

User the cart belongs to

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

claim_code
string

Code used to assign the cart item to a user in group buy

plan
object

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

detail
string

Describes the result of the action in human-readable form

created_at
string

Date/time of creation (in ISO format)

user
object

User the cart belongs to

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

claim_code
string

Code used to assign the cart item to a user in group buy

plan
object

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"plan": "premium", "option": 1}' https://livedemo.djaoapp.com/api/cart
responds 
{
  "plan": {
    "slug": "premium",
    "title": "Premium"
  },
  "option": 1,
  "user": {
    "username": "xia",
    "slug": "xia",
    "full_name": "Xia Lee",
    "email": "xia@localhost.localdomain"
  }
}

Removes an item from the user cart

endpoint 
DELETE /api/cart

Removes an item from the request.user cart.

Query parameters
email
string

E-mail address

plan
string

Plan

Responses

204 No Content

 

Examples 
curl -X DELETE https://livedemo.djaoapp.com/api/cart?plan=premium

Redeems a discount code

endpoint 
POST /api/cart/redeem

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

Request body
code
string required

Coupon code to redeem

Responses
detail
string

Describes the reason for the error in plain text

 

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"code": "LABORDAY"}' https://livedemo.djaoapp.com/api/cart/redeem
responds 
{
  "detail": "Coupon 'LABORDAY' was successfully applied."
}

Uploads multiple items into a user cart

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

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

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

Request body
created
array required

Items that have been created in the cart

user
object required

User the cart belongs to

slug
string required

Unique identifier that can safely be used in place of username

username
string required

Unique identifier for the user, typically used in URLs

plan
object required

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

updated
array required

Rows that have been uploaded

user
object required

User the cart belongs to

slug
string required

Unique identifier that can safely be used in place of username

username
string required

Unique identifier for the user, typically used in URLs

plan
object required

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

failed
array required

Rows that have failed to be created in the cart

user
object required

User the cart belongs to

slug
string required

Unique identifier that can safely be used in place of username

username
string required

Unique identifier for the user, typically used in URLs

plan
object required

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

Responses
created
array

Items that have been created in the cart

created_at
string

Date/time of creation (in ISO format)

user
object

User the cart belongs to

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

claim_code
string

Code used to assign the cart item to a user in group buy

plan
object

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

detail
string

Describes the result of the action in human-readable form

updated
array

Rows that have been uploaded

created_at
string

Date/time of creation (in ISO format)

user
object

User the cart belongs to

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

claim_code
string

Code used to assign the cart item to a user in group buy

plan
object

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

detail
string

Describes the result of the action in human-readable form

failed
array

Rows that have failed to be created in the cart

created_at
string

Date/time of creation (in ISO format)

user
object

User the cart belongs to

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

claim_code
string

Code used to assign the cart item to a user in group buy

plan
object

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -X POST https://livedemo.djaoapp.com/api/cart/basic/upload
responds 
{
  "created": [
    {
      "plan": {
        "slug": "basic",
        "title": "Basic"
      },
      "user": {
        "username": "joe",
        "slug": "joe",
        "full_name": "Joe Smith",
        "email": "joesmith@example.com"
      }
    },
    {
      "plan": {
        "slug": "basic",
        "title": "Basic"
      },
      "user": {
        "username": "mariejohnson",
        "slug": "mariejohnson",
        "full_name": "Marie Johnson",
        "email": "mariejohnson@example.com"
      }
    }
  ],
  "updated": [],
  "failed": []
}

Sends a contact-us message

endpoint 
POST /api/contact

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

The API is typically used within an HTML contact page as present in the default theme.

Request body
full_name
string required

Full name the sender of the message wishes to be addressed as

email
string required

Email address to reply to the sender

message
string

Description of the reason for contacting the provider

Responses
detail
string

Describes the reason for the error in plain text

 

Examples 
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"email": "joe+1@example.com", "full_name": "Joe Card1", "message": "Can I request a demo?"}' https://livedemo.djaoapp.com/api/contact
responds 
{
  "detail": "Your request has been sent. We will reply within24 hours. Thank you."
}

Lists activities for a user

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

Returns a list of page_size activity records for user account {user}.

Query parameters
o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: text. searches all fields when unspecified.

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

created_by
object

User that created the activity

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

text
string

Free form text description of the activity

account
object

Account the activity is associated to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/contacts/xia/activities
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2018-01-01T00:00:00Z",
      "text": "Phone call",
      "created_by": {
        "username": "alice",
        "printable_name": "Alice",
        "picture": null,
        "slug": "alice"
      },
      "account": null
    },
    {
      "created_at": "2018-01-02T00:00:00Z",
      "text": "Follow up e-mail",
      "created_by": {
        "username": "alice",
        "printable_name": "Alice",
        "picture": null,
        "slug": "alice"
      },
      "account": {
        "slug": "cowork",
        "printable_name": "Coworking Space",
        "picture": null,
        "type": "organization",
        "credentials": false
      }
    }
  ]
}

Records new activity with a user

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

Free form text description of the activity

account
string required

Account the activity is associated to

Responses
text
string

Free form text description of the activity

account
string

Account the activity is associated to

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"text": "Phone call", "account": "cowork"}' https://livedemo.djaoapp.com/api/contacts/xia/activities
responds 
{
  "text": "Phone call",
  "account": "cowork"
}

List legal agreements

endpoint 
GET /api/legal

Returns a list of page_size legal agreements a user might be requested to sign such as "terms of use" or "security policy". This end point can be used by unauthenticated users. As such it is perfect for legal disclosure pages.

Query parameters
o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, title. searches all fields when unspecified.

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

 

Examples 
curl https://livedemo.djaoapp.com/api/legal
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "terms-of-use",
      "title": "Terms of Use",
      "updated_at": "2023-08-16T00:00:00Z"
    }
  ]
}

Retrieves a legal agreement

endpoint 
GET /api/legal/{agreement}

Retrieves the text of legal agreement a user might be requested to sign. This end point can be used by unauthenticated users. As such it is perfect for legal disclosure pages.

Responses
slug
string

Unique identifier shown in the URL bar

title
string

Short description of the agreement

updated_at
string

Date/time the agreement was last updated (in ISO format)

text
string

Text of the agreement

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/legal/terms-of-use
responds 
{
  "slug": "terms-of-use",
  "title": "Terms of Use",
  "updated_at": "2023-08-16T00:00:00Z",
  "text": "..."
}

Signs a consent agreement

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

Indicates the request user has signed the required consent agreement.

The API is typically used within an HTML legal agreement page as present in the default theme.

Request body
read_terms
boolean required

I have read and understand these terms and conditions

Responses
read_terms
boolean

I have read and understand these terms and conditions

last_signed
string

Date/time of signature (in ISO 8601 format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"read_terms": true}' https://livedemo.djaoapp.com/api/legal/terms-of-use/sign
responds 
{
  "read_terms": true,
  "last_signed": "2019-01-01T00:00:00Z"
}

Retrieves a balance sheet

endpoint 
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/.

Query parameters
ends_at
string

Data/time for the end of the period (in ISO format)

nb_periods
integer

Specify the number of periods to include. Min value is 1.

period_type
string

Natural period length (hourly, daily, weekly, monthly, yearly). Defaults to monthly.

Responses
scale
number

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

unit
string

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

title
string

Title for the table

results
array

Data series

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

List of (datetime, integer) couples that represents the data serie

selector
string

Filter on transaction accounts

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/balances/taxes
responds 
{
  "scale": 0.01,
  "unit": "usd",
  "title": "Balances: taxes",
  "results": [
    {
      "slug": "sales",
      "title": "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

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

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

Query parameters
page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

title
string

Title for the row

selector
string

Filter on transaction accounts

rank
integer

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/balances/taxes/lines
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "title": "Sales",
      "selector": "Receivable",
      "rank": 1
    }
  ]
}

Creates a row in a balance sheet

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

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

Request body
title
string required

Title for the row

selector
string

Filter on transaction accounts

rank
integer required

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

Responses
title
string

Title for the row

selector
string

Filter on transaction accounts

rank
integer

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Sales", "selector": "Receivable", "rank": 1}' https://livedemo.djaoapp.com/api/metrics/balances/taxes/lines
responds 
{
  "title": "Sales",
  "selector": "Receivable",
  "rank": 1
}

Retrieves a row in a balance sheet

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

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

Responses
title
string

Title for the row

selector
string

Filter on transaction accounts

rank
integer

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/balances/taxes/lines/1
responds 
{
  "title": "Sales",
  "selector": "Receivable",
  "rank": 1
}

Updates a row in a balance sheet

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

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

Request body
title
string required

Title for the row

selector
string

Filter on transaction accounts

rank
integer required

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

Responses
title
string

Title for the row

selector
string

Filter on transaction accounts

rank
integer

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Sales", "selector": "Receivable", "rank": 1}' https://livedemo.djaoapp.com/api/metrics/balances/taxes/lines/1
responds 
{
  "title": "Sales",
  "selector": "Receivable",
  "rank": 1
}

Deletes a row in a balance sheet

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

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

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/metrics/balances/taxes/lines/1

Lists top of funnel registered users

endpoint 
GET /api/metrics/registered

Returns a list of page_size users which have no associated role or a role to a profile which has no subscription, active or inactive.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

The API is typically used within an HTML subscribers page as present in the default theme.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: username, first_name, last_name, email, slug, full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/registered
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "alice",
      "username": "alice",
      "full_name": "Alice Cooper",
      "printable_name": "Alice Cooper",
      "picture": null
    }
  ]
}

Retrieves trailing deferred balances

endpoint 
GET /api/metrics/{profile}/balances

Generates a table of currency amounts (rows) per period (columns) for a default balance sheet (Income, Backlog, Receivable).

The date/time returned in results[].values[] specifies the end of the period (not included) for which the associated amount in the tuple is computed.

The date from which trailing balances are computed can be specified by the ends_at query parameter. The type of periods (hourly, daily, weekly, monthly, yearly) to aggregate balances over, and the number of periods to return can be specificed by period_type and nb_periods respectively.

The API is typically used within an HTML revenue page as present in the default theme.

Query parameters
ends_at
string

Data/time for the end of the period (in ISO format)

nb_periods
integer

Specify the number of periods to include. Min value is 1.

period_type
string

Natural period length (hourly, daily, weekly, monthly, yearly). Defaults to monthly.

Responses
scale
number

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

unit
string

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

title
string

Title for the table

results
array

Data series

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

List of (datetime, integer) couples that represents the data serie

selector
string

Filter on transaction accounts

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/cowork/balances
responds 
{
  "title": "Balances",
  "scale": 0.01,
  "unit": "usd",
  "results": [
    {
      "slug": "income",
      "title": "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
        ]
      ]
    },
    {
      "slug": "backlog",
      "title": "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
        ]
      ]
    },
    {
      "slug": "Receivable",
      "title": "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 subscribers to a provider with a balance due

endpoint 
GET /api/metrics/{profile}/balances-due

This endpoint returns a list of organizations with their respective total contract value, payments made, and total balance due.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

balances
object

Dictionary of balances due, keyed by unit

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/cowork/balances-due
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "printable_name": "Xia Lee",
      "picture": null,
      "type": "organization",
      "credentials": false,
      "created_at": "2022-08-31T19:00:00-05:00",
      "balances": {
        "eur": {
          "contract_value": 1333,
          "payments": 0,
          "balance": 1333
        },
        "usd": {
          "contract_value": 982800,
          "cash_payments": 945000,
          "balance": 37800
        }
      }
    }
  ]
}

Retrieves performance of a discount code

endpoint 
GET /api/metrics/{profile}/coupons/{coupon}

Returns a list of page_size cart items on which coupon with code {coupon} was used. Coupon {coupon} must have been created by the specified provider.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: user__username, user__first_name, user__last_name, user__email. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

user
object

User the cart belongs to

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

claim_code
string

Code used to assign the cart item to a user in group buy

plan
object

Item in the cart (if plan)

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

option
integer

Index in the list of discounts for advance payments

use
integer

Item added to the cart (if use charge)

quantity
integer

Number of periods to be paid in advance

sync_on
string

identifier of the person that will benefit from the subscription (GroupBuy)

full_name
string

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

email
string

e-mail of the person that will benefit from the subscription (GroupBuy)

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/cowork/coupons/DIS100
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "user": {
        "slug": "xia",
        "username": "xia",
        "title": "Xia Lee",
        "picture": null
      },
      "plan": {
        "slug": "basic",
        "title": "Basic"
      },
      "created_at": "2014-01-01T09:00:00Z"
    }
  ]
}

Retrieves trailing customer counts

endpoint 
GET /api/metrics/{profile}/customers

Generates a table of total number of customers, number of new customers, number of churned customers, and number of net new customers (rows) per period (columns).

New customers are defined as customers that made an order in the period, but not in the previous period. Churned customers are defined as customers that made an order in the previous period, but not in the period. The net new customers is defined as the number of new customers minus the number of churned customers.

The date/time returned in results[].values[] specifies the end of the period (not included) for which the associated count in the tuple is computed.

The date from which trailing balances are computed can be specified by the ends_at query parameter. The type of periods (hourly, daily, weekly, monthly, yearly) to aggregate balances over, and the number of periods to return can be specificed by period_type and nb_periods respectively.

The API is typically used within an HTML revenue page as present in the default theme.

Query parameters
ends_at
string

Data/time for the end of the period (in ISO format)

nb_periods
integer

Specify the number of periods to include. Min value is 1.

period_type
string

Natural period length (hourly, daily, weekly, monthly, yearly). Defaults to monthly.

Responses
scale
number

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

unit
string

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

title
string

Title for the table

results
array

Data series

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

List of (datetime, integer) couples that represents the data serie

selector
string

Filter on transaction accounts

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/cowork/customers
responds 
{
  "title": "Customers",
  "results": [
    {
      "slug": "total-customers",
      "title": "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
        ]
      ]
    },
    {
      "slug": "new-customers",
      "title": "# 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
        ]
      ]
    },
    {
      "slug": "churned-customers",
      "title": "# 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
        ]
      ]
    },
    {
      "slug": "net-new-customers",
      "title": "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
        ]
      ]
    }
  ]
}

Retrieves churned vs. new subscribers for a federation

endpoint 
GET /api/metrics/{profile}/federated

Returns the number of churned vs. new subscribers per plans for a period for all members of a federation of provider.

Responses
scale
number

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

unit
string

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

title
string

Title for the table

results
array

Data series

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

List of (datetime, integer) couples that represents the data serie

selector
string

Filter on transaction accounts

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/cowork/federated
responds 
{
  "title": "Invited",
  "scale": 1,
  "unit": "profiles",
  "results": [
    {
      "slug": "removed-profiles",
      "title": "removed profiles",
      "values": [
        [
          "Energy utility",
          0
        ]
      ]
    },
    {
      "slug": "invited-profiles",
      "title": "invited profiles",
      "values": [
        [
          "Energy utility",
          0
        ]
      ]
    },
    {
      "slug": "newly-invited-profiles",
      "title": "newly invited profiles",
      "values": [
        [
          "Energy utility",
          0
        ]
      ]
    }
  ]
}

Retrieves shared profiles within a federation

endpoint 
GET /api/metrics/{profile}/federated/shared

Returns the number of shared profiles

Responses
scale
number

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

unit
string

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

title
string

Title for the table

results
array

Data series

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

List of (datetime, integer) couples that represents the data serie

selector
string

Filter on transaction accounts

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/cowork/federated/shared
responds 
{
  "title": "shared profiles",
  "scale": 1,
  "unit": "profiles",
  "results": [
    {
      "slug": "shared",
      "title": "Shared",
      "values": [
        [
          "Energy utility",
          0
        ]
      ]
    }
  ]
}

Retrieves trailing revenue

endpoint 
GET /api/metrics/{profile}/funds

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

The API is typically used within an HTML revenue page as present in the default theme.

Query parameters
ends_at
string

Data/time for the end of the period (in ISO format)

nb_periods
integer

Specify the number of periods to include. Min value is 1.

period_type
string

Natural period length (hourly, daily, weekly, monthly, yearly). Defaults to monthly.

Responses
scale
number

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

unit
string

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

title
string

Title for the table

results
array

Data series

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

List of (datetime, integer) couples that represents the data serie

selector
string

Filter on transaction accounts

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/cowork/funds
responds 
{
  "title": "Amount",
  "scale": 0.01,
  "unit": "usd",
  "results": [
    {
      "slug": "total-sales",
      "title": "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
        ]
      ]
    },
    {
      "slug": "new-sales",
      "title": "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
        ]
      ]
    },
    {
      "slug": "churned-sales",
      "title": "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
        ]
      ]
    },
    {
      "slug": "payments",
      "title": "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
        ]
      ]
    },
    {
      "slug": "refunds",
      "title": "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 customers lifetime value

endpoint 
GET /api/metrics/{profile}/lifetimevalue

Generates the total amount of the contract for a customer, the amount of cash payments towards the contract value made so far by the customer, and the deferred revenue remaining to be recognized on the contract value.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, full_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Since when is the profile a subscriber

ends_at
string

Current end date for the contract

contract_value
integer

Total value to be collected from the profile

cash_payments
integer

Cash payments collected from the profile

deferred_revenue
integer

The deferred revenue for the profile

unit
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/cowork/lifetimevalue
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "title": "Xia Lee",
      "picture": null,
      "type": "personal",
      "credentials": true,
      "created_at": "2014-01-01T09:00:00Z",
      "ends_at": "2014-01-01T09:00:00Z",
      "unit": "usd",
      "contract_value": 10000,
      "cash_payments": 10000,
      "deferred_revenue": 10000
    }
  ]
}

Retrieves trailing plans performance

endpoint 
GET /api/metrics/{profile}/plans

Generates a table of active susbribers for each plan (rows) per period (columns).

The date/time returned in results[].values[] specifies the end of the period (not included) for which the associated count in the tuple is computed.

The date from which trailing balances are computed can be specified by the ends_at query parameter. The type of periods (hourly, daily, weekly, monthly, yearly) to aggregate balances over, and the number of periods to return can be specificed by period_type and nb_periods respectively.

The API is typically used within an HTML revenue page as present in the default theme.

Query parameters
ends_at
string

Data/time for the end of the period (in ISO format)

nb_periods
integer

Specify the number of periods to include. Min value is 1.

period_type
string

Natural period length (hourly, daily, weekly, monthly, yearly). Defaults to monthly.

Responses
scale
number

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

unit
string

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

title
string

Title for the table

results
array

Data series

slug
string

Unique key in the table for the data series

title
string

Title of data serie that can be safely used for display in HTML pages

extra
string

Extra meta data (can be stringify JSON)

values
array

List of (datetime, integer) couples that represents the data serie

selector
string

Filter on transaction accounts

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/metrics/cowork/plans
responds 
{
  "title": "Active Subscribers",
  "results": [
    {
      "is_active": true,
      "slug": "open-space",
      "title": "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,
      "slug": "open-plus",
      "title": "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,
      "slug": "private",
      "title": "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
        ]
      ]
    }
  ]
}

Sends a test notification e-mail

endpoint 
POST /api/notifications/{template}
Responses
detail
string

Describes the result of the API call in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST https://livedemo.djaoapp.com/api/notifications/user_contact
responds 
{
  "detail": "Test email sent to xia@example.com"
}

Lists pricing plans

endpoint 
GET /api/pricing

Returns a list of page_size plans which are active and can be subscribed to.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

The API is typically used within an HTML pricing page as present in the default theme.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, title, profile. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period length of a subscription to the plan (hourly, daily, weekly, monthly, yearly)

advance_discounts
array

Discounts when periods are paid in advance.

discount_type
string

Type of discount (periods, percentage or currency unit)

discount_value
integer

Amount of the discount

length
integer

Contract length associated with the period (defaults to 1)

use_charges
array

Variable pricing based on usage

slug
string

Unique identifier shown in the URL bar

title
string

Short description of the use charge

description
string

Long description of the use charge

created_at
string

Date/time of creation (in ISO format)

use_amount
integer

Amount of the use charge in plan currency unit

quota
integer

Number of use charge included in the plan

maximum_limit
integer

Maximum number of use charge added per period before notififying subscriber

extra
string

Extra meta data (can be stringify JSON)

unit
string

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

profile
object

Provider of the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Number of periods for a subscription to the plan (defaults to 1)

renewal_type
string

What happens at the end of a subscription period (one-time, auto-renew, repeat)

is_not_priced
boolean

True if the plan has no pricing (i.e. contact us)

unlock_event
string

Payment required to access full service

created_at
string

Date/time of creation (in ISO format)

skip_optin_on_grant
boolean

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

optin_on_request
boolean

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

discounted_period_amount
string

Discounted amount for the first period

is_cart_item
string

The plan is part of the cart to checkout

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl https://livedemo.djaoapp.com/api/pricing
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "managed",
      "title": "Managed",
      "description": "Ideal for growing businesses",
      "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",
      "profile": "cowork",
      "extra": null,
      "skip_optin_on_grant": false,
      "optin_on_request": false
    }
  ]
}

Lists billing profiles

endpoint 
GET /api/profile

Returns a list of page_size profile and user accounts.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, full_name, email, phone, street_address, locality, region, postal_code, country, username, first_name, last_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

full_name
string

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The profile can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy

extra
string

Extra meta data (can be stringify JSON)

detail
string

Describes the result of the action in human-readable form

nick_name
string

Short casual name used to address the contact (only available for 'personal' and 'user' accounts)

lang
string

Preferred communication language (only available for 'personal' and 'user' accounts)

 

Examples 
curl https://livedemo.djaoapp.com/api/profile?o=created_at\&ot=desc
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "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": "personal",
      "picture": ""
    }
  ]
}

Retrieves a billing profile

endpoint 
GET /api/profile/{profile}

The API is typically used within an HTML contact information page as present in the default theme.

Responses
slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

full_name
string

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The profile can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy

extra
string

Extra meta data (can be stringify JSON)

detail
string

Describes the result of the action in human-readable form

subscriptions
array

Active subscriptions for the profile

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

nick_name
string

Short casual name used to address the contact (only available for 'personal' and 'user' accounts)

lang
string

Preferred communication language (only available for 'personal' and 'user' accounts)

activities
array

Activities related to the account (only available for 'personal' and 'user' accounts)

created_at
string

Date/time of creation (in ISO format)

created_by
object

User that created the activity

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

text
string

Free form text description of the activity

account
object

Account the activity is associated to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/xia
responds 
{
  "created_at": "2018-01-01T00:00:00Z",
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "printable_name": "Xia Lee",
  "slug": "xia",
  "phone": "555-555-5555",
  "street_address": "185 Berry St #550",
  "locality": "San Francisco",
  "region": "CA",
  "postal_code": "",
  "country": "US",
  "default_timezone": "Europe/Kiev",
  "is_provider": false,
  "is_bulk_buyer": false,
  "type": "",
  "picture": "",
  "subscriptions": [
    {
      "created_at": "2018-01-01T00:00:00Z",
      "ends_at": "2019-01-01T00:00:00Z",
      "plan": {
        "slug": "open-space",
        "title": "Open Space"
      },
      "auto_renew": true
    }
  ]
}

Updates a billing profile

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

Unique identifier shown in the URL bar

picture
string

URL location of the profile picture

full_name
string required

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The profile can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy

extra
string

Extra meta data (can be stringify JSON)

Responses
slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

full_name
string

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The profile can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy

extra
string

Extra meta data (can be stringify JSON)

detail
string

Describes the result of the action in human-readable form

subscriptions
array

Active subscriptions for the profile

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

nick_name
string

Short casual name used to address the contact (only available for 'personal' and 'user' accounts)

lang
string

Preferred communication language (only available for 'personal' and 'user' accounts)

activities
array

Activities related to the account (only available for 'personal' and 'user' accounts)

created_at
string

Date/time of creation (in ISO format)

created_by
object

User that created the activity

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

text
string

Free form text description of the activity

account
object

Account the activity is associated to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"email": "xia@locahost.localdomain", "full_name": "Xia Lee"}' https://livedemo.djaoapp.com/api/profile/xia
responds 
{
  "email": "xia@locahost.localdomain",
  "full_name": "Xia Lee",
  "type": "personal"
}

Deletes a billing profile

endpoint 
DELETE /api/profile/{profile}

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

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/profile/xia

Lists a provider plans

endpoint 
GET /api/profile/{profile}/plans

Returns a list of page_size plans managed by a specified provider.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

Query parameters
active
string

True when customers can subscribe to the plan

ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, title, profile. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period length of a subscription to the plan (hourly, daily, weekly, monthly, yearly)

advance_discounts
array

Discounts when periods are paid in advance.

discount_type
string

Type of discount (periods, percentage or currency unit)

discount_value
integer

Amount of the discount

length
integer

Contract length associated with the period (defaults to 1)

use_charges
array

Variable pricing based on usage

slug
string

Unique identifier shown in the URL bar

title
string

Short description of the use charge

description
string

Long description of the use charge

created_at
string

Date/time of creation (in ISO format)

use_amount
integer

Amount of the use charge in plan currency unit

quota
integer

Number of use charge included in the plan

maximum_limit
integer

Maximum number of use charge added per period before notififying subscriber

extra
string

Extra meta data (can be stringify JSON)

unit
string

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

profile
object

Provider of the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Number of periods for a subscription to the plan (defaults to 1)

renewal_type
string

What happens at the end of a subscription period (one-time, auto-renew, repeat)

is_not_priced
boolean

True if the plan has no pricing (i.e. contact us)

unlock_event
string

Payment required to access full service

created_at
string

Date/time of creation (in ISO format)

skip_optin_on_grant
boolean

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

optin_on_request
boolean

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

discounted_period_amount
string

Discounted amount for the first period

is_cart_item
string

The plan is part of the cart to checkout

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/plans
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "managed",
      "title": "Managed",
      "description": "Ideal for growing businesses",
      "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",
      "profile": "cowork",
      "extra": null,
      "skip_optin_on_grant": false,
      "optin_on_request": false
    }
  ]
}

Creates a plan

endpoint 
POST /api/profile/{profile}/plans

Creates a new subscription plan that belongs to the specified provider.

Request body
slug
string

Unique identifier shown in the URL bar

title
string required

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period length of a subscription to the plan (hourly, daily, weekly, monthly, yearly)

advance_discounts
array

Discounts when periods are paid in advance.

discount_type
string required

Type of discount (periods, percentage or currency unit)

discount_value
integer

Amount of the discount

length
integer

Contract length associated with the period (defaults to 1)

use_charges
array

Variable pricing based on usage

slug
string required

Unique identifier shown in the URL bar

title
string

Short description of the use charge

description
string required

Long description of the use charge

use_amount
integer

Amount of the use charge in plan currency unit

quota
integer

Number of use charge included in the plan

maximum_limit
integer

Maximum number of use charge added per period before notififying subscriber

extra
string

Extra meta data (can be stringify JSON)

unit
string

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

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Number of periods for a subscription to the plan (defaults to 1)

renewal_type
string

What happens at the end of a subscription period (one-time, auto-renew, repeat)

is_not_priced
boolean

True if the plan has no pricing (i.e. contact us)

unlock_event
string

Payment required to access full service

skip_optin_on_grant
boolean

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

optin_on_request
boolean

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

Responses
slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period length of a subscription to the plan (hourly, daily, weekly, monthly, yearly)

advance_discounts
array

Discounts when periods are paid in advance.

discount_type
string

Type of discount (periods, percentage or currency unit)

discount_value
integer

Amount of the discount

length
integer

Contract length associated with the period (defaults to 1)

use_charges
array

Variable pricing based on usage

slug
string

Unique identifier shown in the URL bar

title
string

Short description of the use charge

description
string

Long description of the use charge

created_at
string

Date/time of creation (in ISO format)

use_amount
integer

Amount of the use charge in plan currency unit

quota
integer

Number of use charge included in the plan

maximum_limit
integer

Maximum number of use charge added per period before notififying subscriber

extra
string

Extra meta data (can be stringify JSON)

unit
string

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

profile
object

Provider of the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Number of periods for a subscription to the plan (defaults to 1)

renewal_type
string

What happens at the end of a subscription period (one-time, auto-renew, repeat)

is_not_priced
boolean

True if the plan has no pricing (i.e. contact us)

unlock_event
string

Payment required to access full service

created_at
string

Date/time of creation (in ISO format)

skip_optin_on_grant
boolean

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

optin_on_request
boolean

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

discounted_period_amount
string

Discounted amount for the first period

is_cart_item
string

The plan is part of the cart to checkout

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Popup Desk", "description": "A desk in our coworking space", "is_active": false, "period_amount": 12000, "period_type": "monthly"}' https://livedemo.djaoapp.com/api/profile/cowork/plans
responds 
{
  "title": "Popup Desk",
  "description": "A desk in our coworking space",
  "is_active": false,
  "period_amount": 12000,
  "period_type": "monthly"
}

Retrieves a plan

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

Returns the {plan} that belongs to the specified provider.

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.

The API is typically used within an HTML update plan page as present in the default theme.

Responses
slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period length of a subscription to the plan (hourly, daily, weekly, monthly, yearly)

advance_discounts
array

Discounts when periods are paid in advance.

discount_type
string

Type of discount (periods, percentage or currency unit)

discount_value
integer

Amount of the discount

length
integer

Contract length associated with the period (defaults to 1)

use_charges
array

Variable pricing based on usage

slug
string

Unique identifier shown in the URL bar

title
string

Short description of the use charge

description
string

Long description of the use charge

created_at
string

Date/time of creation (in ISO format)

use_amount
integer

Amount of the use charge in plan currency unit

quota
integer

Number of use charge included in the plan

maximum_limit
integer

Maximum number of use charge added per period before notififying subscriber

extra
string

Extra meta data (can be stringify JSON)

unit
string

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

profile
object

Provider of the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Number of periods for a subscription to the plan (defaults to 1)

renewal_type
string

What happens at the end of a subscription period (one-time, auto-renew, repeat)

is_not_priced
boolean

True if the plan has no pricing (i.e. contact us)

unlock_event
string

Payment required to access full service

created_at
string

Date/time of creation (in ISO format)

skip_optin_on_grant
boolean

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

optin_on_request
boolean

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

discounted_period_amount
string

Discounted amount for the first period

is_cart_item
string

The plan is part of the cart to checkout

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/plans/open-space
responds 
{
  "title": "Open Space",
  "description": "A desk in our coworking space",
  "is_active": false,
  "period_amount": 12000,
  "period_type": "monthly"
}

Updates a plan

endpoint 
PUT /api/profile/{profile}/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.

The API is typically used within an HTML update plan page as present in the default theme.

Request body
slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period length of a subscription to the plan (hourly, daily, weekly, monthly, yearly)

advance_discounts
array

Discounts when periods are paid in advance.

discount_type
string required

Type of discount (periods, percentage or currency unit)

discount_value
integer

Amount of the discount

length
integer

Contract length associated with the period (defaults to 1)

use_charges
array

Variable pricing based on usage

slug
string required

Unique identifier shown in the URL bar

title
string

Short description of the use charge

description
string required

Long description of the use charge

use_amount
integer

Amount of the use charge in plan currency unit

quota
integer

Number of use charge included in the plan

maximum_limit
integer

Maximum number of use charge added per period before notififying subscriber

extra
string

Extra meta data (can be stringify JSON)

unit
string

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

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Number of periods for a subscription to the plan (defaults to 1)

renewal_type
string

What happens at the end of a subscription period (one-time, auto-renew, repeat)

is_not_priced
boolean

True if the plan has no pricing (i.e. contact us)

unlock_event
string

Payment required to access full service

skip_optin_on_grant
boolean

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

optin_on_request
boolean

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

Responses
slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

description
string

Free-form text description for the plan

is_active
boolean

True when customers can subscribe to the plan

setup_amount
integer

One-time amount to pay when the subscription starts

period_amount
integer

Amount billed every period

period_type
string

Natural period length of a subscription to the plan (hourly, daily, weekly, monthly, yearly)

advance_discounts
array

Discounts when periods are paid in advance.

discount_type
string

Type of discount (periods, percentage or currency unit)

discount_value
integer

Amount of the discount

length
integer

Contract length associated with the period (defaults to 1)

use_charges
array

Variable pricing based on usage

slug
string

Unique identifier shown in the URL bar

title
string

Short description of the use charge

description
string

Long description of the use charge

created_at
string

Date/time of creation (in ISO format)

use_amount
integer

Amount of the use charge in plan currency unit

quota
integer

Number of use charge included in the plan

maximum_limit
integer

Maximum number of use charge added per period before notififying subscriber

extra
string

Extra meta data (can be stringify JSON)

unit
string

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

profile
object

Provider of the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

period_length
integer

Number of periods for a subscription to the plan (defaults to 1)

renewal_type
string

What happens at the end of a subscription period (one-time, auto-renew, repeat)

is_not_priced
boolean

True if the plan has no pricing (i.e. contact us)

unlock_event
string

Payment required to access full service

created_at
string

Date/time of creation (in ISO format)

skip_optin_on_grant
boolean

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

optin_on_request
boolean

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

discounted_period_amount
string

Discounted amount for the first period

is_cart_item
string

The plan is part of the cart to checkout

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Open Space"}' https://livedemo.djaoapp.com/api/profile/cowork/plans/open-space
responds 
{
  "title": "Open Space",
  "description": "A desk in our coworking space",
  "is_active": false,
  "period_amount": 12000,
  "period_type": "monthly"
}

Deletes a plan

endpoint 
DELETE /api/profile/{profile}/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.

The API is typically used within an HTML update plan page as present in the default theme.

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/profile/cowork/plans/open-space

Lists plan active subscriptions

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

Returns a list of page_size subscriptions to a {plan} of the provider {profile} whose renewal date is later than the time at which the API call was made.

Optionnaly when an start_at query parameter is specified, the returned queryset is filtered such that each subscription start date (i.e. created_at field) is greater than start_at. Using the start_at query parameter, it is effectively possible to construct cohorts of active subscribers by period of initial subscription.

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

Returned results can be ordered by natural fields (o) in either ascending or descending order by using the minus sign ('-') in front of the ordering field name.

The API is typically used within an HTML subscribers page as present in the default theme.

Query parameters
o
string

sort by created_at, ends_at, profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. If a field is preceded by a minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

full_name
string

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The profile can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy

extra
string

Extra meta data (can be stringify JSON)

detail
string

Describes the result of the action in human-readable form

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/plans/open-space/subscriptions?o=created_at\&ot=desc
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2016-01-14T23:16:55Z",
      "ends_at": "2017-01-14T23:16:55Z",
      "description": null,
      "profile": {
        "slug": "xia",
        "printable_name": "Xia Lee",
        "type": "personal",
        "credentials": true
      },
      "plan": {
        "slug": "open-space",
        "title": "Open Space"
      },
      "auto_renew": true
    }
  ]
}

Grants a subscription

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

Subscribes a customer to the plan {plan} of the specified provider.

Query parameters
force
boolean

Forces invite of user/organization that could not be found

Request body
profile
object required

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

picture
string

URL location of the profile picture

type
string

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

full_name
string required

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The profile can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy

extra
string

Extra meta data (can be stringify JSON)

message
string

Message to send along the invitation

Responses
created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

accept_request_api_url
string

URL API endpoint to grant the subscription

remove_api_url
string

URL API endpoint to remove the subscription grant

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"profile": {"slug": "xia", "full_name": "Xia Lee"}}' https://livedemo.djaoapp.com/api/profile/cowork/plans/premium/subscriptions
responds 
{
  "created_at": "2016-01-14T23:16:55Z",
  "ends_at": "2017-01-14T23:16:55Z",
  "description": null,
  "profile": {
    "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"
  },
  "auto_renew": true
}

Lists plan subscriptions

endpoint 
GET /api/profile/{profile}/plans/{plan}/subscriptions/all

Returns a list of page_size subscriptions to a plan {plan} of the provider {profile}.

The queryset can be filtered for at least one field to match a search term (q) and/or intersects a period (start_at, ends_at).

Returned results can be ordered by natural fields (o) in either ascending or descending order by using the minus sign ('-') in front of the ordering field name.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

sort by created_at, ends_at, profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. If a field is preceded by a minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

accept_request_api_url
string

URL API endpoint to grant the subscription

remove_api_url
string

URL API endpoint to remove the subscription grant

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/plans/premium/subscriptions/all
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "full_name": "Xia Lee",
      "created_at": "2016-01-14T23:16:55Z",
      "ends_at": "2017-01-14T23:16:55Z"
    }
  ]
}

Lists plan churned subscriptions

endpoint 
GET /api/profile/{profile}/plans/{plan}/subscriptions/churned

Returns a list of page_size subscriptions to a {plan} of the provider {profile} which have ended already at the time the API call was made.

Optionally by defining either start_at, ends_at , or both, it is possible to construct cohorts of subscribers that have churned within a period.

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

Returned results can be ordered by natural fields (o) in either ascending or descending order by using the minus sign ('-') in front of the ordering field name.

The API is typically used within an HTML subscribers page as present in the default theme.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

sort by created_at, ends_at, profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. If a field is preceded by a minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

accept_request_api_url
string

URL API endpoint to grant the subscription

remove_api_url
string

URL API endpoint to remove the subscription grant

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/plans/open-space/subscriptions/churned?o=created_at\&ot=desc
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2016-01-14T23:16:55Z",
      "ends_at": "2017-01-14T23:16:55Z",
      "description": null,
      "profile": {
        "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"
      },
      "auto_renew": true
    }
  ]
}

Retrieves a plan subscription

endpoint 
GET /api/profile/{profile}/plans/{plan}/subscriptions/{subscriber}

Returns the subscription of {subscriber} to a plan {plan} of the specified provider.

Responses
created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

accept_request_api_url
string

URL API endpoint to grant the subscription

remove_api_url
string

URL API endpoint to remove the subscription grant

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/plans/open-space/subscriptions/xia
responds 
{
  "created_at": "2019-01-01T00:00:00Z",
  "ends_at": "2020-01-01T00:00:00Z",
  "profile": {
    "slug": "xia",
    "printable_name": "Xia Lee",
    "picture": null,
    "type": "personal",
    "credentials": true
  },
  "plan": {
    "slug": "open-space",
    "title": "Open Space"
  },
  "description": null,
  "auto_renew": true,
  "extra": null,
  "grant_key": null,
  "request_key": null
}

Updates a plan subscription

endpoint 
PUT /api/profile/{profile}/plans/{plan}/subscriptions/{subscriber}

Updates the subscription of {subscriber} to a plan {plan} of the specified provider.

Request body
ends_at
string required

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

description
string

Free-form text description for the subscription

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

Responses
created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

accept_request_api_url
string

URL API endpoint to grant the subscription

remove_api_url
string

URL API endpoint to remove the subscription grant

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"ends_at": "2020-01-01T00:00:00Z", "description": "extended after call with customer"}' https://livedemo.djaoapp.com/api/profile/cowork/plans/open-space/subscriptions/xia
responds 
{
  "created_at": "2019-01-01T00:00:00Z",
  "ends_at": "2020-01-01T00:00:00Z",
  "profile": {
    "slug": "xia",
    "printable_name": "Xia Lee",
    "picture": null,
    "type": "personal",
    "credentials": true
  },
  "plan": {
    "slug": "open-space",
    "title": "Open Space"
  },
  "description": null,
  "auto_renew": true,
  "extra": null,
  "grant_key": null,
  "request_key": null
}

Cancels subscription

endpoint 
DELETE /api/profile/{profile}/plans/{plan}/subscriptions/{subscriber}

Provider cancels a {subscriber}'s subscription to a plan {plan}, effective at the time the API is called.

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/profile/cowork/plans/open-space/subscriptions/xia

Lists users and their role on an profile

endpoint 
GET /api/profile/{profile}/roles
Query parameters
o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: user, user__full_name, user__email, role, role__title. searches all fields when unspecified.

Responses
invited_count
integer

Number of user invited to have a role

requested_count
integer

Number of user requesting a role

count
integer

Total number of items in the results

next
string

API end point to get the next pageof results matching the query

previous
string

API end point to get the previous pageof results matching the query

results
array

Items in the queryset

created_at
string

Date/time of creation (in ISO format)

user
object

User with the role

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Key to identify the grant of the role

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

accept_request_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/xia/roles
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "invited_count": 0,
  "requested_count": 0,
  "results": [
    {
      "created_at": "2022-01-01T00:00:00Z",
      "role_description": {
        "title": "Manager",
        "slug": "manager",
        "profile": null
      },
      "user": {
        "slug": "xia",
        "username": "xia",
        "printable_name": "Xia Lee",
        "picture": null
      },
      "request_key": "1",
      "grant_key": null
    }
  ]
}

Lists role types

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

Lists roles by description``RoleDescription``.

see Flexible Security Framework.

Query parameters
o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, title. searches all fields when unspecified.

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/xia/roles/describe
responds 
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2023-01-01T00:00:00Z",
      "slug": "manager",
      "title": "Manager",
      "skip_optin_on_grant": false,
      "implicit_create_on_none": false,
      "is_global": true
    },
    {
      "created_at": "2023-01-01T00:00:00Z",
      "slug": "contributor",
      "title": "Contributor",
      "skip_optin_on_grant": true,
      "implicit_create_on_none": false,
      "is_global": false,
      "profile": {
        "slug": "xia",
        "printable_name": "Xia",
        "picture": null,
        "type": "personal",
        "credentials": true,
        "created_at": "2023-01-01T00:00:00Z"
      }
    }
  ]
}

Creates a role type

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

Creates a role that users can take on a profile.

see Flexible Security Framework.

Request body
title
string required

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

extra
string

Extra meta data (can be stringify JSON)

Responses
created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Support"}' https://livedemo.djaoapp.com/api/profile/xia/roles/describe
responds 
{
  "created_at": "2023-01-01T00:00:00Z",
  "title": "Support",
  "slug": "support",
  "skip_optin_on_grant": false,
  "implicit_create_on_none": false,
  "is_global": false,
  "profile": {
    "slug": "xia",
    "printable_name": "Xia",
    "picture": null,
    "type": "personal",
    "credentials": true,
    "created_at": "2023-01-01T00:00:00Z"
  }
}

Retrieves a role type

endpoint 
GET /api/profile/{profile}/roles/describe/{role}
Responses
created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/xia/roles/describe/manager
responds 
{
  "created_at": "2023-01-01T00:00:00Z",
  "slug": "manager",
  "title": "Profile Manager",
  "skip_optin_on_grant": false,
  "implicit_create_on_none": false,
  "is_global": true
}

Updates a role type

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

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

extra
string

Extra meta data (can be stringify JSON)

Responses
created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"title": "Associate"}' https://livedemo.djaoapp.com/api/profile/xia/roles/describe/support
responds 
{
  "created_at": "2023-01-01T00:00:00Z",
  "slug": "support",
  "title": "Associate",
  "skip_optin_on_grant": false,
  "implicit_create_on_none": false,
  "is_global": false,
  "profile": {
    "slug": "xia",
    "printable_name": "Xia",
    "picture": null,
    "type": "personal",
    "credentials": true,
    "created_at": "2023-01-01T00:00:00Z"
  }
}

Deletes a role type

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

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/profile/xia/roles/describe/support

Lists roles of a specific type

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

Lists the specified role assignments for a profile.

Query parameters
o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: user, user__full_name, user__email. searches all fields when unspecified.

Responses
invited_count
integer

Number of user invited to have a role

requested_count
integer

Number of user requesting a role

count
integer

Total number of items in the results

next
string

API end point to get the next pageof results matching the query

previous
string

API end point to get the previous pageof results matching the query

results
array

Items in the queryset

created_at
string

Date/time of creation (in ISO format)

user
object

User with the role

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Key to identify the grant of the role

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

accept_request_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl https://livedemo.djaoapp.com/api/profile/cowork/roles/manager
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "invited_count": 0,
  "requested_count": 0,
  "results": [
    {
      "created_at": "2018-01-01T00:00:00Z",
      "role_description": {
        "name": "Manager",
        "slug": "manager",
        "profile": null
      },
      "user": {
        "slug": "alice",
        "printable_name": "Alice Doe",
        "picture": null
      },
      "request_key": "1",
      "grant_key": null
    }
  ]
}

Creates a role

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

Attaches a user to a specified billing profile with a {role}, typically granting permissions to the user with regards to managing the profile (see Flexible Security Framework).

Query parameters
force
boolean

Forces invite of user/organization that could not be found

Request body
slug
string

Username

email
string

E-mail of user to grant role onto profile (potentially generating an invite to the site)

full_name
string

Full name of user to grant role onto profile (potentially generating an invite to the site)

extra
string

Extra meta data (can be stringify JSON)

message
string

Message to send along the invitation

Responses
created_at
string

Date/time of creation (in ISO format)

user
object

User with the role

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Key to identify the grant of the role

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

accept_request_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"slug": "xia"}' https://livedemo.djaoapp.com/api/profile/xia/roles/manager
responds 
{
  "created_at": "2023-01-01T00:00:00Z",
  "role_description": {
    "created_at": "2023-01-01T00:00:00Z",
    "title": "Profile Manager",
    "slug": "manager",
    "is_global": true
  },
  "user": {
    "slug": "xia",
    "username": "xia",
    "printable_name": "Xia Lee",
    "picture": null
  },
  "grant_key": null
}

Retrieves a role through a profile

endpoint 
GET /api/profile/{profile}/roles/{role}/{user}

Retrieves the role of a user on a profile.

Responses
created_at
string

Date/time of creation (in ISO format)

user
object

User with the role

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Key to identify the grant of the role

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

accept_request_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/xia/roles/manager/xia
responds 
{
  "created_at": "2023-01-01T00:00:00Z",
  "role_description": {
    "created_at": "2023-01-01T00:00:00Z",
    "title": "Profile Manager",
    "slug": "manager",
    "is_global": true
  },
  "user": {
    "slug": "xia",
    "username": "xia",
    "printable_name": "Xia Lee",
    "picture": null
  },
  "grant_key": null
}

Sends invite notification for a role

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

Re-sends the notification that the {user} was granted a {role} on the specified billing profile.

Responses
created_at
string

Date/time of creation (in ISO format)

user
object

User with the role

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Key to identify the grant of the role

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

accept_request_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST https://livedemo.djaoapp.com/api/profile/xia/roles/manager/xia
responds 
{
  "created_at": "2023-01-01T00:00:00Z",
  "role_description": {
    "created_at": "2023-01-01T00:00:00Z",
    "title": "Profile Manager",
    "slug": "manager",
    "is_global": true
  },
  "user": {
    "slug": "xia",
    "username": "xia",
    "printable_name": "Xia Lee",
    "picture": null
  },
  "grant_key": null
}

Updates role meta information

endpoint 
PUT /api/profile/{profile}/roles/{role}/{user}

Updates meta information for a role.

Request body
extra
string

Extra meta data (can be stringify JSON)

Responses
created_at
string

Date/time of creation (in ISO format)

user
object

User with the role

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Key to identify the grant of the role

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

accept_request_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"extra": {"kinship": "self"}}' https://livedemo.djaoapp.com/api/profile/xia/roles/manager/xia
responds 
{
  "created_at": "2023-01-01T00:00:00Z",
  "role_description": {
    "created_at": "2023-01-01T00:00:00Z",
    "title": "Profile Manager",
    "slug": "manager",
    "is_global": true
  },
  "user": {
    "slug": "xia",
    "username": "xia",
    "printable_name": "Xia Lee",
    "picture": null
  },
  "grant_key": null,
  "extra": {
    "kinship": "self"
  }
}

Deletes a role through a profile

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

Dettaches a {user} from one or all roles with regards to the specified billing profile, typically resulting in revoking permissions from the user to manage part of the profile.

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/profile/xia/roles/manager/xia

Lists active subscribers

endpoint 
GET /api/profile/{profile}/subscribers

Returns a list of page_size subscribers which have an active subscription to a plan of the specified provider {profile}.

The queryset can be filtered for at least one field to match a search term (q) and/or intersects a period (start_at, ends_at).

Returned results can be ordered by natural fields (o) in either ascending or descending order by using the minus sign ('-') in front of the ordering field name.

The API is typically used in search forms linked to providers.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, full_name, email, phone, street_address, locality, region, postal_code, country, username, first_name, last_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/subscribers?o=created_at\&ot=desc
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "printable_name": "Xia Lee",
      "picture": null,
      "type": "personal",
      "credentials": true
    }
  ]
}

Grants a subscription request

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

Accepts a subscription request identified by {request_key}. The subscription must be to a plan that belongs to the specified provider.

Responses
created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

accept_request_api_url
string

URL API endpoint to grant the subscription

remove_api_url
string

URL API endpoint to remove the subscription grant

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST https://livedemo.djaoapp.com/api/profile/cowork/subscribers/accept/a00000d0a0000001234567890123456789012345
responds 
{
  "created_at": "2019-01-01T00:00:00Z",
  "ends_at": "2020-01-01T00:00:00Z",
  "description": null,
  "profile": {
    "slug": "xia",
    "printable_name": "Xia Lee",
    "picture": null,
    "type": "personal",
    "credentials": true
  },
  "plan": {
    "slug": "open-space",
    "title": "Open Space"
  },
  "auto_renew": true,
  "extra": null,
  "grant_key": null,
  "request_key": null
}

Lists subscribers

endpoint 
GET /api/profile/{profile}/subscribers/all

Returns a list of page_size subscribers which have or had a subscription to a plan of the specified provider {profile}.

The queryset can be filtered for at least one field to match a search term (q) and/or intersects a period (start_at, ends_at).

Returned results can be ordered by natural fields (o) in either ascending or descending order by using the minus sign ('-') in front of the ordering field name.

The API is typically used in search forms linked to providers.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, full_name, email, phone, street_address, locality, region, postal_code, country, username, first_name, last_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/subscribers/all?o=created_at\&ot=desc
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "printable_name": "Xia Lee",
      "picture": null,
      "type": "personal",
      "credentials": true
    }
  ]
}

Lists engaged subscribers

endpoint 
GET /api/profile/{profile}/subscribers/engaged

Returns a list of page_size subscribers which have or had a subscription to a plan of the specified provider {profile}.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

Query parameters
o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: first_name, last_name, profile, profile__full_name. searches all fields when unspecified.

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

user
object

User with the role

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Key to identify the grant of the role

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

accept_request_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

detail
string

Describes the result of the action in human-readable form

profile
object

Profile the user has a role on

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/subscribers/engaged?o=created_at\&ot=desc
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2022-01-01T00:00:00Z",
      "user": {
        "slug": "xia23",
        "email": "123@example.com",
        "full_name": "",
        "created_at": "2022-01-01T00:00:00Z",
        "last_login": "2022-01-01T00:00:00Z"
      },
      "role_description": {
        "created_at": "2022-01-01T00:00:00Z",
        "slug": "manager",
        "title": "Profile Manager",
        "skip_optin_on_grant": false,
        "implicit_create_on_none": false,
        "is_global": true,
        "profile": null,
        "extra": null
      },
      "accept_request_api_url": "http://127.0.0.1:8000/api/profile/xia23/roles/manager",
      "remove_api_url": "http://127.0.0.1:8000/api/profile/xia23/roles/manager/admin",
      "profile": {
        "slug": "xia23",
        "printable_name": "Xia23",
        "picture": null,
        "type": "organization",
        "credentials": false,
        "created_at": "2022-01-01T00:00:00Z"
      }
    }
  ]
}

Lists provider active subscriptions

endpoint 
GET /api/profile/{profile}/subscribers/subscriptions

Returns a list of page_size subscriptions whose renewal date is later than the time at which the API call was made, and the owner of the subscription plan is the specified provider {profile}.

Optionnaly when an start_at query parameter is specified, the returned queryset is filtered such that each subscription start date (i.e. created_at field) is greater than start_at. Using the start_at query parameter, it is effectively possible to construct cohorts of active subscribers by period of initial subscription.

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

Returned results can be ordered by natural fields (o) in either ascending or descending order by using the minus sign ('-') in front of the ordering field name.

The API is typically used within an HTML subscribers page as present in the default theme.

Query parameters
o
string

sort by created_at, ends_at, profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. If a field is preceded by a minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

full_name
string

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The profile can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy

extra
string

Extra meta data (can be stringify JSON)

detail
string

Describes the result of the action in human-readable form

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/subscribers/subscriptions?o=created_at\&ot=desc
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2016-01-14T23:16:55Z",
      "ends_at": "2017-01-14T23:16:55Z",
      "description": null,
      "profile": {
        "slug": "xia",
        "printable_name": "Xia Lee",
        "type": "personal",
        "credentials": true
      },
      "plan": {
        "slug": "open-space",
        "title": "Open Space"
      },
      "auto_renew": true
    }
  ]
}

Lists provider subscriptions

endpoint 
GET /api/profile/{profile}/subscribers/subscriptions/all

Returns a list of page_size subscriber profiles which have or had a subscription to a plan of the specified provider.

The queryset can be filtered for at least one field to match a search term (q) and/or intersects a period (start_at, ends_at).

Returned results can be ordered by natural fields (o) in either ascending or descending order by using the minus sign ('-') in front of the ordering field name.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

sort by created_at, ends_at, profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. If a field is preceded by a minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

accept_request_api_url
string

URL API endpoint to grant the subscription

remove_api_url
string

URL API endpoint to remove the subscription grant

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/subscribers/subscriptions/all?o=created_at\&ot=desc
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2016-01-14T23:16:55Z",
      "ends_at": "2022-01-14T23:16:55Z",
      "description": null,
      "profile": {
        "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"
      },
      "auto_renew": true
    }
  ]
}

Lists provider churned subscriptions

endpoint 
GET /api/profile/{profile}/subscribers/subscriptions/churned

Returns a list of page_size subscriptions which have ended already the time at which the API call was made, and the owner of the subscription plan is the specified provider {profile}.

Optionally by defining either start_at, ends_at , or both, it is possible to construct cohorts of subscribers that have churned within a period.

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

Returned results can be ordered by natural fields (o) in either ascending or descending order by using the minus sign ('-') in front of the ordering field name.

The API is typically used within an HTML subscribers page as present in the default theme.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

sort by created_at, ends_at, profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. If a field is preceded by a minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

accept_request_api_url
string

URL API endpoint to grant the subscription

remove_api_url
string

URL API endpoint to remove the subscription grant

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/subscribers/subscriptions/churned?o=created_at\&ot=desc
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2016-01-14T23:16:55Z",
      "ends_at": "2017-01-14T23:16:55Z",
      "description": null,
      "profile": {
        "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"
      },
      "auto_renew": true
    }
  ]
}

Lists inactive subscribers

endpoint 
GET /api/profile/{profile}/subscribers/unengaged

Returns a list of page_size subscribers which have or had a subscription to a plan of the specified provider {profile}.

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

Query parameters
o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, full_name, email, phone, street_address, locality, region, postal_code, country, username, first_name, last_name. searches all fields when unspecified.

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/cowork/subscribers/unengaged?o=created_at\&ot=desc
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "printable_name": "Xia Lee",
      "picture": null,
      "type": "organization",
      "credentials": false,
      "created_at": "2016-01-14T23:16:55Z"
    }
  ]
}

Lists present subscriptions

endpoint 
GET /api/profile/{profile}/subscriptions

Returns a list of page_size subscriptions for subscriber {profile} whose renewal date is later than the time at which the API call was made.

The queryset can be filtered such that each subscription initial start date is greater than the start_at query parameter.

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

Returned results can be ordered by natural fields (o) in either ascending or descending order by using the minus sign ('-') in front of the ordering field name.

The API is typically used within an HTML subscriptions page as present in the default theme.

Query parameters
o
string

sort by created_at, ends_at, profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. If a field is preceded by a minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

remove_api_url
string

URL API endpoint to remove the subscription request

editable
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/xia/subscriptions?o=created_at\&ot=desc
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2016-01-14T23:16:55Z",
      "ends_at": "2017-01-14T23:16:55Z",
      "description": null,
      "profile": {
        "slug": "xia",
        "printable_name": "Xia Lee",
        "picture": null,
        "type": "personal",
        "credentials": true
      },
      "plan": {
        "slug": "open-space",
        "title": "Open Space"
      },
      "auto_renew": true,
      "app_url": "https://livedemo.djaoapp.com/app/xia/open-space/"
    }
  ]
}

Lists expired subscriptions

endpoint 
GET /api/profile/{profile}/subscriptions/expired

Returns a list of page_size subscriptions for subscriber {profile} which have ended already the time at which the API call was made.

Optionally by defining either start_at, ends_at , or both, it is possible to find subscriptions which have expired within a specified period.

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

Returned results can be ordered by natural fields (o) in either ascending or descending order by using the minus sign ('-') in front of the ordering field name.

The API is typically used within an HTML subscriptions page as present in the default theme.

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

sort by created_at, ends_at, profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. If a field is preceded by a minus sign ('-'), the order will be reversed. Multiple 'o' parameters can be specified to produce a stable result.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: profile, profile__full_name, profile__email, profile__phone, profile__street_address, profile__locality, profile__region, profile__postal_code, profile__country, plan, plan__title. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

remove_api_url
string

URL API endpoint to remove the subscription request

editable
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/xia/subscriptions/expired?o=created_at\&ot=desc
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2016-01-14T23:16:55Z",
      "ends_at": "2017-01-14T23:16:55Z",
      "description": null,
      "profile": {
        "slug": "xia",
        "printable_name": "Xia Lee",
        "picture": null,
        "type": "personal",
        "credentials": true
      },
      "plan": {
        "slug": "open-space",
        "title": "Open Space"
      },
      "auto_renew": true,
      "app_url": "https://livedemo.djaoapp.com/app/xia/open-space/"
    }
  ]
}

Retrieves a subscriber subscription

endpoint 
GET /api/profile/{profile}/subscriptions/{subscribed_plan}

Returns a subscription to plan {subscribed_plan} for the specified subscriber.

Responses
created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

remove_api_url
string

URL API endpoint to remove the subscription request

editable
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/profile/xia/subscriptions/open-space
responds 
{
  "created_at": "2019-01-01T00:00:00Z",
  "ends_at": "2020-01-01T00:00:00Z",
  "description": null,
  "profile": {
    "slug": "xia",
    "printable_name": "Xia Lee",
    "picture": null,
    "type": "personal",
    "credentials": true
  },
  "plan": {
    "slug": "open-space",
    "title": "Open Space"
  },
  "auto_renew": true,
  "app_url": "https://livedemo.djaoapp.com/app/xia/open-space/",
  "editable": true,
  "extra": null,
  "grant_key": null,
  "request_key": null
}

Unsubscribes at a future date

endpoint 
PUT /api/profile/{profile}/subscriptions/{subscribed_plan}

Unsubscribes a specified subscriber from a plan {subscribed_plan} at a future date.

The API is typically used within an HTML subscribers page as present in the default theme.

Request body
ends_at
string required

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

description
string

Free-form text description for the subscription

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

Responses
created_at
string

Date/time of creation (in ISO format)

ends_at
string

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

description
string

Free-form text description for the subscription

profile
object

Profile subscribed to the plan

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

plan
object

Plan the profile is subscribed to

slug
string

Unique identifier shown in the URL bar

title
string

Title for the plan

auto_renew
boolean

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

extra
string

Extra meta data (can be stringify JSON)

grant_key
string

Unique key generated when a grant is initiated

request_key
string

Unique key generated when a request is initiated

app_url
string

URL to access the subscribed service

remove_api_url
string

URL API endpoint to remove the subscription request

editable
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"ends_at": "2020-01-01T00:00:00Z"}' https://livedemo.djaoapp.com/api/profile/xia/subscriptions/open-space
responds 
{
  "created_at": "2019-01-01T00:00:00Z",
  "ends_at": "2020-01-01T00:00:00Z",
  "description": null,
  "profile": {
    "slug": "xia",
    "printable_name": "Xia Lee",
    "picture": null,
    "type": "personal",
    "credentials": true
  },
  "plan": {
    "slug": "open-space",
    "title": "Open Space"
  },
  "auto_renew": true,
  "editable": true,
  "extra": null,
  "grant_key": null,
  "request_key": null
}

Unsubscribes now

endpoint 
DELETE /api/profile/{profile}/subscriptions/{subscribed_plan}

Unsubscribes a specified subscriber from a plan {subscribed_plan}.

The API is typically used within an HTML subscribers page as present in the default theme.

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/profile/xia/subscriptions/open-space

Retrieves forward end-point

endpoint 
GET /api/proxy

Returns the URL endpoint to which requests passing the access rules 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 session API endpoint.

Responses
slug
string

unique identifier for the site (also serves as subdomain)

entry_point
string

Entry point to which requests will be redirected to

session_backend
integer

Format to encode session in the forwarded HTTP request

authentication
string

Restricted authentication and registration

welcome_email
boolean

Send a welcome e-mail to newly registered users

cors_restricted
boolean

Set CORS headers on HTTP responses

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/proxy
responds 
{
  "slug": "cowork",
  "entry_point": "https://cowork.herokuapp.com/",
  "session_backend": 1
}

Updates forward end-point

endpoint 
PUT /api/proxy

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

Request body
entry_point
string

Entry point to which requests will be redirected to

session_backend
integer

Format to encode session in the forwarded HTTP request

authentication
string

Restricted authentication and registration

welcome_email
boolean

Send a welcome e-mail to newly registered users

cors_restricted
boolean

Set CORS headers on HTTP responses

detail
string

Describes the result of the action in human-readable form

Responses
slug
string

unique identifier for the site (also serves as subdomain)

entry_point
string

Entry point to which requests will be redirected to

session_backend
integer

Format to encode session in the forwarded HTTP request

authentication
string

Restricted authentication and registration

welcome_email
boolean

Send a welcome e-mail to newly registered users

cors_restricted
boolean

Set CORS headers on HTTP responses

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"entry_point": "https://cowork.herokuapp.com/", "session_backend": 1}' https://livedemo.djaoapp.com/api/proxy
responds 
{
  "slug": "cowork",
  "entry_point": "https://cowork.herokuapp.com/",
  "session_backend": 1
}

Retrieves users engagement

endpoint 
GET /api/proxy/engagement
Responses
engagements
array

Engagement tags by user

slug
string

Engagement tag

count
integer

Number of users that have engaged with this tag

active_users
integer

Number of users that have engaged with the app

authentication
string

Restricted authentication and registration

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/proxy/engagement
responds 
{
  "active_users": 10,
  "authentication": "enabled",
  "engagements": []
}

Retrieves engagement metrics

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

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

username
string

Username

engagements
string

Engagement tags for username

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/proxy/engagement/users
responds 
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "username": "alice",
      "engagements": [
        "app",
        "profile"
      ]
    },
    {
      "username": "kenneth",
      "engagements": [
        "app",
        "billing"
      ]
    }
  ]
}

Rotates session encoding key

endpoint 
POST /api/proxy/key

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

Responses
enc_key
string

Key used to decrypt the encoded session information.

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST https://livedemo.djaoapp.com/api/proxy/key
responds 
{
  "enc_key": "********"
}

Retrieves recently active users

endpoint 
GET /api/proxy/recent

The API is typically used within an HTML dashboard page as present in the default theme.

Query parameters
page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier for the user or profile

printable_name
string

Name that can be safely used for display in HTML pages

descr
string

Description of the activity

created_at
string

Date/time of creation (in ISO format)

type
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/proxy/recent
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "printable_name": "Alice Cooper",
      "descr": "recently logged in",
      "created_at": "2019-07-15T20:40:29.509572Z",
      "slug": "alice"
    }
  ]
}

Lists access rules

endpoint 
GET /api/proxy/rules

Returns a list of page_size rules incoming HTTP requests are checked against.

Query parameters
page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

rank
integer

Determines the order in which rules are considered

path
string

OpenAPI path against which requests are matched

allow
string

Method applied to grant or deny access

is_forward
boolean

When access is granted, should the request be forwarded

engaged
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/proxy/rules
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "rank": 0,
      "path": "/",
      "allow": 1,
      "is_forward": true,
      "engaged": "app"
    }
  ]
}

Creates an access rule

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

Determines the order in which rules are considered

path
string required

OpenAPI path against which requests are matched

allow
string

Method applied to grant or deny access

is_forward
boolean

When access is granted, should the request be forwarded

engaged
string

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

Responses
rank
integer

Determines the order in which rules are considered

path
string

OpenAPI path against which requests are matched

allow
string

Method applied to grant or deny access

is_forward
boolean

When access is granted, should the request be forwarded

engaged
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"rank": 0, "path": "/", "allow": 1, "is_forward": true, "engaged": ""}' https://livedemo.djaoapp.com/api/proxy/rules
responds 
{
  "rank": 0,
  "path": "/",
  "allow": 1,
  "is_forward": true,
  "engaged": ""
}

Retrieves an access rule

endpoint 
GET /api/proxy/rules/{path}
Responses
rank
integer

Determines the order in which rules are considered

path
string

OpenAPI path against which requests are matched

allow
string

Method applied to grant or deny access

is_forward
boolean

When access is granted, should the request be forwarded

engaged
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/proxy/rules/app
responds 
{
  "rank": 0,
  "path": "/app",
  "allow": 1,
  "is_forward": true,
  "engaged": ""
}

Updates an access rule

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

Determines the order in which rules are considered

allow
string

Method applied to grant or deny access

is_forward
boolean

When access is granted, should the request be forwarded

engaged
string

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

Responses
rank
integer

Determines the order in which rules are considered

path
string

OpenAPI path against which requests are matched

allow
string

Method applied to grant or deny access

is_forward
boolean

When access is granted, should the request be forwarded

engaged
string

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

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"rank": 0, "allow": 1, "is_forward": true, "engaged": ""}' https://livedemo.djaoapp.com/api/proxy/rules/app
responds 
{
  "rank": 0,
  "path": "/app",
  "allow": 1,
  "is_forward": true,
  "engaged": ""
}

Deletes an access rule

endpoint 
DELETE /api/proxy/rules/{path}
Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/proxy/rules/app

Retrieves example session

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

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

Responses
forward_session
string

The session being forwarded

forward_session_header
string

The HTTP header that encodes the session

forward_url
string

The URL end point where the request is forwarded

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/proxy/sessions/xia
responds 
{
  "forward_session": "{username: xia}",
  "forward_session_header": "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzbHVnIjoieGlhIiwicHJpbnRhYmxlX25hbWUiOiJYaWEgTGVlIiwicGljdHVyZSI6bnVsbCwiZW1haWwiOiJzbWlyb2xvKzExQGRqYW9kamluLmNvbSIsImNyZWF0ZWRfYXQiOiIyMDIxLTAxLTAxVDAwOjAwOjAwWiIsImNyZWRlbnRpYWxzIjp0cnVlLCJ1c2VybmFtZSI6InhpYSIsImZ1bGxfbmFtZSI6IlhpYSBMZWUiLCJleHAiOjE2MzI5MzM0NDJ9.ZFA3-LH3O7z7JVZdpBLz0AbnZd-zFtqiehk40Jc5uya",
  "forward_url": "https://cowork.herokuapp.com/"
}

Uploads a theme package

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

Request body
files
string required

Content of the theme package as a zip file.

Responses
location
string

URL where the theme package was uploaded.

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST https://livedemo.djaoapp.com/api/themes
responds 
{
  "location": "https://themes.*mydomain*/"
}

Removes custom theme

endpoint 
DELETE /api/themes

Removes the custom theme templates and assets.

Pages will be using the default theme after a reset.

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/themes

Retrives edit tools toggle

endpoint 
GET /api/themes/tools
Responses
show_edit_tools
boolean

Show the online editor tools

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/themes/tools
responds 
{
  "show_edit_tools": true
}

Toggles edit tools on/off

endpoint 
PUT /api/themes/tools
Request body
show_edit_tools
boolean

Show the online editor tools

Responses
show_edit_tools
boolean

Show the online editor tools

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"show_edit_tools": true}' https://livedemo.djaoapp.com/api/themes/tools
responds 
{
  "show_edit_tools": true
}

Lists user accounts

endpoint 
GET /api/users

Returns a list of page_size profile and user accounts.

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

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: email, username. searches all fields when unspecified.

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/users?q=xia
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "slug": "xia",
      "username": "xia",
      "printable_name": "Xia"
    }
  ]
}

Creates a user account

endpoint 
POST /api/users
Request body
slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string required

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

email_code
integer

Email verification code

phone_code
integer

Phone verification code

new_password
string

Password with which a user can authenticate with the service

Responses
slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

detail
string

Describes the reason for the error in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"full_name": "Xia Lee", "nick_name": "Xia", "email": "xia@locahost.localdomain"}' https://livedemo.djaoapp.com/api/users
responds 
{
  "slug": "xia",
  "username": "xia",
  "created_at": "2018-01-01T00:00:00Z",
  "printable_name": "Xia",
  "full_name": "Xia Lee",
  "nick_name": "Xia",
  "email": "xia@locahost.localdomain"
}

Retrieves a user account

endpoint 
GET /api/users/{user}

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

The API is typically used within an HTML contact information page as present in the default theme.

Responses
slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/users/donny
responds 
{
  "slug": "donny",
  "username": "donny",
  "created_at": "2018-01-01T00:00:00Z",
  "printable_name": "Donny",
  "full_name": "Donny Smith",
  "email": "donny.smith@locahost.localdomain"
}

Updates a user account

endpoint 
PUT /api/users/{user}

The API is typically used within an HTML contact information page as present in the default theme.

Request body
slug
string

Unique identifier that can safely be used in place of username

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string required

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

email_code
integer

Email verification code

phone_code
integer

Phone verification code

Responses
slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"email": "xia@locahost.localdomain", "full_name": "Xia Lee", "nick_name": "Xia"}' https://livedemo.djaoapp.com/api/users/xia
responds 
{
  "slug": "xia",
  "username": "xia",
  "created_at": "2018-01-01T00:00:00Z",
  "printable_name": "Xia",
  "full_name": "Xia Lee",
  "nick_name": "Xia",
  "email": "xia@locahost.localdomain"
}

Deletes a user account

endpoint 
DELETE /api/users/{user}

The API is typically used within an HTML contact information page as present in the default theme.

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/users/xia

Lists roles by user

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

Returns a list of page_size roles where a profile is accessible by {user}. Typically the user was granted a role with specific permissions on the profile.

The queryset can be further refined to match a search filter (q) and sorted on specific fields (o).

The API is typically used within an HTML connected profiles page as present in the default theme.

see Flexible Security Framework.

Query parameters
o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: profile, profile__full_name, profile__email, role, role__title. searches all fields when unspecified.

Responses
invited_count
integer

Number of user invited to have a role

requested_count
integer

Number of user requesting a role

count
integer

Total number of items in the results

next
string

API end point to get the next pageof results matching the query

previous
string

API end point to get the previous pageof results matching the query

results
array

Items in the queryset

created_at
string

Date/time of creation (in ISO format)

request_key
string

Key to identify the request for the role

profile
object

Profile the user has a role on

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

home_url
string

URL to the homepage for the profile associated to the role

settings_url
string

URL to the settings page for the profile associated to the role

accept_grant_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/users/xia/accessibles
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "invited_count": 0,
  "requested_count": 0,
  "results": [
    {
      "profile": {
        "slug": "cowork",
        "printable_name": "ABC Corp.",
        "type": "organization",
        "credentials": false
      },
      "role_description": {
        "slug": "manager",
        "created_at": "2023-01-01T00:00:00Z",
        "title": "Profile Manager",
        "is_global": true,
        "profile": 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

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

Creates a request to connect {user} to a profile

The API is typically used within an HTML connected profiles page as present in the default theme.

see Flexible Security Framework.

Query parameters
force
boolean

Forces invite of user/organization that could not be found

Request body
slug
string

Profile to grant {user} a role onto

email
string

E-mail of profile to grant {user} a role onto (potentially generating an invite to the site)

message
string

Message to send along the invitation

Responses
created_at
string

Date/time of creation (in ISO format)

request_key
string

Key to identify the request for the role

profile
object

Profile the user has a role on

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

home_url
string

URL to the homepage for the profile associated to the role

settings_url
string

URL to the settings page for the profile associated to the role

accept_grant_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"slug": "cowork"}' https://livedemo.djaoapp.com/api/users/xia/accessibles
responds 
{
  "profile": {
    "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

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

Accepts a role identified by {verification_key}.

The API is typically used within an HTML connected profiles page as present in the default theme.

Responses
created_at
string

Date/time of creation (in ISO format)

request_key
string

Key to identify the request for the role

profile
object

Profile the user has a role on

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

home_url
string

URL to the homepage for the profile associated to the role

settings_url
string

URL to the settings page for the profile associated to the role

accept_grant_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT https://livedemo.djaoapp.com/api/users/xia/accessibles/accept/a00000d0a0000001234567890123456789012345
responds 
{
  "created_at": "2023-01-01T00:00:00Z",
  "role_description": {
    "created_at": "2023-01-01T00:00:00Z",
    "title": "Profile Manager",
    "slug": "manager",
    "is_global": true
  },
  "profile": {
    "slug": "cowork",
    "printable_name": "ABC Corp.",
    "type": "organization",
    "credentials": false
  }
}

Lists roles of specific type by user

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

Returns a list of page_size roles where a profile is accessible by {user} through a {role}. Typically the user was granted the {role} with specific permissions on the profile.

The queryset can be further refined to match a search filter (q) and sorted on specific fields (o).

The API is typically used within an HTML connected profiles page as present in the default theme.

see Flexible Security Framework.

Query parameters
o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: profile, profile__full_name, profile__email. searches all fields when unspecified.

Responses
invited_count
integer

Number of user invited to have a role

requested_count
integer

Number of user requesting a role

count
integer

Total number of items in the results

next
string

API end point to get the next pageof results matching the query

previous
string

API end point to get the previous pageof results matching the query

results
array

Items in the queryset

created_at
string

Date/time of creation (in ISO format)

request_key
string

Key to identify the request for the role

profile
object

Profile the user has a role on

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

home_url
string

URL to the homepage for the profile associated to the role

settings_url
string

URL to the settings page for the profile associated to the role

accept_grant_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/users/xia/accessibles/manager
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "invited_count": 0,
  "requested_count": 0,
  "results": [
    {
      "profile": {
        "slug": "cowork",
        "printable_name": "ABC Corp.",
        "type": "organization",
        "credentials": false
      },
      "role_description": {
        "slug": "manager",
        "created_at": "2023-01-01T00:00:00Z",
        "title": "Profile manager",
        "is_global": true,
        "profile": 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

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

Creates a request to connect {user} to a profile with a specified {role}.

The API is typically used within an HTML connected profiles page as present in the default theme.

see Flexible Security Framework.

Query parameters
force
boolean

Forces invite of user/organization that could not be found

Request body
slug
string

Profile to grant {user} a role onto

email
string

E-mail of profile to grant {user} a role onto (potentially generating an invite to the site)

message
string

Message to send along the invitation

Responses
created_at
string

Date/time of creation (in ISO format)

request_key
string

Key to identify the request for the role

profile
object

Profile the user has a role on

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

home_url
string

URL to the homepage for the profile associated to the role

settings_url
string

URL to the settings page for the profile associated to the role

accept_grant_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"slug": "cowork"}' https://livedemo.djaoapp.com/api/users/xia/accessibles/manager
responds 
{
  "profile": {
    "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": "2023-01-01T00:00:00Z",
    "title": "Profile manager",
    "is_global": true,
    "profile": null
  },
  "home_url": "/app/cowork/",
  "settings_url": "/profile/cowork/contact/",
  "accept_grant_api_url": null,
  "remove_api_url": "/api/users/xia/accessibles/manager/cowork"
}

Retrieves a role through a user

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

Retrieves the accessible role for a profile by a user.

Responses
created_at
string

Date/time of creation (in ISO format)

request_key
string

Key to identify the request for the role

profile
object

Profile the user has a role on

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

home_url
string

URL to the homepage for the profile associated to the role

settings_url
string

URL to the settings page for the profile associated to the role

accept_grant_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/users/xia/accessibles/manager/cowork
responds 
{
  "created_at": "2023-01-01T00:00:00Z",
  "role_description": {
    "created_at": "2023-01-01T00:00:00Z",
    "title": "Profile Manager",
    "slug": "manager",
    "is_global": true
  },
  "profile": {
    "slug": "cowork",
    "printable_name": "ABC Corp.",
    "type": "organization",
    "credentials": false
  },
  "request_key": null
}

Sends request notification for role

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

Re-sends the notification that the {user} is requesting a {role} on the specified billing profile.

Responses
created_at
string

Date/time of creation (in ISO format)

request_key
string

Key to identify the request for the role

profile
object

Profile the user has a role on

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

role_description
object

Description of the role

created_at
string

Date/time of creation (in ISO format)

slug
string

Unique identifier shown in the URL bar

title
string

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

skip_optin_on_grant
boolean

Automatically grants the role without requiring a user to accept it.

implicit_create_on_none
boolean

Automatically adds the role when a user and profile share the same e-mail domain.

otp_required
boolean

Requires users with the role to sign-in using an OTP code as a multi-factor authentication.

is_global
boolean

True when the role type is available for all profiles

profile
object

Profile the role type belongs to

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

extra
string

Extra meta data (can be stringify JSON)

editable
string

True if the request user is able to update the role description. Typically a profile manager for the organization (local role description) or the broker (global role descriptions).

home_url
string

URL to the homepage for the profile associated to the role

settings_url
string

URL to the settings page for the profile associated to the role

accept_grant_api_url
string

URL API endpoint to grant the role

remove_api_url
string

URL API endpoint to remove the role grant or request

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST https://livedemo.djaoapp.com/api/users/xia/accessibles/manager/cowork
responds 
{
  "created_at": "2023-01-01T00:00:00Z",
  "role_description": {
    "created_at": "2023-01-01T00:00:00Z",
    "title": "Profile Manager",
    "slug": "manager",
    "is_global": true
  },
  "profile": {
    "slug": "cowork",
    "printable_name": "ABC Corp.",
    "type": "organization",
    "credentials": false
  },
  "request_key": null
}

Deletes a role through a user

endpoint 
DELETE /api/users/{user}/accessibles/{role}/{profile}

Dettaches {user} from one or all roles with regards to the specified billing profile, typically resulting in revoking permissions from this user to manage part of the profile.

The API is typically used within an HTML connected profiles page as present in the default theme.

Responses

204 No Content

 

Examples 
curl -X DELETE https://livedemo.djaoapp.com/api/users/xia/accessibles/manager/cowork

Sends an activation link

endpoint 
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
slug
string

Unique identifier that can safely be used in place of username

username
string

Unique identifier for the user, typically used in URLs

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

email
string

Primary e-mail address to contact user

phone
string

Primary phone number to contact user

full_name
string

Full name (effectively first name followed by last name)

nick_name
string

Short casual name used to address the user

lang
string

Preferred communication language

credentials
string

True if the user has valid login credentials

otp_enabled
string

True if the user has valid login credentials

created_at
string

Date at which the user account was created

last_login
string

Date at which the user last logged in

email_code
integer

Email verification code

phone_code
integer

Phone verification code

detail
string

Describes the reason for the error in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST https://livedemo.djaoapp.com/api/users/donny/activate
responds 
{
  "slug": "xia",
  "username": "xia",
  "printable_name": "Xia",
  "full_name": "Xia Lee",
  "nick_name": "Xia",
  "email": "xia@locahost.localdomain",
  "created_at": "2018-01-01T00:00:00Z"
}

Lists user API keys

endpoint 
GET /api/users/{user}/api-keys

Lists the API keys with which a user can authenticate with the service.

Query parameters
o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: title. searches all fields when unspecified.

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

title
string

Short description of the notification

api_pub_key
string

Unique public identifier for the API key

ends_at
string

Date/time at which the API key expires (in ISO format)

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/users/xia/api-keys
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "api_pub_key": "k9Q9YppQMnZ7Yh5bDkx2wsQvDfL4U3TM",
      "title": "production"
    }
  ]
}

Creates an API key

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

Creates an API key with which a user can authenticate with the service.

Request body
password
string

Password of the user making the HTTP request

otp_code
integer

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

email_code
integer

Email verification code.

phone_code
integer

Phone verification code.

title
string

Title of the new keypair

Responses
secret
string

Secret API Key used to authenticate user on every HTTP request

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"password": "yoyo"}' https://livedemo.djaoapp.com/api/users/xia/api-keys
responds 
{
  "secret": "tgLwDw5ErQ2pQr5TTdAzSYjvZenHC9pSy7fB3sXWERzynbG5zG6h    67pTN4dh7fpy"
}

Deletes a user API key

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

Deletes the API key which user used to authenticate with the service.

Request body
password
string

Password of the user making the HTTP request

otp_code
integer

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

email_code
integer

Email verification code.

phone_code
integer

Phone verification code.

Responses
detail
string

Describes the reason for the error in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"password": "yoyo"}' https://livedemo.djaoapp.com/api/users/xia/api-keys/k9Q9YppQMnZ7Yh5bDkx2wsQvDfL4U3TM
responds 
{
  "detail": "API key deleted successfully."
}

Lists a user notifications preferences

endpoint 
GET /api/users/{user}/notifications
Responses
notifications
array

List of notifications from card_updated, charge_updated, claim_code_generated, expires_soon, order_executed, period_sales_report_created, profile_updated, role_request_created, user_activated, user_contact, user_registered, user_welcome

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/users/donny/notifications
responds 
{
  "notifications": [
    "user_registered_notice"
  ]
}

Changes a user notifications preferences

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

List of notifications from card_updated, charge_updated, claim_code_generated, expires_soon, order_executed, period_sales_report_created, profile_updated, role_request_created, user_activated, user_contact, user_registered, user_welcome

Responses
notifications
array

List of notifications from card_updated, charge_updated, claim_code_generated, expires_soon, order_executed, period_sales_report_created, profile_updated, role_request_created, user_activated, user_contact, user_registered, user_welcome

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"notifications": ["user_registered_notice"]}' https://livedemo.djaoapp.com/api/users/donny/notifications
responds 
{
  "notifications": [
    "user_registered_notice"
  ]
}

Enables multi-factor authentication

endpoint 
PUT /api/users/{user}/otp

Enables multi-factor authentication, through either an OTP one-time code, email verification, phone verification or any combination of the above.

To disable any of the MFA requirements, pass a false value for its respective field.

The API is typically used within an HTML update password page as present in the default theme.

Request body
password
string

Password of the user making the HTTP request

otp_code
integer

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

email_code
integer

Email verification code.

phone_code
integer

Phone verification code.

otp_enabled
boolean required

Enables/disables OTP

email_verification_enabled
boolean required

Enables/disables E-mail verification

phone_verification_enabled
boolean required

Enables/disables Phone verification

Responses
priv_key
string

Private key

provisioning_uri
string

Provisioning URI

detail
string

Describes the reason for the error in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"password": "yoyo", "otp_enabled": true, "email_verification_enabled": false, "phone_verification_enabled": false}' https://livedemo.djaoapp.com/api/users/xia/otp
responds 
{
  "priv_key": "**********************",
  "provisioning_uri": "https://localhost:8020/"
}

Updates a user password

endpoint 
PUT /api/users/{user}/password

Sets a new password for a user. Any or a combination of the HTTP request user secrets must be passed along for authorization.

The API is typically used within an HTML update password page as present in the default theme.

Request body
password
string

Password of the user making the HTTP request

otp_code
integer

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

email_code
integer

Email verification code.

phone_code
integer

Phone verification code.

new_password
string required

New password for the user referenced in the URL

Responses
detail
string

Describes the reason for the error in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"password": "yoyo", "new_password": "yeye"}' https://livedemo.djaoapp.com/api/users/xia/password
responds 
{
  "detail": "Password updated successfully."
}

Removes a user password

endpoint 
DELETE /api/users/{user}/password

Technically this de-activates a user. An e-mail verification will be required before the user can be activate again.

Responses

204 No Content

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X DELETE https://livedemo.djaoapp.com/api/users/xia/password

Lists billing profiles with a user as a profile manager

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

Returns a list of page_size of profiles

The queryset can be further refined to match a search filter (q) and/or a range of dates ([start_at, ends_at]), and sorted on specific fields (o).

Query parameters
ends_at
string

date/time in ISO 8601 format

o
string

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

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page between 1 and 100 (defaults to 25).

q
string

value to search for in the fields specified by q_f

q_f
string

restrict searches to one or more fields in: slug, full_name, email, phone, street_address, locality, region, postal_code, country, username, first_name, last_name. searches all fields when unspecified.

start_at
string

date/time in ISO 8601 format

Responses
count
integer

The number of records

next
string

API end point to get the next page of records matching the query

previous
string

API end point to get the previous page of records matching the query

results
array

Records in the queryset

slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

full_name
string

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The profile can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy

extra
string

Extra meta data (can be stringify JSON)

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' https://livedemo.djaoapp.com/api/users/xia/profiles?o=created_at
responds 
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created_at": "2023-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": "personal",
      "picture": ""
    }
  ]
}

Creates a connected profile

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

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

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

Request body
slug
string

Unique identifier shown in the URL bar

picture
string

URL location of the profile picture

type
string

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

full_name
string required

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The profile can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy

extra
string

Extra meta data (can be stringify JSON)

Responses
slug
string

Unique identifier shown in the URL bar

printable_name
string

Name that can be safely used for display in HTML pages

picture
string

URL location of the profile picture

type
string

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

credentials
string

True if the account has valid login credentials

created_at
string

Date/time of creation (in ISO format)

full_name
string

Full name

email
string

E-mail address

phone
string

Phone number

street_address
string

Street address

locality
string

City/Town

region
string

State/Province/County

postal_code
string

Zip/Postal code

country
String

Country as 2-letter code (ISO 3166-1)

default_timezone
string

Timezone to use when reporting metrics

is_provider
boolean

The profile can fulfill the provider side of a subscription.

is_bulk_buyer
boolean

Enable GroupBuy

extra
string

Extra meta data (can be stringify JSON)

detail
string

Describes the result of the action in human-readable form

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"full_name": "My Project"}' https://livedemo.djaoapp.com/api/users/xia/profiles
responds 
{
  "slug": "myproject",
  "full_name": "My Project"
}

Updates a user public RSA key

endpoint 
PUT /api/users/{user}/ssh-keys

Sets a new public RSA key for a user. Any or a combination of the HTTP request user secrets must be passed along for authorization.

Request body
password
string

Password of the user making the HTTP request

otp_code
integer

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

email_code
integer

Email verification code.

phone_code
integer

Phone verification code.

pubkey
string required

New public key for the user referenced in the URL

Responses
detail
string

Describes the reason for the error in plain text

 

Examples 
curl -H 'Authorization: Bearer JWT auth token' -X PUT -H 'Content-Type: application/json; charset=UTF-8' -d '{"pubkey": "ssh-rsa AAAAB3N...", "password": "yoyo"}' https://livedemo.djaoapp.com/api/users/xia/ssh-keys
responds 
{
  "detail": "Public key updated successfully."
}