Skip to content
Documentation
English
Explore guides

For administrators

Companies

List, create, show, update, and delete companies in the account.

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 companies

GET /api/v3/companies

Results are paginated. Pass page to move through pages of 50 records.

Response 200 

[
  {
    "id": "55129d78-0281-4e72-aca1-8d547a2df814",
    "manager_id": null,
    "language_id": "7959a043-0eb1-45f5-8da9-0a5b4aea6404",
    "language_name": "Spanish",
    "name": "Company name",
    "slug": null,
    "legal_name": null,
    "vat_number": null,
    "timezone": null,
    "currency": "eur",
    "country_code": null,
    "state_code": null,
    "date_format": 0,
    "annual_leave_days": 24
  },
  {
    "id": "7b25791b-6e76-4bea-a821-46efde3869b3",
    "manager_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
    "manager_name": "Employee name",
    "language_id": "e3a6bfcb-aaf8-4086-b9dd-290e967c9d49",
    "language_name": "English",
    "name": "Other company",
    "slug": "Other-company",
    "legal_name": "Company.SL",
    "vat_number": 271263712,
    "timezone": "Paris",
    "currency": "eur",
    "country_code": "es",
    "state_code": null,
    "date_format": 0,
    "annual_leave_days": 24
  }
]

Create a company

POST /api/v3/companies

Request

{
  "name": "new company name",
  "timezone": "Paris",
  "currency": "eur",
  "country_code": "es",
  "state_code": null,
  "annual_leave_days": 32,
  "date_format": 0,
  "id_legal": null,
  "legal_name": "new company legal name",
  "language_id": "e3a6bfcb-aaf8-4086-b9dd-290e967c9d49",
  "manager_id": "c4a9bfcb-aaf8-4086-b9dd-340e967c9d49"
}

Response 200 

{
  "id": "7b25791b-6e76-4bea-a821-46efde3869b3",
  "manager_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "manager_name": "Employee name",
  "language_id": "e3a6bfcb-aaf8-4086-b9dd-290e967c9d49",
  "language_name": "English",
  "name": "new company name",
  "slug": "Other-company",
  "legal_name": "new company legal name",
  "vat_number": 271263712,
  "timezone": "Paris",
  "currency": "eur",
  "country_code": "es",
  "state_code": null,
  "date_format": 0,
  "annual_leave_days": 32
}

Show a company

GET /api/v3/companies/{company_id}

Parameter Type Description
company_id string (UUID) Company id.

Response 200 

{
  "id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "manager_id": null,
  "language_id": "7959a043-0eb1-45f5-8da9-0a5b4aea6404",
  "language_name": "Spanish",
  "name": "Company name",
  "slug": null,
  "legal_name": null,
  "vat_number": null,
  "timezone": null,
  "currency": "eur",
  "country_code": null,
  "state_code": null,
  "date_format": 0,
  "annual_leave_days": 24
}

Update a company

PUT /api/v3/companies/{company_id}

Request

{
  "name": "updated company name",
  "timezone": "London",
  "language_id": "7959a043-0eb1-45f5-8da9-0a5b4aea6404",
  "manager_id": "7959a043-0eb1-45f5-8da9-0a5b4aea6404"
}

Response 200 

{
  "id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "manager_id": "7959a043-0eb1-45f5-8da9-0a5b4aea6404",
  "language_id": "7959a043-0eb1-45f5-8da9-0a5b4aea6404",
  "language_name": "Spanish",
  "name": "updated company name",
  "slug": null,
  "legal_name": null,
  "vat_number": null,
  "timezone": "London",
  "currency": "eur",
  "country_code": null,
  "state_code": null,
  "date_format": 0,
  "annual_leave_days": 24,
  "manager_name": "Employee name"
}

Delete a company

DELETE /api/v3/companies/{company_id}

Response 200 

{}