curl --request GET \
--url https://{subdomain}.conveyour.com/api/roles \
--header 'x-conveyour-token: <api-key>'const options = {method: 'GET', headers: {'x-conveyour-token': '<api-key>'}};
fetch('https://{subdomain}.conveyour.com/api/roles', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {method: 'GET', headers: {'x-conveyour-token': '<api-key>'}};
fetch('https://{subdomain}.conveyour.com/api/roles', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{subdomain}.conveyour.com/api/roles"
headers = {"x-conveyour-token": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{subdomain}.conveyour.com/api/roles",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-conveyour-token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"status": "ok",
"message": "6 Roles found",
"data": [
{
"id": "system_team_lead",
"slug": "team_lead",
"name": "Team Lead",
"description": "Oversees a team of contacts, engages via conversations, and views reports.",
"permissions": [
"contacts",
"add_contacts",
"conversations",
"reports",
"tags",
"proposals",
"boards",
"read_users"
],
"type": "system",
"is_editable": false
},
{
"id": "64a1b2c3d4e5f6a7b8c9d0e1",
"name": "Regional Manager",
"slug": "regional_manager",
"description": "Manages contacts and reports for a region.",
"permissions": [
"contacts",
"add_contacts",
"reports"
],
"type": "custom",
"is_editable": true
}
]
}{
"status": "failed",
"message": "Lacking necessary permission add_contacts",
"data": {
"permission": "add_contacts"
}
}List roles
Returns all roles for the org — the built-in system roles followed by the org’s custom roles.
List all roles (system + custom)
Permission: Org admin, or a user with update_users. Denials read View Roles.
Not callable with an API key. Requires an org admin or the update_users permission. Service accounts can be neither (update_users is denied to them and they cannot be admin), so every API key gets 403.
curl --request GET \
--url https://{subdomain}.conveyour.com/api/roles \
--header 'x-conveyour-token: <api-key>'const options = {method: 'GET', headers: {'x-conveyour-token': '<api-key>'}};
fetch('https://{subdomain}.conveyour.com/api/roles', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {method: 'GET', headers: {'x-conveyour-token': '<api-key>'}};
fetch('https://{subdomain}.conveyour.com/api/roles', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{subdomain}.conveyour.com/api/roles"
headers = {"x-conveyour-token": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{subdomain}.conveyour.com/api/roles",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-conveyour-token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"status": "ok",
"message": "6 Roles found",
"data": [
{
"id": "system_team_lead",
"slug": "team_lead",
"name": "Team Lead",
"description": "Oversees a team of contacts, engages via conversations, and views reports.",
"permissions": [
"contacts",
"add_contacts",
"conversations",
"reports",
"tags",
"proposals",
"boards",
"read_users"
],
"type": "system",
"is_editable": false
},
{
"id": "64a1b2c3d4e5f6a7b8c9d0e1",
"name": "Regional Manager",
"slug": "regional_manager",
"description": "Manages contacts and reports for a region.",
"permissions": [
"contacts",
"add_contacts",
"reports"
],
"type": "custom",
"is_editable": true
}
]
}{
"status": "failed",
"message": "Lacking necessary permission add_contacts",
"data": {
"permission": "add_contacts"
}
}Authorizations
Your API key token. Contacts endpoints require a Server-only — Full API key — see Authentication.
Query Parameters
Team scope for the request, as one or more team ObjectIds. The brackets are required: PHP keeps only the last value for a repeated plain key, so teams=A&teams=B silently resolves to B alone. On requests with a JSON body you may send teams (no brackets) in the body instead.
Values that are not valid ObjectIds are silently ignored — a mistyped team ID behaves as if no team was sent. See the teams section of the API conventions guide.
Response
Success.
The common response envelope shared by all ConveYour endpoints.
ok on success, failed on error.
ok, failed Human-readable description of the result.
The array merges the built-in system roles with the org's custom roles, so it holds BOTH shapes. Branch on type.
A built-in role from a template. It is NOT a stored record — it has no org_id, source_template, created_at or updated_at.
- Option 1
- Option 2
Show child attributes
Show child attributes