Skip to content
Talki DevelopersBeta

Update a caller rule

PATCH
/v1/caller_rules/{rule_id}
curl --fail-with-body -X PATCH 'https://api.talki.it/v1/caller_rules/93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30' \
  -H "Authorization: Bearer $TALKI_API_KEY" \
  -H "Idempotency-Key: rule-move-1" \
  -H "Content-Type: application/json" \
  --data '{"kind":"vip","label":"Supplier"}'

Move a rule to the other list or relabel it. Requires contacts: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”
rule_id
required
Rule Id
string

Header Parameters

Section titled “Header Parameters”
Talki-Version
string
Example
2026-10-01

Serve 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.

Idempotency-Key
string
<= 255 characters

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
rule-move-1

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
CallerRuleUpdate

A partial edit of a caller rule.

object
kind
Kind

Move it to the other list. Cannot be null.

string
Allowed values: vip blocked
label
Any of:
string
<= 100 characters
Example
{
  "kind": "vip",
  "label": "Supplier"
}

Responses

Section titled “ Responses ”

200

Section titled “200”

Successful Response

Media typeapplication/json
CallerRule

A VIP or blocked number of one location. A number is on one list at most at a location, so adding it to the other list moves it. A call from a VIP number to its location rings with caller.vip true on call.ringing.

object
id
required
Id

Rule identifier.

string
location_id
required
Location Id

The location whose calls it matches (GET /v1/locations). Never null, and it never changes.

string
phone_number
required
Phone Number

The number, E.164.

string
kind
required

vip or blocked.

string
Allowed values: vip blocked
label
required
Any of:
string
created_at
required
Created At

RFC 3339 UTC.

string format: date-time
updated_at
required
Updated At

RFC 3339 UTC.

string format: date-time
Example
{
  "id": "93c7e0a5-2d1f-4b68-8e4a-c6f19b2d7e30",
  "phone_number": "+393401234567",
  "location_id": "0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40",
  "kind": "vip",
  "label": "Supplier",
  "created_at": "2026-10-02T09:10:00Z",
  "updated_at": "2026-10-07T16:30:00Z"
}

Headers

Section titled “Headers”
X-Request-Id
string

Identifier to include when contacting Talki support.

Talki-Version
string
Example
2026-10-01

The dated contract version this response was served at.

Idempotency-Replayed
string
Allowed values: true

true when this response was replayed from a prior request with the same key.

400

Section titled “400”

A parameter, cursor, body field, or required idempotency key is invalid, or Talki-Version names an unsupported version (unsupported_version).

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

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.

string
message
required
string
request_id
required
string
Example
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameter",
    "message": "One or more request values are invalid.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

401

Section titled “401”

The credential is missing, malformed, expired, revoked, or unknown.

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

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.

string
message
required
string
request_id
required
string
Example
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credentials",
    "message": "The supplied API credential is invalid.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

402

Section titled “402”

The account does not have an active subscription.

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

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.

string
message
required
string
request_id
required
string
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”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

403

Section titled “403”

The account or credential may not perform this request.

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

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.

string
message
required
string
request_id
required
string
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”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

404

Section titled “404”

No caller rule with this ID exists in the authenticated account.

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

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.

string
message
required
string
request_id
required
string
Example
{
  "error": {
    "type": "invalid_request",
    "code": "resource_not_found",
    "message": "No such caller rule.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

409

Section titled “409”

The destination list is full (caller_rule_limit_reached), 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.

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

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.

string
message
required
string
request_id
required
string
Example
{
  "error": {
    "type": "conflict",
    "code": "caller_rule_limit_reached",
    "message": "A location holds at most 50 vip numbers. Remove one first.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

429

Section titled “429”

The account or installation exceeded its request rate (rate_limit_exceeded), or the calling address did (ip_rate_limited).

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

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.

string
message
required
string
request_id
required
string
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”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

Retry-After
integer

Seconds to wait before retrying.

X-RateLimit-Limit
string

The budget of the window that was exceeded. Absent on ip_rate_limited.

X-RateLimit-Remaining
integer

Requests left in the window. Absent on ip_rate_limited.

X-RateLimit-Reset
integer

When the window resets, in Unix seconds. Absent on ip_rate_limited.

500

Section titled “500”

An unexpected error occurred.

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

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.

string
message
required
string
request_id
required
string
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”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.