Skip to content
Documentation
English
Explore guides

For administrators

Customers

List, create, show, update, and delete customers, and change customer stage.

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 customers

GET /api/v3/customers

Parameter Type Description
name string Optional name filter.
has_open_opportunities boolean Optional open-opportunity filter.
customer_category_id string (UUID) Optional customer category id.
customer_stage_category_id string (UUID) Optional customer stage category id.

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

Response 200 

[
  {
    "id": "55129d78-0281-4e72-aca1-8d547a2df814",
    "name": "Acme",
    "legal_name": "Acme SL",
    "id_legal": "B12345678",
    "email": "billing@acme.test",
    "country_code": "es",
    "number": "C-100",
    "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
    "employee_name": "Employee name",
    "customer_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
    "customer_category_name": "Enterprise",
    "customer_stage_category_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
    "customer_stage_category_name": "Active"
  }
]

Create a customer

POST /api/v3/customers

Request

{
  "name": "Acme",
  "legal_name": "Acme SL",
  "id_legal": "B12345678",
  "email": "billing@acme.test",
  "country_code": "es",
  "number": "C-100",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "customer_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58"
}

Response 200 

{
  "id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "name": "Acme",
  "legal_name": "Acme SL",
  "id_legal": "B12345678",
  "email": "billing@acme.test",
  "country_code": "es",
  "number": "C-100",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "customer_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "customer_category_name": "Enterprise",
  "customer_stage_category_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "customer_stage_category_name": "Active"
}

Show a customer

GET /api/v3/customers/{customer_id}

Parameter Type Description
customer_id string (UUID) Customer id.

Response 200 

{
  "id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "name": "Acme",
  "legal_name": "Acme SL",
  "id_legal": "B12345678",
  "email": "billing@acme.test",
  "country_code": "es",
  "number": "C-100",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "customer_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "customer_category_name": "Enterprise",
  "customer_stage_category_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "customer_stage_category_name": "Active"
}

Update a customer

PUT /api/v3/customers/{customer_id}

Request

{
  "name": "Acme updated",
  "email": "billing@acme.test",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "customer_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58"
}

Response 200 

{
  "id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "name": "Acme updated",
  "legal_name": "Acme SL",
  "id_legal": "B12345678",
  "email": "billing@acme.test",
  "country_code": "es",
  "number": "C-100",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "customer_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "customer_category_name": "Enterprise",
  "customer_stage_category_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "customer_stage_category_name": "Active"
}

Delete a customer

DELETE /api/v3/customers/{customer_id}

Response 200 

{}

Change customer stage

POST /api/v3/customers/{customer_id}/stage

Parameter Type Description
customer_id string (UUID) Customer id.

Request

{
  "customer_stage_category_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "note": "Moved after onboarding"
}

Response 200 

{
  "id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "name": "Acme",
  "legal_name": "Acme SL",
  "id_legal": "B12345678",
  "email": "billing@acme.test",
  "country_code": "es",
  "number": "C-100",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "customer_category_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "customer_category_name": "Enterprise",
  "customer_stage_category_id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
  "customer_stage_category_name": "Active"
}