Who can use this feature?
System administrator
Plan Type: Enterprise
Difficulty: Medium
Qwil Messenger offers 22 System APIs enabling Enterprise customers to perform group and user management functions. Actions performed by APIs follow the same rules as conventionally using Qwil, but allow greater freedom for automation and integration.
This guide will help you develop programmes to automate your organisations messaging using the following API calls. You can also view all our APIs by accessing our Postman collection.
You will need to provide certain permissions for your keys to perform certain functions. These are outlined with each endpoint. The options are:
- This key can export data
- This key can perform read-only admin actions
- This key can perform write-only admin actions
- This key can perform data reviewer actions
To read more about this and learn how to set up and maintain your System API keys, click here.
The URL must contain the environment of your organisation:
https://{{environment}}.qwil.io/entity-service/
Entity Memberships
Existing Members
- /sys-api/entity-memberships/suspend POST
- /sys-api/entity-memberships/unsuspend POST
- /sys-api/entity-memberships/avatar GET
- /sys-api/chats/list GET
- /sys-api/chats/export/pdf GET
- /sys-api/chats/export/zip GET
New Member
- /sys-api/entity-memberships/create POST
- /sys-api/entity-memberships/update POST
- /sys-api/entity-memberships/invitations/resend POST
- /sys-api/entity-memberships/phone-numbers/update POST
- /sys-api/entity-memberships/emails/update POST
- /sys-api/entity-memberships/profile/update POST
- /sys-api/entity-memberships/destroy POST
- /sys-api/entity-memberships/restore POST
- /sys-api/entity-memberships/list GET
- /sys-api/entity-memberships GET
- /sys-api/entity-memberships/group-memberships/list/chat-service/api/contacts GET
- /sys-api/export/entities GET
Groups
New Group
- /sys-api/groups/create POST
- /sys-api/groups/update POST
- /sys-api/groups/group-members/create POST
- /sys-api/groups/group-members/destroy POST
- /sys-api/groups/destroy POST
Existing Group
sys-api/entity-memberships/suspend POST
This API call allows the suspension of users. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Note: The user will get notified that they are suspended and will no longer have access to the organisation. They will still appear active to other users.
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"entity_user_xref_uuids": "{{entity_user_xref_uuid_sam_brown}}"
}
sys-api/entity-service/sys-api/entity-memberships/unsuspend POST
This API call allows the un-suspension of users. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"entity_user_xref_uuids": "{{entity_user_xref_uuid_sam_brown}}"
}
sys-api/entity-memberships/avatar GET
This call returns the avatar of a user. For error codes click here.
Permissions: "This key can perform read-only admin actions"
Note: If the user has not added a profile picture, the avatar call will return:"error_code": "RN013"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"entity_user_xref_uuids": "{{entity_user_xref_uuid_sam_brown}}"
}
sys-api/chats/list GET
This call returns the chats and messages in an organisation. For error codes click here.
Permissions: "This key can perform data reviewer actions actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"date": "{{date}}" (optional),
"page": "{{page number}}" (optional),
"per_page": "{{number of entries per page}}" (optional)
}
sys-api/chats/export/pdf GET
This call returns a pdf transcript of the messages from a chat. For error codes click here.
Permissions: "This key can perform data reviewer actions actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"chat_uuid": "{{chat_uuid}}"
}
sys-api/chats/export/zip GET
This call returns a zip file of the transcript of a chat in your organisation. For error codes click here.
Permissions: "This key can perform data reviewer actions actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"chat_uuid": "{{chat_uuid}}"
}
/sys-api/entity-memberships/create POST
This call creates a staff user. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"enum_profile_id" : "{{enum_profile_id_staff}}",
"first_name" : "{{first_name}}",
"last_name" : "{{last_name}}",
"group_uuids" : [],
"identifier" : "{{identifier}}",
"job_title" : "{{job_title_staff}}",
"primary_email" : "{{primary_email}}",
"primary_phone_number" : "{{primary_phone_number}}",
"send_invitation" : "{{send_invitation}}"
}
sys-api/entity-memberships/update POST
This call updates a user's information. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"entity_user_xref_uuids": "{{entity_user_xref_uuid_sam_brown}}",
"enum_profile_id" : "{{enum_profile_id_staff_administrator}}",
"identifier" : "{{identifier}}",
"job_title" : "{{job_title_tochange}}",
"primary_email" : "{{primary_email_tochange}}",
"primary_phone_number" : "{{primary_phone_number_tochange}}"
}
sys-api/entity-memberships/invitations/resend POST
This call resends a user invitation. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Note: This is only possible if a user is pending
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"entity_user_xref_uuids": "{{entity_user_xref_uuid}}"
}
sys-api/entity-memberships/phone-numbers/update POST
This call updates a user's phone number. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"entity_user_xref_uuids": "{{entity_user_xref_uuid}}",
"phone_numbers" : [{"phone_number": "{{phone_number}}", "primary": true}]
}
sys-api/entity-memberships/emails/update POST
This call updates a user's email address. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"entity_user_xref_uuids": "{{entity_user_xref_uuid}}",
"emails" : [{"email": "{{email}}", "primary": true}]
}
sys-api/entity-memberships/profile/update POST
This call updates a user's profile name. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"entity_user_xref_uuids": "{{entity_user_xref_uuid}}",
"first_name" : "{{first_name_tochange}}",
"last_name" : "{{last_name_tochange}}"
}
sys-api/entity-memberships/destroy POST
This call removes a user from your organisation. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"entity_user_xref_uuids": "{{entity_user_xref_uuid}}"
}
sys-api/entity-memberships/restore POST
This call restores a user to your organisation. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Note: You have the option to restore a user with or without their original data. Also, a client user must be restored into at least one group.
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"entity_user_xref_uuids": "{{entity_user_xref_uuid}}"
"group_uuids": [],
"restore_data": "{{restore_data_pending_user}}"
}
sys-api/entity-memberships/list GET
This call retrieves a list of the users to your organisation, depending on the "entity_user_xref_status_type" (2: suspended, 1: active, 0: pending, -1: cancelled and -2: removed) and "entity_user_xref_type" (1: staff, 2. clients and 3: all). For error codes click here.
Permissions: "This key can perform read-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"entity_user_xref_status_type": "{{entity_user_xref_status_type}}",
"entity_user_xref_type": "{{entity_user_xref_type}}"
}
sys-api/entity-memberships GET
This call retrieves a users from your organisation's entity information. For error codes click here.
Permissions: "This key can perform read-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"entity_user_xref_uuids": "{{entity_user_xref_uuid}}"
}
sys-api/entity-memberships/group-memberships/list GET
This call retrieves a list of users entity memberships from your organisation. For error codes click here.
Permissions: "This key can perform read-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"only_active": false,
"entity_user_xref_uuids": "{{entity_user_xref_uuid}}"
}
entity-service/sys-api/export/entities GET
Exports entity memberships that were created or updated on the given date. For error codes click here.
Permissions: "This key can perform read-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"date": "date"(optional)
}
sys-api/groups/create POST
This creates a group in an organisation. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"identifier": "{{group_identifier}}",
"name": "{{group_name}}"
}
sys-api/groups/update POST
This API updates a contact group's name in an organisation. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"group_uuid": "{{group_uuid}}",
"identifier": "{{group_identifier}}",
"name": "{{group_name}}"
}
sys-api/groups/group-members/create POST
This API adds members to a contact group in an organisation. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"group_uuid": "{{group_uuid}}",
"entity_user_xref_uuids" : ["{{entity_user_xref_uuid_sam_brown}}"]
}
sys-api/groups/group-members/destroy POST
This API removes members from a contact group in an organisation. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"group_member_uuid": "{{group_member_uuid}}"
}
sys-api/groups/destroy POST
This API deletes a contact group in an organisation. For error codes click here.
Permissions: "This key can perform write-only admin actions"
Note: Clients cannot be left without a contact group.
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"group_uuid": "{{group_uuid}}"
}
sys-api/groups GET
This API returns entity information about a contact group in an organisation. For error codes click here.
Permissions: "This key can perform read-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"group_uuid": "{{group_uuid}}"
}
sys-api/groups/list GET
This API returns entity information about all contact groups in an organisation depending on status (1: Active, 2: Inactive and 3: All groups). For error codes click here.
Permissions: "This key can perform read-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"group_status_type": "{{group_status_type}}"
}
sys-api/groups/group-members/list GET
This API returns entity information about all members of a contact group in an organisation. For error codes click here.
Permissions: "This key can perform read-only admin actions"
Headers
X-SYS-API-KEY-SECRET:{{X-SYS-API-KEY-SECRET}}
X-SYS-API-KEY:{{X-SYS-API-KEY}}
Content-Type:application/json
Body
{
"group_uuid": "{{group_uuid}}"
}