Managing Sub Accounts via API
Flow XO allows users on an Agency plan to create and manage sub-accounts via our API.
The following sub-account management functions are available:
1. Creating a sub account
2. Adding users to a sub-account
3. Listing sub-accounts
4. Listing details/usage for a single sub-account
5. Adding a team member to a sub-account
6. Fetching team-members associated with a sub-account
Authorization
You must authorize all calls to the Flow XO API using your API key and an authorization header. Details can be found here: https://support.flowxo.com/article/289-api-authorization
API Url
To use the Flow XO API, you will need to send HTTP requests to the following endpoint. The last part of the URL will depend on the method you are calling, but the base address is:
https://flowxo.com/api/users/subaccounts
Sub Accounts
Creating a new sub-account
You can add a sub-account to your agency account by issuing a POST request:
POST https://flowxo.com/api/users/subaccounts
With the following payload:
{
"email":"primary_contact_email@yourcustomer.com",
"company_name":"Your Customer Company Name",
"given_name":"Your primary contact first name",
"family_name":"Your primary contact last name",
"role":"Client",
"timezone":"America/Los_Angeles"
}
The result will look like this:
{
"account": {
"_id": "xxx",
"api_key": "eyJhbGciOiJ...Szg7X2tzVLFJSeMDSY",
"parent_account": "yyy",
"timezone": "America/Los_Angeles",
"company_name": "Your Customer Company Name",
"email": "primary_contact_email@yourcustomer.com",
"created_at": "2021-11-12T00:47:42.754Z",
"usage": {
"rateable_workflows_count": 0,
"rateable_bots_count": 0,
"rateable_items_count": 0,
"rateable_items_limit": 15,
"rateable_items_limit_bonus": 0,
"rateable_users_count": 0,
"rateable_users_limit": 5,
"rateable_users_limit_bonus": 0,
"rateable_sub_accounts_count": 0,
"rateable_sub_accounts_limit": 0,
"rateable_sub_accounts_limit_bonus": 0,
"rateable_runs_count": 0,
"rateable_runs_limit": 5000,
"rateable_runs_limit_bonus": 0,
"rateable_runs_count_all_time": 0,
"rateable_runs_history": [],
"rateable_runs_test_limit": 100,
"rateable_runs_test_count": 0,
"rateable_runs_test_last_used": 1636677705849,
"rateable_runs_limit_started_at": "2021-11-12T00:47:42.754Z",
"rateable_runs_limit_reset_at": "2021-12-12T00:47:42.754Z"
}
},
"teamMembers": [
{
"_id": "zzz",
"email": "subtwo@flowxo.com",
"given_name": "Your primary contact first name",
"family_name": "Your primary contact last name",
"login_attempts": 0,
"role": "Client",
"token": "eyJhbGciOiJ...3MqQ2HnSRYbDmkfD6AULD-xSrs",
"account": "618db9aea657230949c99ea3"
}
]
}
Most of the returned fields are self explanatory, however there are two that are of particular interest:
1. account.api_key : This is the API key of the sub-account. You can use this to access the API on behalf of the sub account.
2. teamMember.token : This is the authorization token for the primary team member that is always added along with a sub-account. You can use this token to embed live chat in your back office, and also to call the Flow XO API on behalf of that sub-account team member, for example to access conversation history or analytics.
Listing Sub-Accounts
You can list all sub-accounts by issuing a GET request:
GET https://flowxo.com/api/users/subaccounts
The result will look like this:
[
{
"_id": "xxx",
"api_key": "eyJhbGc...cvxurW0OZY8EyC0",
"parent_account": "xxx",
"timezone": "America/Los_Angeles",
"company_name": "Company 2",
"email": "sub1@flowxo.com",
"created_at": "2021-11-05T16:04:12.806Z",
"usage": {
"rateable_workflows_count": 1,
"rateable_bots_count": 0,
"rateable_items_count": 1,
"rateable_items_limit": 15,
"rateable_items_limit_bonus": 0,
"rateable_users_count": 0,
"rateable_users_limit": 5,
"rateable_users_limit_bonus": 0,
"rateable_sub_accounts_count": 0,
"rateable_sub_accounts_limit": 0,
"rateable_sub_accounts_limit_bonus": 0,
"rateable_runs_limit_bonus": 0,
"rateable_runs_test_limit": 100,
"rateable_runs_test_count": 0,
"rateable_runs_test_last_used": 1636676652683
}
},
{
"_id": "yyy",
"api_key": "eyJhbGciOiJIUz...TBjA_NDE",
"parent_account": "zzz",
"timezone": "America/Los_Angeles",
"company_name": "Beep Beep",
"email": "sub2@flowxo.com",
"created_at": "2021-11-05T16:06:40.650Z",
"usage": {
"rateable_workflows_count": 0,
"rateable_bots_count": 0,
"rateable_items_count": 0,
"rateable_items_limit": 15,
"rateable_items_limit_bonus": 0,
"rateable_users_count": 1,
"rateable_users_limit": 5,
"rateable_users_limit_bonus": 0,
"rateable_sub_accounts_count": 0,
"rateable_sub_accounts_limit": 0,
"rateable_sub_accounts_limit_bonus": 0,
"rateable_runs_limit_bonus": 0,
"rateable_runs_test_limit": 100,
"rateable_runs_test_count": 0,
"rateable_runs_test_last_used": 1636588761646
}
}
]
This results in a list of all the sub-accounts associated with your agency.
Listing a single sub-account
You can retrieve the data of a single sub-account by issuing a GET request:
GET https://flowxo.com/api/users/subaccounts/{your_sub_account_id}
The result will look like this:
{
"_id": "yyy",
"api_key": "eyJhbGciOiJIUz...TBjA_NDE",
"parent_account": "zzz",
"timezone": "America/Los_Angeles",
"company_name": "Beep Beep",
"email": "sub2@flowxo.com",
"created_at": "2021-11-05T16:06:40.650Z",
"usage": {
"rateable_workflows_count": 0,
"rateable_bots_count": 0,
"rateable_items_count": 0,
"rateable_items_limit": 15,
"rateable_items_limit_bonus": 0,
"rateable_users_count": 1,
"rateable_users_limit": 5,
"rateable_users_limit_bonus": 0,
"rateable_sub_accounts_count": 0,
"rateable_sub_accounts_limit": 0,
"rateable_sub_accounts_limit_bonus": 0,
"rateable_runs_limit_bonus": 0,
"rateable_runs_test_limit": 100,
"rateable_runs_test_count": 0,
"rateable_runs_test_last_used": 1636588761646
}
}
Listing team members in a sub-account
You can retrieve the team members associated with a sub account with a GET request
GET https://flowxo.com/api/users/subaccounts/{your_sub_account_id}/team_members
The result will look like this:
[
{
"_id": "xxx",
"email": "sub2@flowxo.com",
"given_name": "first name",
"family_name": "laast name",
"login_attempts": 0,
"role": "Client",
"token": "eyJhbGciOiJIUzI1NiI...lZGcD8L_2Z6eMvDCHdh-B59enB1U",
"account": "6185569056534072bf0fa37a"
}
]
Note the 'token' field where you can get the authorization token you will need to embed live chat or access the API on behalf of each sub-account team member.
Adding a team-member to a sub-account
You can add a team member to any sub-account to your agency account by issuing a POST request:
POST https://flowxo.com/api/users/subaccounts/{your_sub_account_id}/team_members
With the following payload:
{
"email":"another_sub_team_member@somewhere.com",
"given_name":"First",
"family_name":"Last"
}
The result will look like this:
{
"_id": "xxx",
"email": "another_sub_team_member@somewhere.com",
"given_name": "First",
"family_name": "Last",
"login_attempts": 0,
"role": "Client",
"token": "eyJhbGciOiJIUz...DRq6Eda8ONBp1Rz8Z9F1tftXejriFEss",
"account": "618565404d5801829f10f5f9"
}
That's It for now!
We will add more API calls in the future to remove sub-accounts or update them, but these should be enough to get started with a fully developed agency account. Let us know if you have questions/feedback on this API at support@flowxo.com