Restore an appointment
curl --fail-with-body -X POST 'https://api.talki.it/v1/appointments/a3fe45ee-572f-4677-b1dd-f36c21bb47de/restore' \ -H "Authorization: Bearer $TALKI_API_KEY" \ -H "Idempotency-Key: restore-crm-1042"from talki import Talki
talki = Talki()
appointment = talki.appointments.restore( "a3fe45ee-572f-4677-b1dd-f36c21bb47de", idempotency_key="restore-crm-1042",)print(appointment)import { Talki } from "@hubtec/talki";
const talki = new Talki();
const appointment = await talki.appointments.restore( "a3fe45ee-572f-4677-b1dd-f36c21bb47de", { idempotencyKey: "restore-crm-1042" },);console.log(appointment);Undo a cancellation, keeping the ID. Refused with a conflict code when the time no longer fits, and with service_deleted when a service of the booking has been deleted and that service’s part of the booking ends in the future: book it again with a service that exists. Refused with location_inactive when the booking’s location is switched off. Requires Idempotency-Key. Requires appointments:write. Limited to 120 requests per minute per account (API key) or per installation (OAuth).
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path 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.
Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked Idempotency-Replayed: true, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a 400 asking for a different request (invalid_parameter, invalid_cursor, export_too_large, unknown_scenario, no_services_requested, stay_too_short, stay_too_long, stay_dates_invalid), a 415, a 409 request_conflict, document_not_ready or check_in_progress, a 412, a 429 and a 5xx.
Example
restore-crm-1042Responses
Section titled “ Responses ”Successful Response
One booking in the account’s calendar. This object is the record: a connected Google or Outlook calendar holds a copy, so reconcile against this object, not against the provider calendar.
object
Opaque Talki appointment identifier.
The location the booking is at (GET /v1/locations), the one its service belongs to. Never null, and it never changes: moving a booking keeps its location.
active or cancelled. A cancelled appointment is retained rather than deleted, and can be restored — expect to see an id return to active via appointment.updated.
Who the booking is for. Always present; contact_id and phone_number are null when Talki has no number for the client. The name is the one the booking was taken under, exactly as the owner sees it, and may come from what the assistant heard on the call.
The service an appointment is for, with enough to display it. Once the service is deleted, id is null and name is the one it was booked under. Fetch the full service with services:read.
Start of the booking, RFC 3339 UTC.
End of the booking, RFC 3339 UTC. For a multi-day stay this is the check-out moment, so the span covers the whole booking rather than one night.
Party size the booking carries — covers, people, items — for a service that asks for one (asks_quantity on GET /v1/services). Always 1 for a service that does not, so you can read it unconditionally. It is the booking’s total, not a breakdown per resource or unit.
When the booking was written, RFC 3339 UTC.
Last change to the booking, RFC 3339 UTC. Show it to a human as “last modified”; do not sync on it: changes do not become visible in updated_at order, so a watermark on it can skip a booking permanently. Use the change feed’s next_cursor instead.
Example
{ "id": "a3fe45ee-572f-4677-b1dd-f36c21bb47de", "location_id": "0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40", "status": "active", "client": { "contact_id": "8fbb25f2-4f3b-4496-8aea-f0fc66de512d", "name": "Giulia", "surname": "Bianchi", "phone_number": "+393331234567" }, "service": { "id": "45c470b7-592a-42cd-8ce8-5d7a0a497d26", "name": "Haircut" }, "start_at": "2026-10-08T09:00:00Z", "end_at": "2026-10-08T09:30:00Z", "quantity": 1, "call_id": "38d23d84-02d2-4418-b169-3608aa04a8f8", "notes": "First visit", "created_at": "2026-09-15T09:18:03Z", "updated_at": "2026-10-07T10:12:45Z"}Headers
Section titled “Headers”Identifier to include when contacting Talki support.
Example
2026-10-01The dated contract version this response was served at.
true when this response was replayed from a prior request with the same key.
A parameter or body field is invalid (invalid_parameter); the booking cannot be made at any time (service_deleted, location_inactive, or another 400 booking code); Idempotency-Key is missing (idempotency_key_required); or Talki-Version names an unsupported version (unsupported_version).
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": "service_deleted", "message": "A service of this booking has been deleted, so the booking cannot be restored or moved to a time still to come.", "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.
No appointment with this ID exists in the authenticated account.
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": "resource_not_found", "message": "No such appointment.", "request_id": "req_7f24a2f8c6b64e699901563a458b5031" }}Headers
Section titled “Headers”Example
req_7f24a2f8c6b64e699901563a458b5031Identifier to include when contacting Talki support.
The appointment is not cancelled (appointment_not_cancelled), or the time no longer fits (slot_unavailable and the other booking conflict codes), or the idempotency key was reused for a different request. Except idempotency_key_reuse, the other refusals are replayed for 24 hours to a request with the same idempotency key: once the cause is gone, retry with a new key.
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": "conflict", "code": "slot_unavailable", "message": "That time is no longer available.", "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.