Employees endpoints

The Employees endpoints enable you to retrieve a list of all Gtmhub employees or get the details of a single employee by their Id. The employee object extends the Gtmhub user object with additional information about any badges, team membership or teams the employee manages. The employee Id is equal to the User Id.

🔗
get
/employees
Returns a list of employees.
Supports filtering, sorting and field projection.
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the unique identifier (id) of the Gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
filterstringSpecifies the filter in Mongo syntax. For example, to get a single employee by their Id, use filter={"_id":"611fce386400780001b19e1e"}.
expected in query, sample value:
{"_id":"611fce386400780001b19e1e"}
sortstringSpecifies the sort expression. For example, to sort employees by their creation date user sort=dateCreated or sort=-dateCreated (to sort in descending order).
expected in query, sample value:
dateCreated
fieldsstringSpecifies the list of fields to be returned in the response. For example, to get only the employee's email, first and last name use fields=email,firstName,lastName
expected in query, sample value:
email,firstName,lastName
skipstringSpecifies how many items to skip from the beginning of the collection. Use this to implement paging. For example, if you want to get employees 5-10 use skip=5&take=5. Always sort your response to ensure that you're paging through the collection in the same order, for example sort=dateCreated&skip=5&take=5.
expected in query, sample value:
5
takestringSpecifies how many items to take from the collection. Use this to implement paging. For example, if you want to get the first 10 employees use take=10. Always sort your response to ensure that you're paging through the collection in the same order, for example sort=dateCreated&take=10.
expected in query, sample value:
10
Expected response codes
200employeesResponse
400bad request
401unauthorized
500internal server error

curl -X GET 'https://app.gtmhub.com/api/v2/employees?filter={"_id":"611fce386400780001b19e1e"}&sort=dateCreated&fields=email,firstName,lastName&skip=5&take=10' \ -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/employees?filter={"_id":"611fce386400780001b19e1e"}&sort=dateCreated&fields=email,firstName,lastName&skip=5&take=10", "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/employees"



requests.get(url, headers = headers)
{
    "items": [
        {
            "badges": [
                {
                    "background": "string value",
                    "icon": "string value",
                    "id": "string value",
                    "name": "string value",
                    "pattern": "string value"
                }
            ],
            "dateCreated": "string value",
            "email": "string value",
            "firstName": "string value",
            "id": "string value",
            "isActive": false,
            "isManager": false,
            "lastName": "string value",
            "managedTeamIds": [
                "string value 1",
                "string value 2"
            ],
            "picture": "string value",
            "roles": [
                {
                    "accountId": "string",
                    "description": "string value",
                    "id": "string",
                    "name": "string value",
                    "team": {
                        "ExternalTeamMapping": {
                            "ExternalId": "string value",
                            "ExternalSystem": "string value"
                        },
                        "accountId": "string",
                        "avatar": "string value",
                        "color": "string value",
                        "createdById": "string",
                        "dateCreated": "string value",
                        "description": "string value",
                        "id": "string",
                        "manager": "string",
                        "members": [
                            "string"
                        ],
                        "mentions": {},
                        "modifiedById": "string",
                        "movedExternalMembers": [
                            "string"
                        ],
                        "name": "string value",
                        "parentId": "string",
                        "picture": "string value",
                        "richTextDescription": "string value",
                        "tags": [
                            {
                                "id": "string",
                                "isActive": {
                                    "IsActive": false
                                },
                                "name": "string value",
                                "title": "string value"
                            }
                        ]
                    }
                }
            ],
            "teamIds": [
                "string value 1",
                "string value 2"
            ]
        }
    ],
    "totalCount": 2
}
🔗
get
/employees/{employeeId}
Gets an employee by its unique identifier (id).
Parameters
NameTypeDescription
gtmhub-accountId
*
stringSpecifies the unique identifier (id) of the Gtmhub account.
expected in header, sample value:
5be26318e5274a0007f17f61
employeeId
*
stringSpecifies the employee unique identifier (id).
expected in path
Expected response codes
200employeeDetailResponse
401unauthorized

curl -X GET 'https://app.gtmhub.com/api/v1/employees/{employeeId}' \ -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/employees/{employeeId}", "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/employees/{employeeId}"



requests.get(url, headers = headers)
{
    "info": {
        "badges": [
            {
                "background": "string value",
                "icon": "string value",
                "id": "string value",
                "name": "string value",
                "pattern": "string value"
            }
        ],
        "dateCreated": "string value",
        "email": "string value",
        "firstName": "string value",
        "id": "string value",
        "isActive": false,
        "isManager": false,
        "lastName": "string value",
        "managedTeamIds": [
            "string value 1",
            "string value 2"
        ],
        "picture": "string value",
        "roles": [
            {
                "accountId": "string",
                "description": "string value",
                "id": "string",
                "name": "string value",
                "team": {
                    "ExternalTeamMapping": {
                        "ExternalId": "string value",
                        "ExternalSystem": "string value"
                    },
                    "accountId": "string",
                    "avatar": "string value",
                    "color": "string value",
                    "createdById": "string",
                    "dateCreated": "string value",
                    "description": "string value",
                    "id": "string",
                    "manager": "string",
                    "members": [
                        "string"
                    ],
                    "mentions": {},
                    "modifiedById": "string",
                    "movedExternalMembers": [
                        "string"
                    ],
                    "name": "string value",
                    "parentId": "string",
                    "picture": "string value",
                    "richTextDescription": "string value",
                    "tags": [
                        {
                            "id": "string",
                            "isActive": {
                                "IsActive": false
                            },
                            "name": "string value",
                            "title": "string value"
                        }
                    ]
                }
            }
        ],
        "teamIds": [
            "string value 1",
            "string value 2"
        ]
    }
}