Update a number

patch

https://api.emaktalk.com/api/v1/numbers/{phoneNumberId}

Updates a phone number's routing and settings. Fields you omit keep their current values.

Use it:

Send only the fields you want to change.
On an account that routes calls only through call flows, send call_flow_uuid to attach the number to a call flow or move it to another one (see below).

Notes:

Every change is recorded in the number's history.
Routing changes take effect right away: the number's routing is rebuilt and reloaded.
Sending destination_actions, even with its current value, gives the number routing of its own and detaches it from its call flow (except on call-flows-only accounts, below).
domain_uuid, provider_uuid, provider_verified, destination_enabled and domain_name are ignored, without an error.
Changing the number, its prefix or its match pattern is refused (403) if the result would match a number another account already uses. Re-sending the values they already hold is fine.
If a step after saving fails, the change is rolled back where possible, and the response says whether that worked.

Accounts that route calls only through call flows:

Every enabled number stays attached to a call flow.
call_flow_uuid attaches the number first; the rest of your update is saved after. The response's attached_flow names the flow.
A change that would leave an enabled number without a call flow needs call_flow_uuid. That's clearing its routing, or changing anything on a number that has no call flow yet. Without it, you get 409 flow_required and nothing changes.
No published call flow yet? The number is attached to a new call flow named "Default call flow", which simply hangs up. You can edit it like any other call flow.
The routing fields can't give the number routing of its own here (409 legacy_routing_retired).
Disabled numbers never need a call flow, and neither does changing only destination_hold_music.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

phoneNumberId

string

required

ID of the phone number to update. The format is not checked before the lookup.

Body Params

destination_actions

array of objects

Routing actions for the number. The first entry supplies the flat app and data, and the array is stored when both are present. Sending a non-null array detaches the number from any call flow.

destination_actions

fax_meta_properties

string

Fax metadata, stored as sent.

destination_type_text

number

Whether the number carries text messaging.

destination_type_emergency

number

Whether the number is usable for emergency calling.

destination_order

number

Sort order for the number.

destination_type

string

Type of the destination.

destination_number

string

The phone number itself.

destination_prefix

string

Prefix stored with the number.

destination_number_regex

string

Match expression used to recognize the number on an inbound call.

destination_caller_id_name

string

Caller ID name sent with calls on this number. Trimmed.

destination_caller_id_number

string

Caller ID number sent with calls on this number.

destination_cid_name_prefix

string

Prefix added to the caller ID name. Trimmed.

destination_context

string

Routing context the number belongs to.

destination_app

string

Routing application for the number. Overrides the value derived from destination_actions.

destination_data

string

Argument for the routing application. Overrides the value derived from destination_actions.

destination_description

string

Free-text description of the number. Trimmed.

destination_record

boolean

Whether calls on this number are recorded. Stored as the string true or false.

destination_alternate_app

string

Alternate routing application.

destination_alternate_data

string

Argument for the alternate routing application.

destination_hold_music

What callers to this number hear when they're put on hold. Takes a recording, music on hold, an internet stream or silence, as a sound reference: an object whose type is one of the types below. null plays the default hold music.

destination_uuid

string

The number's own ID. It can be changed here, so send it only when you mean to.

dialplan_uuid

string

ID of the routing entry associated with this number.

fax_uuid

string

Fax account this number delivers to. Send an empty string to clear it.

user_uuid

string

User this number is assigned to. Send an empty string to clear it.

call_flow_uuid

uuid

The call flow to attach the number to: one of your account's published call flows. Only for accounts that route calls only through call flows (others get 400 invalid_parameter). It attaches or moves the number even when the change doesn't need it.

Responses

401

Missing or invalid API key.

Language

Credentials

Bearer

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200The number was updated. attached_flow: the call flow this update attached the number to (including a new Default call flow). detached_flow: the call flow it left, when destination_actions detached it.

403The new number, prefix or match pattern would match a number another account already uses. Nothing was changed.

404 No such number. flow_not_found: the call flow in call_flow_uuid isn't one of your account's call flows.

422The routing couldn't be rebuilt because the number, its match pattern or its account details are incomplete.

502A lookup, routing rebuild or reload failed. The change was rolled back where possible, and the response says whether that worked. routing_regen_failed: the number was attached (or the change saved) but its routing didn't load. message says what was saved; send the same update again to finish it.