List locations
curl --fail-with-body -X GET 'https://api.talki.it/v1/locations' \ -H "Authorization: Bearer $TALKI_API_KEY"from talki import Talki
talki = Talki()
location_list = talki.locations.list()print(location_list)import { Talki } from "@hubtec/talki";
const talki = new Talki();
const locationList = await talki.locations.list();console.log(locationList);Return every location of the account in one page: the main one, any other, and inactive ones, which keep their records. An account whose multi_sede is false has exactly one, the main location. Resolve the location_id on calls, bookings, services, resources, unresolved requests and closures here. Requires account:read. Limited to 600 requests per minute per account (API key) or per installation (OAuth).
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters”Example
2026-10-01Serve this one request at the given dated contract version instead of the credential’s pin. An unsupported value is refused with 400 unsupported_version, never downgraded.
Responses
Section titled “ Responses ”Successful Response
Every location of the account, inactive ones included, active first and then in the owner’s order, in one page: next_cursor is always null.
object
One place the business works from, with its own Talki number, assistant settings, weekly hours, line, services, resources and bookings. Every account has exactly one main location (is_default). Locations are created, renamed and switched off in Talki only; an inactive one stays listed with its records, takes no calls or bookings and has no Talki number.
object
Opaque Talki location identifier.
What the business calls the location; what the assistant names it to callers. Unique among active locations, not among all of them: key on id.
True for the main location, exactly one per account. It is never switched off.
active — it answers its calls and takes bookings. inactive — switched off in Talki, by the owner or because the plan has room for fewer locations: its records stay, it takes no calls or bookings, and it has no Talki number.
The location’s Talki number, its line that forwards to it, and whether that forwarding has been proven. For the main location, the same as Account.line.
object
no_number while the location has no Talki number. unverified until a forwarding check of the current forwarding_number has succeeded, including while none is set. verified once one has; it proves forwarding was on at verified_at, not that it still is. Changing forwarding_number returns it to unverified.
The owner’s display order, lowest first. Not unique.
When the location was added, RFC 3339 UTC.
True when another page is available.
Example
{ "data": [ { "id": "0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40", "name": "Studio Bellini", "is_default": true, "status": "active", "phone_number": "+390350000001", "line": { "phone_number": "+390350000001", "forwarding_number": "+393331112222", "status": "verified", "verified_at": "2026-10-07T09:30:12Z" }, "position": 0, "created_at": "2026-08-01T08:00:00Z", "deactivated_at": null }, { "id": "a6e3c2d8-1f47-4b95-8e0a-3d9c6b1f7a52", "name": "Borgo Trento", "is_default": false, "status": "active", "phone_number": "+390350000002", "line": { "phone_number": "+390350000002", "forwarding_number": "+390451234567", "status": "unverified", "verified_at": null }, "position": 1, "created_at": "2026-10-12T09:40:00Z", "deactivated_at": null } ], "next_cursor": null, "has_more": false}Headers
Section titled “Headers”Identifier to include when contacting Talki support.
Example
2026-10-01The dated contract version this response was served at.
Talki-Version, or the credential’s pin, names a version this API does not serve.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "invalid_request", "code": "unsupported_version", "message": "'2025-01-01' is not a supported API version. Supported: 2026-10-01.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
The credential is missing, malformed, expired, revoked, or unknown.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "authentication_error", "code": "invalid_credentials", "message": "The supplied API credential is invalid.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
The account does not have an active subscription.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "permission_error", "code": "subscription_inactive", "message": "This account does not have an active subscription.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
The account or credential may not perform this request.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This credential does not have the required scope.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
The account or installation exceeded its request rate (rate_limit_exceeded), or the calling address did (ip_rate_limited).
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Retry after the interval in Retry-After.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
Seconds to wait before retrying.
The budget of the window that was exceeded. Absent on ip_rate_limited.
Requests left in the window. Absent on ip_rate_limited.
When the window resets, in Unix seconds. Absent on ip_rate_limited.
An unexpected error occurred.
Every error answer has this shape.
object
The error itself. Branch on code; message is for people.
object
Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.
Example
{ "error": { "type": "api_error", "code": "internal_error", "message": "An unexpected error occurred. Quote the request_id when reporting it.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.