Roles endpoints

The Roles endpoint enable you to list, create, update and delete roles in your Gtmhub account.

🔗
get
/roles
Gets all roles in the account.
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
fieldsstringList of fields to be retrieved, separated by comas (,).
expected in query, sample value:
name,description
sortstringList of fields separated by comas (,). To invert a field's sort, you can prefix its name with a minus (-). For example, the following expression: sort=-name,dateCreated would return entities in reverse lexicographical order and then ordered by dateCreated.
expected in query, sample value:
-name,dateCreated
filterstringThe format of the parameter is inspired by the MongoDB query format. For example, the following expression {name: {$in: ["sales", "marketing"]}} would return all the entities that have name either "sales" or "marketing". This expression {"name":{$regex:".*Sales.*"}} would return entities that contain "Sales" in their names.
expected in query, sample value:
{name: {$in: ["sales", "marketing"]}}
skipintegerHow many entities to be skipped when executing a GET query. By default skip value is 0.
expected in query, sample value:
5
limitintegerThe max number of entities that can be returned by the GET query. By default take value is 100.
expected in query, sample value:
10
formattingstringThe formatting used for the description and custom fields of type text area. By default returned as 'mentionsMarkup'. Ex: "@[John Smith:[email protected]:602a65efc05575000123291b]". Use 'plainText' if you need the response to be returned without markdown and special markup. Ex: "@John Smith"
expected in query, sample value:
plainText
Expected response codes
200rolesV2Response
401unauthorized

curl -X GET 'https://app.gtmhub.com/api/v2/roles?fields=name,description&sort=-name,dateCreated&filter={name: {$in: ["sales", "marketing"]}}&skip=5&limit=10&formatting=plainText' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {token}' \
-H 'gtmhub-accountId: 5be26318e5274a0007f17f61' \

var settings = { "url": "https://app.gtmhub.com/api/v2/roles?fields=name,description&sort=-name,dateCreated&filter={name: {$in: ["sales", "marketing"]}}&skip=5&limit=10&formatting=plainText", "method": "GET", "timeout": 0, "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer {token}",
"gtmhub-accountId": "5be26318e5274a0007f17f61",
}
}; $.ajax(settings).done(function (response) { console.log(response); });
 NOTE: You must install the module requests.
In a terminal window do: pip install requests



import requests, json

headers = { "Authorization" : "Bearer {token}", "gtmhub-accountId" : "{accountId}", "Content-Type" : "application/json" };

url = "https://app.gtmhub.com/api/v2/roles"



requests.get(url, headers = headers)
{
    "items": [
        {
            "accountId": "string value",
            "description": "string value",
            "id": "string value",
            "name": "string value",
            "userCount": 2
        }
    ],
    "totalCount": 2
}
🔗
get
/roles/account/mapping/
Get all mapped roles for an account
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
Expected response codes
201roleResponse
401unauthorized


 NOTE: You must install the module requests.
In a terminal window do: pip install requests

{
    "accountId": "string value",
    "description": "string value",
    "id": "string value",
    "name": "string value",
    "teamId": "string value",
    "userCount": 2
}
🔗
get
/roles/{id}
Gets the role with the specified id.
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
id
*
stringSpecifies the role ID.
expected in path, sample value:
5be26318e5274a0007f17f61
Expected response codes
200roleResponse
401unauthorized

curl -X GET 'https://app.gtmhub.com/api/v1/roles/{id}' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {token}' \
-H 'gtmhub-accountId: 5be26318e5274a0007f17f61' \

var settings = { "url": "https://app.gtmhub.com/api/v1/roles/{id}", "method": "GET", "timeout": 0, "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer {token}",
"gtmhub-accountId": "5be26318e5274a0007f17f61",
}
}; $.ajax(settings).done(function (response) { console.log(response); });
 NOTE: You must install the module requests.
In a terminal window do: pip install requests



import requests, json

headers = { "Authorization" : "Bearer {token}", "gtmhub-accountId" : "{accountId}", "Content-Type" : "application/json" };

url = "https://app.gtmhub.com/api/v1/roles/{id}"



requests.get(url, headers = headers)
{
    "accountId": "string value",
    "description": "string value",
    "id": "string value",
    "name": "string value",
    "teamId": "string value",
    "userCount": 2
}
🔗
post
/roles/account
Creates a new account specific role in the system.
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
Expected response codes
201roleResponse
401unauthorized

curl -X POST 'https://app.gtmhub.com/api/v1/roles/account' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer {token}' \
-H 'gtmhub-accountId: 5be26318e5274a0007f17f61' \

var settings = { "url": "https://app.gtmhub.com/api/v1/roles/account", "method": "POST", "timeout": 0, "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer {token}",
"gtmhub-accountId": "5be26318e5274a0007f17f61",
}
}; $.ajax(settings).done(function (response) { console.log(response); });
 NOTE: You must install the module requests.
In a terminal window do: pip install requests



import requests, json

headers = { "Authorization" : "Bearer {token}", "gtmhub-accountId" : "{accountId}", "Content-Type" : "application/json" };

url = "https://app.gtmhub.com/api/v1/roles/account"



requests.post(url, headers = headers)
{
    "accountId": "string value",
    "description": "string value",
    "id": "string value",
    "name": "string value",
    "teamId": "string value",
    "userCount": 2
}
🔗
post
/roles/account/mapping
Creates a new roles mappings.
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
Expected response codes
201roleResponse
401unauthorized


 NOTE: You must install the module requests.
In a terminal window do: pip install requests

{
    "accountId": "string value",
    "description": "string value",
    "id": "string value",
    "name": "string value",
    "teamId": "string value",
    "userCount": 2
}
🔗
put
/roles/account/{id}
Updates the role by id.
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
id
*
stringSpecifies the role ID.
expected in path, sample value:
5be26318e5274a0007f17f61
Expected response codes
200roleResponse
401unauthorized


 NOTE: You must install the module requests.
In a terminal window do: pip install requests

{
    "accountId": "string value",
    "description": "string value",
    "id": "string value",
    "name": "string value",
    "teamId": "string value",
    "userCount": 2
}
🔗
delete
/roles/account/mapping/{id}
Delete a role mapping for an account
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
Expected response codes
204no content
401unauthorized


 NOTE: You must install the module requests.
In a terminal window do: pip install requests

🔗
delete
/roles/account/{id}
Deletes the specified account specific role.
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the ID of the gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
id
*
stringSpecifies the role ID.
expected in path, sample value:
5be26318e5274a0007f17f61
Expected response codes
204no content
401unauthorized


 NOTE: You must install the module requests.
In a terminal window do: pip install requests