--- updatedAt: 2026-04-24T14:36:47.000Z agentTools: projectIndex: https://docs.talkdesk.com/llms.txt --- # Get the paginated list of locations Get the paginated list of locations ## Scope `locations-directory:read` # OpenAPI definition ```json { "openapi": "3.0.2", "info": { "title": "Public API", "version": "5.12.71", "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/locations": { "get": { "operationId": "getLocations", "tags": [ "Locations Directory" ], "summary": "Get the paginated list of locations", "description": "Get the paginated list of locations", "security": [ { "GA": [ "locations-directory:read" ] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "example": 5, "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "example": "Liberdade", "description": "Search location by location name or city", "default": "", "minLength": 0, "maxLength": 255 } }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string", "example": "external-location-001", "description": "The external_id of the location", "default": "", "minLength": 0, "maxLength": 9999 } }, { "name": "location_name", "in": "query", "required": false, "schema": { "type": "string", "example": "Store Avenida da Liberdade", "description": "The name of the location", "default": "", "minLength": 0, "maxLength": 150 } }, { "name": "alternative_name", "in": "query", "required": false, "schema": { "type": "string", "example": "Store ADL", "description": "The alternative name of the location", "default": "", "minLength": 0, "maxLength": 150 } }, { "name": "location_type", "in": "query", "required": false, "schema": { "type": "string", "example": "Store", "description": "The type of the location", "default": "", "minLength": 0, "maxLength": 150 } }, { "name": "address", "in": "query", "required": false, "schema": { "type": "string", "example": "Avenida da Liberdade, 10", "description": "The name of the address", "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", "default": "", "minLength": 0, "maxLength": 20 } }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string", "example": "Lisbon", "description": "The city of the location", "default": "", "minLength": 0, "maxLength": 100 } }, { "name": "country_name", "in": "query", "required": false, "schema": { "type": "string", "example": "Portugal", "description": "The country name", "default": "", "minLength": 0, "maxLength": 100 } }, { "name": "region_name", "in": "query", "required": false, "schema": { "type": "string", "example": "Lisbon", "description": "The region name (country subdivision)", "default": "", "minLength": 0, "maxLength": 100 } }, { "name": "latitude", "in": "query", "required": false, "schema": { "type": "number", "format": "double", "example": 38.698943, "description": " ", "minimum": -90, "maximum": 90 } }, { "name": "longitude", "in": "query", "required": false, "schema": { "type": "number", "format": "double", "example": -9.18423, "description": " ", "default": "", "minimum": -180, "maximum": 180 } }, { "name": "distance", "in": "query", "required": false, "schema": { "type": "number", "format": "double", "example": 10000, "description": " ", "minimum": 0 } }, { "name": "near_by.country", "in": "query", "required": false, "schema": { "type": "string", "example": "US", "description": " ", "minLength": 2, "maxLength": 2 } }, { "name": "near_by.city", "in": "query", "required": false, "schema": { "type": "string", "example": "Boston", "description": " ", "default": "", "minLength": 0, "maxLength": 100 } }, { "name": "near_by.zip_code", "in": "query", "required": false, "schema": { "type": "string", "example": "02108", "description": " ", "default": "", "minLength": 0, "maxLength": 20 } }, { "name": "near_by.latitude", "in": "query", "required": false, "schema": { "type": "number", "format": "double", "example": 38.698943, "description": " ", "minimum": -90, "maximum": 90 } }, { "name": "near_by.longitude", "in": "query", "required": false, "schema": { "type": "number", "format": "double", "example": -9.18423, "description": " ", "minimum": -180, "maximum": 180 } }, { "name": "near_by.distance", "in": "query", "required": false, "schema": { "type": "number", "format": "double", "example": 10000, "description": " ", "minimum": 0 } }, { "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 locations\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 location", "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 location", "default": "", "minLength": 0, "maxLength": 9999 } }, { "name": "staff_id", "in": "query", "required": false, "schema": { "type": "string", "example": "id", "description": "The id of the staff. Accepts multiple ids as a comma-separated list, in which case locations\nassociated with any of the given ids are returned.\n", "default": "", "minLength": 0, "maxLength": 150 } }, { "name": "staff_name", "in": "query", "required": false, "schema": { "type": "string", "example": "staff name", "description": "The name of the staff belongs to location", "default": "", "minLength": 0, "maxLength": 9999 } }, { "name": "staff_specialty", "in": "query", "required": false, "schema": { "type": "string", "example": "staff specialty", "description": "The specialty of the staff belongs to location", "default": "", "minLength": 0, "maxLength": 9999 } }, { "name": "staff_visit_type", "in": "query", "required": false, "schema": { "type": "string", "example": "type name", "description": "The visit type name of the staff belongs to location", "default": "", "minLength": 0, "maxLength": 9999 } }, { "name": "phone_number", "in": "query", "required": false, "schema": { "type": "string", "example": "+1 (555)", "description": "Performs a case-insensitive substring match against the location's phone numbers. An empty string is treated as absent, and no filter is applied.", "default": "", "minLength": 0, "maxLength": 255 } }, { "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 locations 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 locations 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 locations 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 locations 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" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "example": 5, "description": "The return services count for per location", "minimum": 1, "maximum": 2147483647, "default": 15 } }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "example": "proximity_distance", "description": " Specifies the field to order the results by. Currently, only the following value is supported: ", "default": "", "minLength": 0, "maxLength": 9999 } } ], "responses": { "200": { "description": "The paginated list of locations", "content": { "application/json": { "schema": { "type": "object", "description": "Represents a paginated list of locations", "required": [ "count", "total", "total_pages", "page", "per_page", "_embedded", "_links" ], "properties": { "count": { "type": "integer", "format": "int32", "description": "The number of results in the current page", "example": 40 }, "total": { "type": "integer", "format": "int32", "description": "The total of results", "example": 90 }, "page": { "type": "integer", "format": "int32", "description": "The current page", "example": 2 }, "per_page": { "type": "integer", "format": "int32", "description": "The number of results per page", "example": 50 }, "total_pages": { "type": "integer", "format": "int32", "description": "The total number of result pages", "example": 2 }, "_embedded": { "type": "object", "required": [ "locations" ], "properties": { "locations": { "type": "array", "description": "The list of locations in the current page", "items": { "allOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The location identifier", "minLength": 1, "example": "d08d05cc-ac7a-11ed-afa1-0242ac120002" }, "custom_fields": { "type": "array", "description": "Custom field values for the location.", "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" } } } }, "provenance": { "type": "object", "description": "Identifies the system and record the entry was first created from. It can only be set when the entry is created; updates and CSV imports do not change it.", "properties": { "id": { "type": "string", "description": "The identifier of the source record.", "example": "a1b2c3d4-0000-4000-8000-000000000001" }, "key": { "type": "string", "description": "The key of the source system.", "example": "crm" } } } } }, { "type": "object", "required": [ "name", "time_zone", "address", "staffs" ], "properties": { "name": { "type": "string", "description": "The name of the location", "minLength": 1, "example": "Store Avenida da Liberdade" }, "alternative_names": { "type": "array", "description": "The alternative names of the location", "example": [ "Liberdade Store", "Lisboa Flagship" ], "items": { "type": "string", "description": "The alternative name (e.g., Liberdade Store, Lisboa Flagship)", "minLength": 1, "maxLength": 9999, "example": "Liberdade Store" } }, "external_id": { "type": "string", "description": "The external id of the location", "minLength": 1, "example": 123 }, "type": { "type": "string", "description": "The type of the location", "minLength": 1, "example": "Store" }, "time_zone": { "type": "string", "description": "The time zone of the location, according to IANA.", "minLength": 1, "example": "Europe/Lisbon" }, "phone_numbers": { "type": "array", "items": { "type": "object", "description": "Represents the phone numbers of a location", "required": [ "phone_number" ], "properties": { "phone_number": { "type": "string", "description": "The phone number of one person.", "example": "+351123456789", "minLength": 1 }, "name": { "type": "string", "description": "The phone number name", "example": "Home", "minLength": 1 } } } }, "image_url": { "type": "string", "description": "The URL of an image of the location", "minLength": 1, "example": "https://my-image-cdn.com/path/to/my/store/image.png" }, "address": { "type": "object", "description": "Represents the address of a location", "required": [ "address", "zip_code", "country_name" ], "properties": { "address": { "type": "string", "description": "The address line of the location. Typically the street, number, etc.", "example": "Lisbon", "minLength": 1 }, "zip_code": { "type": "string", "description": "The zip-code of the location", "example": "20000000", "minLength": 1 }, "city": { "type": "string", "description": "The city of the location", "example": "Lisbon", "minLength": 1 }, "region_name": { "type": "string", "description": "The region name (country subdivision)", "example": "Lisbon", "minLength": 1 }, "country_name": { "type": "string", "description": "The country name", "example": "Portugal", "minLength": 1 }, "coordinates": { "type": "object", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "format": "double", "minimum": -90, "maximum": 90, "example": 38.736946 }, "longitude": { "type": "number", "format": "double", "minimum": -180, "maximum": 180, "example": -9.142685 } } } } }, "opening_status": { "type": "string", "description": "The status of the location, if it is opened or closed", "minLength": 1, "enum": [ "OPEN", "CLOSED" ], "example": "OPEN" }, "services": { "type": "array", "description": "The list of services", "items": { "type": "object", "required": [ "id", "name" ], "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": "name" } } } }, "staffs": { "type": "array", "description": "The list of staff members assigned to this location.", "default": [], "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" } } } }, "provenance": { "type": "object", "description": "Identifies the system and record the entry was first created from. It can only be set when the entry is created; updates and CSV imports do not change it.", "properties": { "id": { "type": "string", "description": "The identifier of the source record.", "example": "a1b2c3d4-0000-4000-8000-000000000001" }, "key": { "type": "string", "description": "The key of the source system.", "example": "crm" } } } } } } } } ] } } } }, "_links": { "type": "object", "required": [ "self" ], "properties": { "self": { "type": "object", "required": [ "href" ], "properties": { "href": { "type": "string", "format": "uri", "example": "http://api-docs.talkdesk.org/locations-directory/locations?page=1&per_page=10" } } }, "next": { "type": "object", "required": [ "href" ], "properties": { "href": { "type": "string", "format": "uri", "example": "http://api-docs.talkdesk.org/locations-directory/locations?page=2&per_page=10" } } } } } } }, "example": { "_embedded": { "locations": [ { "id": "d08d05cc-ac7a-11ed-afa1-0242ac120002", "name": "Store Avenida da Liberdade", "alternative_names": [ "Liberdade Store", "Lisboa Flagship" ], "type": "Store", "external_id": 123, "phone_numbers": [ { "phone_number": "+351123456789", "name": "Home" }, { "phone_number": "+351123456780", "name": "Personal" } ], "time_zone": "Europe/Lisbon", "image_url": "https://my-image-cdn.com/path/to/my/avenida-da-liberdade-store/image.png", "address": { "address": "Avenida da Liberdade, 10", "zip_code": "1250-142", "city": "Lisbon", "region_name": "Lisbon", "country_name": "Portugal", "coordinates": { "latitude": 38.736946, "longitude": -9.142685 } }, "staffs": [ { "id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "Dr. Ana Costa", "external_id": "staff-001", "relationships": [ { "id": "d06b0425-c9eb-d8a3-a7c0-ce14d96a651f", "name": "General Consultation" } ], "tags": [ { "id": "tag-001", "name": "Cardiologist" } ] } ], "custom_fields": [ { "id": "6215e62f-c071-47c3-adbe-567f236cf3bf", "custom_field_template_entry_id": "e58bae95-8be0-4fd8-ac05-3f41e85c85e3", "name": "visit_category", "field_type": "SHORT_TEXT", "value": "wellness" } ] }, { "id": "e740d8ce-ac7b-11ed-afa1-0242ac120002", "phone_numbers": [ { "phone_number": "+351123456789", "name": "Home" }, { "phone_number": "+351123456780", "name": "Personal" } ], "time_zone": "Europe/Lisbon", "name": "Store Avenida dos Aliados", "external_id": 123, "image_url": "https://my-image-cdn.com/path/to/my/avenida-dos-aliados-store/image.png", "address": { "address": "Avenida dos Aliados", "zip_code": "4000-066", "city": "Porto", "region_name": "Porto", "country_name": "Portugal", "coordinates": { "latitude": 41.15, "longitude": -8.61024 } }, "services": [ { "id": "d06b0425-c9eb-d8a3-a7c0-ce14d96a651f", "name": "name" }, { "id": "f06b0425-c9eb-d8a3-a7c0-ce14d96a651f", "name": "name1" } ], "staffs": [] } ] }, "_links": { "self": { "href": "http://api-docs.talkdesk.org/locations-directory/locations?page=1&per_page=2" }, "next": { "href": "http://api-docs.talkdesk.org/locations-directory/locations?page=2&per_page=2" } } } } } }, "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": "4034000", "message": "Bad request." } } } }, "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" } } ```