---
updatedAt: 2026-04-24T14:37:19.000Z
agentTools:
projectIndex: https://docs.talkdesk.com/llms.txt
---
# Search staffs by conditions
Search staffs by conditions
## Scope
`staffs-directory:read`
# OpenAPI definition
```json
{
"openapi": "3.0.2",
"info": {
"title": "Public API",
"version": "5.12.66",
"description": "Documents public API endpoints. Scopes are given to external software, that we don't control",
"contact": {
"name": "Talkdesk",
"url": "https://talkdesk.com"
}
},
"servers": [
{
"url": "https://api.talkdeskapp.com",
"description": "United States (td-us-1)"
},
{
"url": "https://api.talkdeskapp.eu",
"description": "Europe (td-eu-1)"
},
{
"url": "https://api.talkdeskappca.com",
"description": "Canada (td-ca-1)"
},
{
"url": "https://api.talkdeskapp.co.uk",
"description": "United Kingdom (td-uk-1)"
}
],
"tags": [
{
"name": "Locations Directory",
"description": "API responsible to manage Location data for industry related products (ex. store locations)"
}
],
"paths": {
"/locations-directory/staffs": {
"get": {
"operationId": "getStaffs",
"tags": [
"Locations Directory"
],
"summary": "Search staffs by conditions",
"description": "Search staffs by conditions",
"security": [
{
"GA": [
"staffs-directory:read"
]
}
],
"parameters": [
{
"name": "page",
"in": "query",
"description": "Desired page",
"required": false,
"example": 1,
"schema": {
"format": "int32",
"type": "integer",
"default": 1,
"minimum": 1,
"maximum": 2147483647
}
},
{
"name": "per_page",
"in": "query",
"description": "Limit the number of prompts per page",
"required": false,
"example": 50,
"schema": {
"format": "int32",
"default": 50,
"minimum": 1,
"maximum": 50,
"type": "integer"
}
},
{
"name": "name",
"in": "query",
"description": "Name of staff",
"required": false,
"example": "Marry",
"schema": {
"default": "",
"minLength": 0,
"maxLength": 9999,
"type": "string"
}
},
{
"name": "searchTerm",
"in": "query",
"description": "Search term to filter staffs by name or email.",
"required": false,
"example": "Mary",
"schema": {
"default": "",
"minLength": 0,
"maxLength": 512,
"type": "string"
}
},
{
"name": "manager",
"in": "query",
"description": "Manager of staff",
"required": false,
"example": "Maike",
"schema": {
"default": "",
"minLength": 0,
"maxLength": 9999,
"type": "string"
}
},
{
"name": "speciality",
"in": "query",
"description": "Speciality of staff",
"required": false,
"example": "cardiology",
"schema": {
"default": "",
"minLength": 0,
"maxLength": 9999,
"type": "string"
}
},
{
"name": "job_title",
"in": "query",
"description": "Job title of staff",
"required": false,
"example": "Manager",
"schema": {
"default": "",
"minLength": 0,
"maxLength": 9999,
"type": "string"
}
},
{
"name": "external_id",
"in": "query",
"description": "External id of staff",
"required": false,
"example": 1,
"schema": {
"default": "",
"minLength": 0,
"maxLength": 9999,
"type": "string"
}
},
{
"name": "industry",
"in": "query",
"description": "Industry of staff",
"required": false,
"example": "Retail",
"schema": {
"default": "",
"minLength": 0,
"maxLength": 9999,
"type": "string"
}
},
{
"name": "gender",
"in": "query",
"description": "Gender of staff",
"required": false,
"example": "male",
"schema": {
"default": "",
"minLength": 0,
"maxLength": 9999,
"type": "string"
}
},
{
"name": "status",
"in": "query",
"description": "Status of staff",
"required": false,
"example": "Active",
"schema": {
"default": "",
"minLength": 0,
"maxLength": 9999,
"type": "string"
}
},
{
"name": "language",
"in": "query",
"description": "Language of staff",
"required": false,
"example": "English",
"schema": {
"default": "",
"minLength": 0,
"maxLength": 9999,
"type": "string"
}
},
{
"name": "visit_type",
"in": "query",
"description": "Visit type name of staff",
"required": false,
"example": "type",
"schema": {
"default": "",
"minLength": 0,
"maxLength": 9999,
"type": "string"
}
},
{
"name": "location_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "id",
"description": "The id of the location. Accepts multiple ids as a comma-separated list, in which case staff\nassociated with any of the given ids are returned.\n",
"default": "",
"minLength": 0,
"maxLength": 150
}
},
{
"name": "location_name",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "Store Avenida da Liberdade",
"description": "The name of the location which staff in",
"default": "",
"minLength": 0,
"maxLength": 150
}
},
{
"name": "location_type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "Store",
"description": "The type of the location which staff in",
"default": "",
"minLength": 0,
"maxLength": 150
}
},
{
"name": "zip_code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "1250-142",
"description": "The zip-code of the location which staff in",
"default": "",
"minLength": 0,
"maxLength": 20
}
},
{
"name": "city",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "Lisbon",
"description": "The city of the location which staff in",
"default": "",
"minLength": 0,
"maxLength": 100
}
},
{
"name": "country_name",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "Portugal",
"description": "The country name of location which staff in",
"default": "",
"minLength": 0,
"maxLength": 100
}
},
{
"name": "region_name",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "Lisbon",
"description": "The region name (country subdivision) of location which staff in",
"default": "",
"minLength": 0,
"maxLength": 100
}
},
{
"name": "service_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "id",
"description": "The id of the service. Accepts multiple ids as a comma-separated list, in which case staff\nassociated with any of the given ids are returned.\n",
"default": "",
"minLength": 0,
"maxLength": 150
}
},
{
"name": "service_name",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "service name",
"description": "The name of the service provided by staff",
"default": "",
"minLength": 0,
"maxLength": 9999
}
},
{
"name": "service_type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "service type",
"description": "The type of the service provided by staff",
"default": "",
"minLength": 0,
"maxLength": 9999
}
},
{
"name": "latitude",
"in": "query",
"required": false,
"schema": {
"type": "number",
"format": "double",
"example": 38.698943,
"description": " - Latitude and longitude are used together with distance. The search parameters include latitude and longitude to retrieve a list of all staffs within a certain radius.
- Legacy alternative to the
near_by.* parameters; cannot be combined with them. - Currently, these three parameters can only be used when the Feature Flag is enabled.
",
"minimum": -90,
"maximum": 90
}
},
{
"name": "longitude",
"in": "query",
"required": false,
"schema": {
"type": "number",
"format": "double",
"example": -9.18423,
"description": " - Latitude and longitude are used together with distance. The search parameters include latitude and longitude to retrieve a list of all staffs within a certain radius.
- Legacy alternative to the
near_by.* parameters; cannot be combined with them. - Currently, these three parameters can only be used when the Feature Flag is enabled.
",
"default": "",
"minimum": -180,
"maximum": 180
}
},
{
"name": "distance",
"in": "query",
"required": false,
"schema": {
"type": "number",
"format": "double",
"example": 10000,
"description": " - Latitude and longitude are used together with distance. The search parameters include latitude and longitude to retrieve a list of all staffs within a certain radius.
- Distance is measured in meters.
- If no distance is provided, the default distance configured in Industries-settings will be used.
- Legacy alternative to the
near_by.* parameters; cannot be combined with them. - Currently, these three parameters can only be used when the Feature Flag is enabled.
",
"minimum": 0
}
},
{
"name": "near_by.country",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "US",
"description": " - The ISO 3166-1 alpha-2 country code (e.g. 'US') of the
near_by.city or near_by.zip_code to resolve to a coordinate. - Required when
near_by.city or near_by.zip_code is provided; providing near_by.country on its own is not a valid filter. - Cannot be combined with
near_by.latitude/near_by.longitude, or with the legacy latitude/longitude/distance parameters.
",
"minLength": 2,
"maxLength": 2
}
},
{
"name": "near_by.city",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "Boston",
"description": " - The city to resolve (via Google Maps), together with
near_by.country, to a coordinate to retrieve a list of all staffs within a certain radius. - Mutually exclusive with
near_by.zip_code; provide exactly one of the two. - Requires
near_by.country to also be provided.
",
"default": "",
"minLength": 0,
"maxLength": 100
}
},
{
"name": "near_by.zip_code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "02108",
"description": " - The zip/postal code to resolve (via Google Maps), together with
near_by.country, to a coordinate to retrieve a list of all staffs within a certain radius. - Mutually exclusive with
near_by.city; provide exactly one of the two. - Requires
near_by.country to also be provided.
",
"default": "",
"minLength": 0,
"maxLength": 20
}
},
{
"name": "near_by.latitude",
"in": "query",
"required": false,
"schema": {
"type": "number",
"format": "double",
"example": 38.698943,
"description": " - Latitude of the coordinate to search near. Must be provided together with
near_by.longitude. - Cannot be combined with
near_by.country/near_by.city/near_by.zip_code, or with the legacy latitude/longitude/distance parameters.
",
"minimum": -90,
"maximum": 90
}
},
{
"name": "near_by.longitude",
"in": "query",
"required": false,
"schema": {
"type": "number",
"format": "double",
"example": -9.18423,
"description": " - Longitude of the coordinate to search near. Must be provided together with
near_by.latitude. - Cannot be combined with
near_by.country/near_by.city/near_by.zip_code, or with the legacy latitude/longitude/distance parameters.
",
"minimum": -180,
"maximum": 180
}
},
{
"name": "near_by.distance",
"in": "query",
"required": false,
"schema": {
"type": "number",
"format": "double",
"example": 10000,
"description": " - Distance is measured in meters.
- Requires either a
near_by.country + near_by.city/near_by.zip_code group, or a near_by.latitude/near_by.longitude pair, to also be present. - If no distance is provided, the default distance configured in Industries-settings will be used.
- Cannot be combined with the legacy
latitude/longitude/distance parameters.
",
"minimum": 0
}
},
{
"name": "order_by",
"in": "query",
"description": "Order by field, should be one of -> name, external_id, manager, speciality, job_title, date_of_hire, created_at, updated_at",
"required": false,
"example": "name",
"schema": {
"default": "name",
"minLength": 0,
"maxLength": 9999,
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"description": "Sort field, should be one of -> DESC, ASC",
"required": false,
"example": "DESC",
"schema": {
"default": "DESC",
"minLength": 0,
"maxLength": 9999,
"type": "string"
}
},
{
"name": "custom_field",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"example": "visit_category eq 'wellness' and has_parking eq 'true'",
"description": "Filters staffs by the values of their custom fields, using a structured query expression\nin the format `custom_field= eq ''`, combined with `and`/`or` and parentheses.\nOnly the `eq` operator is currently supported.\n\n- **A single comparison.**\n `?custom_field=visit_category eq 'wellness'`\n returns the staffs whose `visit_category` is `wellness`.\n- **`or` matches any of the given comparisons.**\n `?custom_field=visit_category eq 'wellness' or visit_category eq 'acute_sick'`\n returns the staffs whose `visit_category` is either `wellness` or `acute_sick`.\n- **`and` requires all of the given comparisons to match.**\n `?custom_field=visit_category eq 'wellness' and has_parking eq 'true'`\n returns only the staffs that are in the `wellness` category and have parking.\n- **Parentheses group comparisons and override the default precedence (`and` binds tighter than `or`).**\n `?custom_field=visit_category eq 'wellness' and (has_parking eq 'true' or has_parking eq 'false')`\n- **The parameter can be repeated (up to 50 times); repeated occurrences are combined with `and`.**\n `?custom_field=visit_category eq 'wellness'&custom_field=has_parking eq 'true'`\n is equivalent to `?custom_field=visit_category eq 'wellness' and has_parking eq 'true'`.\n\nField names are matched case-insensitively. String values must be enclosed in single quotes;\na literal single quote within a value is escaped by doubling it (`''`).\nValue matching is case-insensitive for regular text custom fields, but case-sensitive for\nsingle-select and multi-select custom fields (the value must match one of the field's\ndefined options exactly). Omitting the parameter leaves the results unfiltered.\n"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"_embedded",
"total"
],
"properties": {
"count": {
"type": "integer",
"format": "int32",
"description": "the number of results in the current page",
"minimum": 1,
"maximum": 2147483647,
"example": 40
},
"total": {
"type": "integer",
"format": "int32",
"description": "the total of results in the account",
"minimum": 1,
"maximum": 2147483647,
"example": 90
},
"page": {
"type": "integer",
"format": "int32",
"description": "the current page",
"minimum": 1,
"maximum": 2147483647,
"example": 2
},
"per_page": {
"type": "integer",
"format": "int32",
"description": "the number of results per page",
"minimum": 1,
"maximum": 50,
"example": 50
},
"total_pages": {
"type": "integer",
"format": "int32",
"description": "the number of the total of result pages",
"minimum": 1,
"maximum": 2147483647,
"example": 2
},
"_embedded": {
"type": "object",
"required": [
"staffs"
],
"properties": {
"staffs": {
"type": "array",
"description": "The list of staffs in the current page",
"items": {
"type": "object",
"required": [
"id",
"name",
"external_id"
],
"properties": {
"id": {
"type": "string",
"description": "The staff identifier",
"minLength": 1,
"maxLength": 9999,
"example": "d08d05cc-ac7a-11ed-afa1-0242ac120002"
},
"name": {
"type": "string",
"description": "The name of staff",
"minLength": 1,
"maxLength": 9999,
"example": "New Staff"
},
"description": {
"type": "string",
"description": "The description of staff",
"minLength": 1,
"maxLength": 9999,
"example": "I am a Doctor"
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"description": "The type of contact",
"minLength": 1,
"maxLength": 9999,
"example": "phone"
},
"value": {
"type": "string",
"description": "The value of contact",
"minLength": 1,
"maxLength": 9999,
"example": "123456"
},
"description": {
"type": "string",
"description": "The description of contact",
"minLength": 1,
"maxLength": 9999,
"example": "it is my phone"
}
}
},
"description": "Employee contact list"
},
"job_title": {
"type": "string",
"description": "Professional title (e.g. Mid Market Customer Success Manager)",
"minLength": 1,
"maxLength": 9999,
"example": "Success Manager"
},
"manager": {
"type": "string",
"description": "Name of direct manager",
"minLength": 1,
"maxLength": 9999,
"example": "Maike"
},
"pronouns": {
"type": "string",
"description": "Understand the employee pronouns (e.g. she/her, he/his)",
"minLength": 1,
"maxLength": 9999,
"example": "she"
},
"specialities": {
"type": "array",
"description": "The specialties of staff",
"items": {
"type": "string",
"description": "The specialty or areas of expertise (e.g., cardiology, pediatrics)",
"minLength": 1,
"maxLength": 9999,
"example": "cardiology"
}
},
"external_id": {
"type": "string",
"description": "The external id of staff, should be unique",
"minLength": 1,
"maxLength": 9999,
"example": "1"
},
"industry": {
"type": "string",
"description": "The industry of staff",
"minLength": 1,
"maxLength": 9999,
"example": "Doctor"
},
"photo_url": {
"type": "string",
"description": "The photo url of staff",
"minLength": 1,
"maxLength": 9999,
"example": "https://images/1.png"
},
"gender": {
"type": "string",
"description": "The gender of staff",
"minLength": 1,
"maxLength": 9999,
"example": "male"
},
"status": {
"type": "string",
"description": "The status of staff",
"minLength": 1,
"maxLength": 9999,
"example": "Active"
},
"date_of_birth": {
"type": "string",
"description": "The dateOfBirth of staff",
"minLength": 1,
"maxLength": 9999,
"example": "1987-01-23"
},
"date_of_hire": {
"type": "string",
"description": "The dateOfHire of staff",
"minLength": 1,
"maxLength": 9999,
"example": "2021-03-23"
},
"languages": {
"type": "array",
"description": "The languages of staff",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 9999,
"description": "The language of staff",
"example": "English"
}
},
"attributes": {
"type": "object",
"description": "The attributes of staff, attributes should be object, and key can be any value",
"example": {
"note": "note",
"experience": "6 year"
}
},
"relationships": {
"type": "array",
"description": "The relationship list of staff",
"items": {
"type": "object",
"description": "Item can only have location or service, if both has value, service should belong to location",
"properties": {
"location": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The id of location",
"minLength": 1,
"maxLength": 9999,
"example": "d06b0425-c9eb-d8a3-a7c0-ce14d96a651f"
},
"name": {
"type": "string",
"description": "The name of location",
"minLength": 1,
"maxLength": 9999,
"example": "location"
}
}
},
"service": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The id of service",
"minLength": 1,
"maxLength": 9999,
"example": "d06b0425-c9eb-d8a3-a7c0-ce14d96a651f"
},
"name": {
"type": "string",
"description": "The name of service",
"minLength": 1,
"maxLength": 9999,
"example": "service"
}
}
}
}
}
},
"visit_types": {
"type": "array",
"description": "The visit type list of staff",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The id of visit type, can be anything",
"minLength": 1,
"maxLength": 9999,
"example": "d06b0425-c9eb-d8a3-a7c0-ce14d96a651f"
},
"name": {
"type": "string",
"description": "The name of visit type, can be anything",
"minLength": 1,
"maxLength": 9999,
"example": "name"
}
}
}
},
"tags": {
"description": "Tag list",
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The id of tag",
"minLength": 1,
"maxLength": 9999,
"example": "d06b0425-c9eb-d8a3-a7c0-ce14d96a651f"
},
"value": {
"type": "string",
"description": "The value of tag",
"minLength": 1,
"maxLength": 9999,
"example": "VIP"
},
"color": {
"type": "string",
"description": "The color of tag",
"minLength": 1,
"maxLength": 9999,
"example": "#EFDBFF"
}
}
}
},
"custom_fields": {
"type": "array",
"description": "Custom field values for the staff member.",
"default": [],
"items": {
"type": "object",
"required": [
"custom_field_template_entry_id",
"name",
"field_type"
],
"properties": {
"id": {
"type": "string",
"description": "The identifier of the custom field value.",
"minLength": 1,
"maxLength": 9999,
"example": "d08d05cc-ac7a-11ed-afa1-0242ac120002"
},
"custom_field_template_entry_id": {
"type": "string",
"description": "The identifier of the custom field template entry this value belongs to.",
"minLength": 1,
"maxLength": 9999,
"example": "a78d05cc-ac7a-11ed-afa1-0242ac120012"
},
"name": {
"type": "string",
"description": "The name of the custom field.",
"minLength": 1,
"maxLength": 9999,
"example": "specialization"
},
"field_type": {
"type": "string",
"description": "The data type of the custom field.",
"minLength": 1,
"enum": [
"SHORT_TEXT",
"LONG_TEXT",
"NUMBER",
"DATE",
"BOOLEAN",
"SINGLE_SELECT",
"MULTI_SELECT"
],
"example": "SINGLE_SELECT"
},
"value": {
"type": "string",
"minLength": 0,
"maxLength": 9999,
"description": "The value of the custom field, always represented as a string regardless of its field_type. For MULTI_SELECT fields, multiple selected options are represented as a single pipe-delimited ('|') string, e.g. 'Wellness|Follow-up'.",
"example": "true"
}
}
}
}
}
}
}
}
},
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"type": "object",
"required": [
"href"
],
"properties": {
"href": {
"type": "string",
"format": "uri",
"minLength": 1,
"maxLength": 9999,
"example": "https://api-docs.talkdesk.org/"
}
}
}
}
}
}
},
"example": {
"_embedded": {
"staffs": [
{
"id": "d08d05cc-ac7a-11ed-afa1-0242ac120002",
"name": "Test-Staff",
"description": "I am a Doctor",
"job_title": "title",
"specialities": [
"IT support",
"Diagnostic specialist"
],
"pronouns": "she",
"manager": "manager",
"contacts": [
{
"type": "phone",
"value": "+123456789",
"description": "phone"
}
],
"external_id": "1",
"industry": "Doctor",
"photo_url": "https://images/1.png",
"gender": "male",
"status": "Active",
"date_of_birth": "1987-01-23",
"date_of_hire": "2021-03-23",
"languages": [
"English",
"Chinese"
],
"attributes": {
"note": "note",
"experience": "6 year"
},
"relationships": [
{
"location": {
"id": "1",
"name": "location 1"
},
"service": {
"id": "2",
"name": "service 1"
}
},
{
"location": {
"id": "3",
"name": "location 2"
}
},
{
"service": {
"id": "4",
"name": "service 2"
}
}
],
"visit_types": [
{
"id": "1",
"name": "name"
}
],
"tags": [
{
"id": "1",
"value": "VIP",
"color": "#EFDBFF"
},
{
"id": "2",
"value": "VVIP",
"color": "#EFDBFF"
}
],
"custom_fields": [
{
"id": "d13a4b7e-1c2d-4e9f-8a3b-5f6c7d8e9f01",
"custom_field_template_entry_id": "e58bae95-8be0-4fd8-ac05-3f41e85c85e3",
"name": "visit_category",
"field_type": "SHORT_TEXT",
"value": "wellness"
}
]
}
]
},
"count": 1,
"total": 2,
"page": 1,
"per_page": 1,
"total_pages": 2,
"_links": {
"self": {
"href": "http://api-docs.talkdesk.org/locations-directory/staffs?page=1&per_page=20"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"description": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"description"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"example": {
"code": "1484000",
"message": "Bad request."
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"description": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"description"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"example": {
"code": "1484010",
"message": "Invalid JWT token."
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"description": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"description"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"example": {
"code": "1484030",
"message": "Required scopes are missing."
}
}
}
},
"422": {
"description": "The given near_by.* location could not be resolved to a coordinate.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"description": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"description"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"example": {
"code": "40342212",
"message": "Could not resolve the given near_by location to a coordinate."
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"GA": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://{account_name}.talkdeskid.com/oauth/authorize",
"tokenUrl": "https://{account_name}.talkdeskid.com/oauth/token",
"scopes": {
"account:read": "Show account details",
"apps:read": "Get details about app installations for an account",
"apps:write": "Update an app installation state programatically",
"attributes:read": "List attributes or attribute categories for an account and get details for a specific attribute",
"attributes:write": "Create, update and remove attributes or attributes categories for an account",
"bulk-imports:read": "Get list of imports and export errors into CSV file",
"bulk-imports:write": "Create and update import data",
"messages:write": "Ability to send messages from the API",
"callback:write": "Request a new direct callback",
"contacts-integrations:read": "Get details for contacts' integrations",
"contacts:read": "Get details for contact(s)",
"contacts:write": "Create, update or delete contacts",
"contact-gdpr:write": "GDPR Contacts",
"continuity-settings:read": "Read business continuity settings",
"continuity-settings:write": "Change business continuity settings",
"continuity-settings-activation:read": "Read information on activation of the continuity settings",
"continuity-settings-activation:write": "Edit information on activation of the continuity settings",
"data-reports:read": "Download previously generated data reports",
"data-reports:write": "Create new data reports",
"data-tables:read": "Fetch and list data tables",
"data-tables:write": "Create and update data tables",
"data-tables-exports:read": "List and download data table exports",
"data-tables-exports:write": "Create and cancel data table exports",
"events:read": "Get details from received events",
"express-provisioning:read": "Express-provisioning validate if account exists",
"express-provisioning:write": "Provisioning of an account",
"express-accounts-usage:read": "Read usage information for an account",
"express-accounts:read": "Read account information",
"express-accounts-contracts:read": "Get contract info for express accounts",
"express-accounts-contracts-actions:write": "Create contract actions for express accounts",
"express-accounts-contracts-actions:read": "Read contract actions of express accounts",
"express-products:read": "Read product information",
"express-accounts-subscriptions:read": "Read subscription information for an account",
"express-accounts-invoices:read": "Read invoice information for an account",
"erc-ecommerce-shopify-webhooks-handler-credentials:write": "Create or update Shopify webhook handler credentials",
"erc-ecommerce-shopify-webhooks-handler-credentials:read": "Read Shopify webhook handler credentials",
"flows-interactions:start": "Starts an interaction associated with a flow",
"flows-platform:submit": "Trigger an automation flow associated with an account",
"fsi-accounts:read": "List of accounts associated with a contact",
"fsi-contacts:write": "Update contact information",
"fsi-contacts:read": "List and get contact details",
"fsi-cards:read": "List of cards from a account",
"fsi-cards:write": "Update the status for a card",
"fsi-payments:read": "List of payments from a specific account",
"fsi-transactions:read": "List of transactions for a specific account",
"fsi-payoff:read": "Get the payoff for an FSI account",
"fsi-transfers:write": "Create an FSI Transfer",
"fsi-stop-payment:write": "Cancel a payment before it’s been processed",
"fsi-travel-notification:write": "Create a new endpoint for Travel Notifications",
"fsi-checks:read": "Search for a check",
"fsi-set-ach-transfer:write": "FSI Set ACH Transfer",
"fsi-unlock-account:write": "Unlock account for a banking customer",
"fsi-decrypt:read": "The decryption based on AES algorithm",
"fsi-write-back:write": "FSI Write Data Back",
"fsi-spend-limit:read": "Daily limit for reading debit cards",
"fsi-spend-limit:write": "Modify the daily limit of debit cards",
"guardian-call-quality:read": "Read Guardian call quality data.",
"guardian-sessions:read": "Read Sessions Guardian data.",
"guardian-users:read": "Read Users Guardian data.",
"guardian-cases:read": "Read Cases Guardian data.",
"identity-activity:read": "Identity activity read access",
"identity-email-validation:read": "Identity Email Validation read access",
"identity-ip-validation:read": "Identity IP Validation read access",
"identity-phone-validation:read": "Identity Phone Validation read access",
"openid": "User info endpoint",
"recordings:read": "Get recording files",
"recordings:delete": "Delete recording files",
"refresh_token": "Token refresh flow",
"reports:read": "List previously generated reports and download them",
"reports:write": "Create new reports or delete existing ones",
"queues:read": "List CCAAS queues",
"queues:write": "Create/update CCAAS queues details",
"queues-users:read": "List users assigned to a CCAAS queue",
"users:read": "List users for an account and get details for a specific user",
"users:write": "Create, Update and Delete users",
"interactions:control-recordings": "Control the recording status of an interaction",
"fsi-workspace-contact-synchronization:write": "Synchronize Talkdesk contact with fsi member information",
"voicebiometrics-enroll:write": "Update and delete Voice Biometrics enroll data",
"voicebiometrics-consent:read": "VoiceBiometrics consent read access",
"voicebiometrics-consent:write": "VoiceBiometrics consent write access",
"live-queries:read": "Read and list queries from Live API",
"live-subscriptions:read": "Read subscriptions from Live API",
"live-subscriptions:write": "Create a new subscription for Live API",
"wfm-aion-public:write": "Create, Update and Delete WFM Aion related data by an external client.",
"wfm-request-management-public:write": "Create, Update and Delete WFM Request Management related data by an external client.",
"wfm-request-management-public:read": "Read WFM Request Management related data by an external client.",
"account-wallets:read": "Get information about account wallets",
"bucket-configurations:read": "Get all bucket configurations",
"cases-public:write": "Create,update and delete case data",
"cases-public:read": "Read case",
"case-notes-public:read": "Read case note data",
"case-notes-public:write": "Create, edit, and delete case note data",
"case-fields-public:read": "Read case field",
"do-not-call-lists:manage": "Update a DNCL by adding or deleting a entry on a do not call list",
"do-not-call-lists:read": "Read entries in a do not call list",
"record-lists:manage": "Ability to view, add and update records of a Record List",
"record-lists:write": "Create and update record lists for an account",
"role-permissions:skip": "Skip role permissions validation",
"campaigns:write": "Create, update and delete campaigns",
"campaigns:read": "List and view available campaigns",
"schedule-callbacks:read": "List schedule callbacks",
"schedule-callbacks:write": "schedule a callbacks or reschedule a callbacks",
"po-record-list-automations:write": "Custom record list automations for proactive outbound clients",
"prompts:read": "Read prompts",
"prompts:write": "Create a prompt",
"prompts:delete": "Delete a prompt",
"prompts:download": "Get prompt download link",
"webhooks-trigger:write": "Create, update and delete a webhook trigger",
"cfm-public:write": "Collect feedback data",
"digital-connect:read": "List and Get digital-connect Resources",
"digital-connect:write": "Create, Update and Delete digital-connect Resources",
"entitymapper-contact-interactions:write": "Update interaction's contact mappings",
"locations-directory:read": "Read locations information",
"locations-directory:write": "Write/update locations information and custom fields",
"locations-directory:support": "Create/Update/Delete locations-directory support features",
"staffs-directory:read": "Read staffs information",
"staffs-directory:write": "Write/update staffs information",
"automated-notifications-management:read": "Read Automated Notifications related account information",
"automated-notifications-management:write": "Write Automated Notifications related account information",
"automated-notifications:read": "Read Automated Notifications event information",
"automated-notifications:write": "Write Automated Notifications event information",
"automated-notifications-bridge:write": "Write permissions for automated-notifications-bridge webhooks",
"automated-notifications-subscriptions:read": "Read Automated Notifications subscriptions related to a topic/channel",
"automated-notifications-subscriptions:write": "Write (subscribe/unsubscribe) Automated Notifications subscriptions related to a topic/channel",
"entitymapper-map:write": "Write mappings with external entities",
"entitymapper-contacts:read": "Search Talkdesk contact",
"entitymapper-contacts:write": "Write Talkdesk contact",
"appointment-scheduling-va:read": "Read appointment scheduling va entries",
"hls-coverage:read": "Read healthcare & life sciences coverage information",
"hls-balance:read": "Read healthcare & life sciences balance information",
"hls-patient:read": "Read healthcare & life sciences patient information",
"hls-providers:call-answered": "Write healthcare & life sciences call answered information",
"hls-appointment:read": "Read healthcare & life sciences patient appointments",
"hls-medication-order:read": "Read healthcare & life sciences patient medication orders",
"hls-appointment:write": "Write healthcare & life sciences patient appointments",
"hls-contact:write": "Write healthcare & life sciences data into talkdesk contact",
"hls-provider:read": "Read healthcare & life sciences provider appointments",
"hls-phone-action:write": "Write healthcare & life sciences phone action",
"hls-click-to-call:write": "Write healthcare & life sciences click-to-call action",
"hls-epic-outgoing-sms:write": "Trigger outgoing SMS from Epic",
"hls-epic-agent-status-sync:write": "Trigger agent status sync from Epic",
"hls-inbasket-message:write": "Send in-basket message to Epic",
"hls-popup-intent:write": "Save intent of a patient",
"hls-prescription:read": "Read healthcare & life sciences prescription information",
"hls-prescription:write": "Write healthcare & life sciences prescription information",
"hls-encounter:read": "Read healthcare & life sciences patient encounters",
"hls-service-request:read": "Read healthcare & life sciences patient service requests",
"hls-procedure:read": "Read healthcare & life sciences patient procedures",
"hls-payers-connections:read": "Read healthcare & life sciences payers information",
"hls-payers-connections:write": "Write healthcare & life sciences payers information",
"hls-symptom-checker:write": "Symptom checker for patient",
"hls-patient:write": "Write healthcare & life sciences patient information",
"hls-epic:call-answered": "Write healthcare & life sciences call answered information",
"hls-sycurio:integrate": "Integrate with Sycurio platform",
"hls-patient-case:write": "Write healthcare & life sciences patient case information",
"hls-outstanding-order:read": "Read healthcare & life sciences outstanding orders",
"hls-medication-order:write": "Write healthcare & life sciences medication order(request)",
"hls-medication-statement:write": "Write healthcare & life sciences medication statement",
"hls-medication-statement:read": "Read healthcare & life sciences medication statement",
"hls-hl7-events:write": "Write healthcare providers HL7 events",
"erc-ecommerce-connections-orders:write": "Update e-commerce connections orders info",
"erc-ecommerce-connections-customers:read": "Read e-commerce connections customers info",
"erc-ecommerce-connections-customers:write": "Write e-commerce connections customers info",
"erc-ecommerce-connections-orders:read": "Read e-commerce connections orders info",
"erc-ecommerce-connections-products:read": "Read e-commerce connections products info",
"erc-ecommerce-customers:read": "Read e-commerce customers info",
"erc-ecommerce-customers:write": "Write e-commerce customers info",
"erc-ecommerce-return-reasons:read": "Read e-commerce return reasons",
"erc-ecommerce-return:read": "Read e-commerce return info",
"erc-ecommerce-return:write": "Write e-commerce return info",
"erc-ecommerce-cart:write": "Sync e-commerce cart items",
"erc-ecommerce-products:read": "Search e-commerce catalog products",
"erc-ecommerce-orders:read": "Show e-commerce integrations orders info",
"erc-ecommerce-orders:write": "Update e-commerce integrations orders info",
"erc-ecommerce-recall:write": "Write e-commerce recall contacts",
"industries-settings-public:write": "Write industries settings",
"industries-contexts:write": "Create, update, and delete context values",
"fsi-insurance-connections-automated-notifications:write": "Write Automated Notifications event information",
"fsi-insurance-connections-contacts:write": "Sync Talkdesk contacts",
"fsi-insurance-connections-claims:read": "Read claims by id from FSI Insurance",
"fsi-insurance-integrations-policies:read": "Read policies from FSI Insurance",
"fsi-insurance-integrations-accounts:read": "Read accounts from FSI Insurance",
"fsi-insurance-integrations-claims:write": "Write claims from FSI Insurance",
"fsi-insurance-integrations-billing:read": "Read billing info from FSI Insurance",
"fsi-insurance-integrations-claims:read": "Read claims from FSI Insurance",
"fsi-insurance-integrations-contacts:write": "Update contact details from FSI Insurance",
"fsi-insurance-integrations-send-docs:read": "Send document deliveries from FSI Insurance",
"fsi-insurance-integrations-data-back:write": "Write contact event data back to FSI Insurance",
"automated-notifications-interactions:read": "Read Automated Notifications related with interactions",
"industries-scheduler-teams:read": "Read teams from industries-scheduler",
"industries-scheduler-availabilities:read": "Get users availabilities by email",
"industries-scheduler-appointment:write": "Create cancel event on specialist's calendar",
"industries-scheduler-appointment:read": "Read appointments from industries-scheduler",
"industries-messaging-service:write": "Write messages in industries-messaging-service",
"interaction-custom-fields:write": "Allows to populate interaction custom fields",
"user-session-public:end": "Terminate a user session",
"industries-settings-public:read": "Read industries settings",
"industries-contexts:read": "Read context values",
"dialer-integrations-records:read": "Read dialer integrations campaign records",
"scim": "Access SCIM-related routes",
"hls-epic-my-chart-reset-password:write": "Trigger Epic MyChart password reset (Deprecated - use hls-patient-password-reset:write)",
"hls-patient-password-reset:write": "Trigger patient password reset for healthcare portal",
"locations-directory-bulk-operation:write": "Write locations directory data",
"locations-directory-batch-operation:write": "Apply a batch of locations directory create/update/delete operations",
"hls-patient-location:read": "Read loction patient data",
"hls-patient-practice:read": "Read healthcare & life sciences patient practices",
"hls-guarantor:read": "Read guarantor identifiers from providers",
"hls-guarantor-billing:read": "Read guarantor billing summary from providers",
"hls-guarantor-password-reset:write": "Trigger guarantor password reset for healthcare portal",
"hls-patient-billing:read": "Read patient billing details from providers",
"hls-interaction-overrides:write": "Write healthcare & life sciences interaction-specific configuration overrides",
"industries-workflows:read": "Read industries workflow schedules and workflows",
"industries-workflows:write": "Create, update, start, and delete industries workflow schedules and workflows",
"digital-messaging-adapter:write": "Write or update Digital Messaging Adapter data"
}
}
}
}
}
},
"externalDocs": {
"description": "External Documentation",
"url": "https://api-docs.talkdeskapp.com/external_docs"
}
}
```