Skip to content
Documentation
English
Explore guides

For administrators

Employees

List, create, show, and update employees in the company.

Contents

Before you start

Send Accept: application/json and Authorization: Bearer YOUR_TOKEN to https://{subdomain}.talentohq.com. See API for authentication.

Path and query identifiers are UUID strings.

Successful responses use 200. Validation failures use 422. Missing or invalid tokens, and records that cannot be found, use 401.

List all employees

GET /api/v3/employees

Returns employees the token can access. The query parameters below are optional.

Parameter Type Description
employee_id string (UUID) Employee id.
team_id string (UUID) Team id.
office_id string (UUID) Office id.
name string Match employee name, employee email, team name, or office name.
archived boolean When true, return archived employees. When absent or 0, active employees only.

Response 200 

[
  {
    "id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
    "name": "Employee name",
    "email": "employee@name.com",
    "avatar": "https://hr.talentohq.com/avatar.svg",
    "team": {
      "id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
      "name": "Team Talento",
      "total_employees": 6
    },
    "office": {
      "id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
      "name": "Office Talento",
      "total_employees": 8,
      "company_id": 12,
      "company_name": "Company name"
    },
    "legal_id": "F123456789",
    "social_security_id": "987654321SC",
    "geolocation_enabled": true,
    "started_on": "2023-07-06",
    "status": "Active"
  },
  {
    "id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
    "name": "Employee name2",
    "email": "employee2@name.com",
    "avatar": "https://hr.talentohq.com/avatar.svg",
    "team": {
      "id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
      "name": "Team Talento",
      "total_employees": 6
    },
    "office": {
      "id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
      "name": "Office Talento",
      "total_employees": 8,
      "company_id": 12,
      "company_name": "Company name"
    },
    "legal_id": "F123456789",
    "social_security_id": "987654321SC",
    "geolocation_enabled": true,
    "started_on": "2023-07-06",
    "status": "Active"
  }
]

Create an employee

POST /api/v3/employees

Creates a new active employee.

Request

{
  "name": "new employee",
  "email": "example@example.com",
  "team_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "office_id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
  "started_on": "2021-03-18",
  "push_key": null
}

Response 200 

{
  "id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "name": "new employee",
  "email": "example@example.com",
  "avatar": "https://hr.talentohq.com/avatar.svg",
  "team": {
    "id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
    "name": "Team Talento",
    "total_employees": 6
  },
  "office": {
    "id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
    "name": "Office Talento",
    "total_employees": 8,
    "company_id": 12,
    "company_name": "Company name"
  },
  "legal_id": "F123456789",
  "social_security_id": "987654321SC",
  "geolocation_enabled": false,
  "started_on": "2021-03-18",
  "status": "Active"
}

Show an employee

GET /api/v3/employees/{employee_id}

Parameter Type Description
employee_id string (UUID) Employee id.

Response 200 

{
  "id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "name": "Employee name",
  "email": "employee@name.com",
  "avatar": "https://hr.talentohq.com/avatar.svg",
  "team": {
    "id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
    "name": "Team Talento",
    "total_employees": 6
  },
  "office": {
    "id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
    "name": "Office Talento",
    "total_employees": 8,
    "company_id": 12,
    "company_name": "Company name"
  },
  "legal_id": "F123456789",
  "social_security_id": "987654321SC",
  "geolocation_enabled": true,
  "started_on": "2023-07-06",
  "status": "Active"
}

Update an employee

PUT /api/v3/employees/{employee_id}

Request

{
  "name": "updated employee",
  "email": "updated@example.com",
  "team_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "office_id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
  "push_key": null,
  "started_on": "2022-04-18"
}

Response 200 

{
  "id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "name": "updated employee",
  "email": "updated@example.com",
  "avatar": "https://hr.talentohq.com/avatar.svg",
  "team": {
    "id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
    "name": "Team Talento",
    "total_employees": 6
  },
  "office": {
    "id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
    "name": "Office Talento",
    "total_employees": 8,
    "company_id": 12,
    "company_name": "Company name"
  },
  "legal_id": "F123456789",
  "social_security_id": "987654321SC",
  "geolocation_enabled": true,
  "started_on": "2023-07-06",
  "status": "Active"
}