---
title: "Update basic route"
method: POST
path: "/v1/projects/{project_id}/phones/{id}"
tags: ["Phone"]
---

# Update basic route

`POST /v1/projects/{project_id}/phones/{id}`

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/projects/{project_id}/phones/{id}`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`)

Saves any fields or custom variables that have changed for this basic route.

## Path parameters

- `project_id` string, required
- `id` string, required

## Request body

- object
  - `name` string: Name of the phone
  - `phone_number` string: Phone number or sender ID
  - `send_paused` boolean: True if sending messages is currently paused, false if the phone can currently send messages
  - `vars` object: Custom variables stored for this phone. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.
  - `validate_recipient_numbers` boolean: Set to true to check that recipient phone numbers appear to be valid before sending messages. Messages to invalid phone numbers will fail without being sent. Only applies to phones capable of sending messages.
  - `allowed_recipient_countries` string[]: Array of 2-letter country codes (ISO 3166-1 alpha-2) to which this phone is allowed to send messages. When null, there is no restriction on recipient countries.
  - `sent_message_limit` integer: Maximum number of messages that can be sent from this phone in a given period. When the sent_message_count reaches this limit, sending is automatically paused. Set to null to disable the limit.
  - `send_delay` number: Number of seconds to wait after sending each message from this phone, to avoid exceeding carrier rate limits.
  - `timezone_id` string: A string specifying the time zone that will be used when implementing quiet hours or estimating send times; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). When null, the project's default time zone is used.
  - `quiet_mode` 'off' | 'delay' | 'confirm': Controls behavior during quiet hours (see quiet_start/quiet_end). Possible values are 'off' (quiet hours disabled), 'delay' (messages are delayed until quiet hours end), or 'confirm' (requires manual confirmation to send during quiet hours).
  - `quiet_start` string: Time of day when quiet hours begin, in HH:MM format (24-hour time) in the phone's time zone. Messages sent during quiet hours are delayed or require confirmation depending on quiet_mode. Only applicable when quiet_mode is not 'off'.
  - `quiet_end` string: Time of day when quiet hours end, in HH:MM format (24-hour time) in the phone's time zone. Messages sent during quiet hours are delayed or require confirmation depending on quiet_mode. Only applicable when quiet_mode is not 'off'.
  - `external_account_id` string: Account ID for the external API (e.g. Twilio Account SID, Vonage API Key). Only present for routes that support external API configuration. See createPhone for the meaning of this field for each phone type.
  - `external_id` string: External phone/resource ID within the external API account (if applicable). Only present for routes that support external API configuration.
  - `external_config` object: Additional configuration settings specific to the phone_type. Only present for routes that support external API configuration. See createPhone for available settings for each phone type.
  - `external_secret` string: Secret/API key for the external API (e.g. Twilio Auth Token, Vonage API Secret). Only applicable for routes that support external API configuration. Write-only; not returned by the API when retrieving a phone.
  - `vcard` object: The route's Contact Card (a vCard that recipients can save to their address book). Only present for routes associated with a phone number that can send messages. When updating this field, only the provided properties are changed. To attach the sending route's Contact Card to a message, include the media item `{"type": "route_vcard"}` in the `media` parameter of project.sendMessage and related methods.
    - `enabled` boolean: Whether the Contact Card can be attached to messages sent from this route.
    - `name` string: Name shown on the Contact Card (defaults to the organization name).
    - `version` string: vCard version. `3.0` is recommended for compatibility.
    - `logo_url` string: URL of the Contact Card's logo image, or null if there is no logo. Read-only.
    - `phone_number` string: Phone number stored on the Contact Card (always the route's own phone number). Read-only.
    - `logo_file_id` string: To set the logo, upload a JPEG or PNG image (max 1MB) via [project.uploadFile](#Project.uploadFile) and provide the resulting file ID; set to null to remove the logo. Write-only; not returned by the API.

## Response `200`

Successful response

- Phone: Represents a basic route (i.e. a phone or gateway) that you use to send/receive messages via Telerivet. Basic Routes were formerly referred to as "Phones" within Telerivet. API methods, parameters, and properties related to Basic Routes continue to use the term "Phone" to maintain backwards compatibility.
  - `id` string: ID of the phone
  - `name` string: Name of the phone
  - `phone_number` string: Phone number or sender ID
  - `phone_type` string: Type of this phone/route (e.g. android, twilio, nexmo, etc)
  - `country` string: 2-letter country code (ISO 3166-1 alpha-2) where phone is from
  - `send_paused` boolean: True if sending messages is currently paused, false if the phone can currently send messages
  - `time_created` integer: Time the phone was created in Telerivet
  - `last_active_time` integer, nullable: Approximate time this phone last connected to Telerivet
  - `vars` object: Custom variables stored for this phone. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.
  - `project_id` string: ID of the project this phone belongs to
  - `validate_recipient_numbers` boolean: Set to true to check that recipient phone numbers appear to be valid before sending messages. Messages to invalid phone numbers will fail without being sent. Only applies to phones capable of sending messages.
  - `allowed_recipient_countries` string[], nullable: Array of 2-letter country codes (ISO 3166-1 alpha-2) to which this phone is allowed to send messages. When null, there is no restriction on recipient countries.
  - `sent_message_limit` integer, nullable: Maximum number of messages that can be sent from this phone in a given period. When the sent_message_count reaches this limit, sending is automatically paused. Set to null to disable the limit.
  - `sent_message_count` integer: Number of messages sent from this phone since the counter was last reset (see sent_message_epoch). This property is not updated if sent_message_limit is null.
  - `sent_message_epoch` integer, nullable: The UNIX timestamp when the sent_message_count was last reset to 0.
  - `send_delay` number, nullable: Number of seconds to wait after sending each message from this phone, to avoid exceeding carrier rate limits.
  - `timezone_id` string, nullable: A string specifying the time zone that will be used when implementing quiet hours or estimating send times; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). When null, the project's default time zone is used.
  - `quiet_mode` 'off' | 'delay' | 'confirm': Controls behavior during quiet hours (see quiet_start/quiet_end). Possible values are 'off' (quiet hours disabled), 'delay' (messages are delayed until quiet hours end), or 'confirm' (requires manual confirmation to send during quiet hours).
  - `quiet_start` string, nullable: Time of day when quiet hours begin, in HH:MM format (24-hour time) in the phone's time zone. Messages sent during quiet hours are delayed or require confirmation depending on quiet_mode. Only applicable when quiet_mode is not 'off'.
  - `quiet_end` string, nullable: Time of day when quiet hours end, in HH:MM format (24-hour time) in the phone's time zone. Messages sent during quiet hours are delayed or require confirmation depending on quiet_mode. Only applicable when quiet_mode is not 'off'.
  - `battery` integer, nullable: Current battery level, on a scale from 0 to 100, as of the last time the phone connected to Telerivet (only present for Android phones)
  - `charging` boolean, nullable: True if the phone is currently charging, false if it is running on battery, as of the last time it connected to Telerivet (only present for Android phones)
  - `internet_type` string, nullable: String describing the current type of internet connectivity for an Android phone, for example WIFI or MOBILE (only present for Android phones)
  - `app_version` string: Currently installed version of Telerivet Android app (only present for Android phones)
  - `android_sdk` integer, nullable: Android SDK level, indicating the approximate version of the Android OS installed on this phone; see [list of Android SDK levels](http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) (only present for Android phones)
  - `mccmnc` string: Code indicating the Android phone's current country (MCC) and mobile network operator (MNC); see [Mobile country code Wikipedia article](https://en.wikipedia.org/wiki/Mobile_country_code) (only present for Android phones). Note this is a string containing numeric digits, not an integer.
  - `manufacturer` string: Android phone manufacturer (only present for Android phones)
  - `model` string: Android phone model (only present for Android phones)
  - `send_limit` integer, nullable: Maximum number of SMS messages per hour that can be sent by this Android phone. To increase this limit, install additional SMS expansion packs in the Telerivet Gateway app. (only present for Android phones)
  - `external_account_id` string, nullable: Account ID for the external API (e.g. Twilio Account SID, Vonage API Key). Only present for routes that support external API configuration. See createPhone for the meaning of this field for each phone type.
  - `external_id` string, nullable: External phone/resource ID within the external API account (if applicable). Only present for routes that support external API configuration.
  - `external_config` object, nullable: Additional configuration settings specific to the phone_type. Only present for routes that support external API configuration. See createPhone for available settings for each phone type.
  - `external_setup` object, nullable: Configuration info for routes that require manual webhook setup. Only present for routes that require manual configuration of callback URLs with the external provider. Contains URL properties for each webhook type that needs to be configured (e.g., `incoming_message_url`, `message_status_url`, `incoming_call_url`).
  - `external_secret` string, nullable: Secret/API key for the external API (e.g. Twilio Auth Token, Vonage API Secret). Only applicable for routes that support external API configuration. Write-only; not returned by the API when retrieving a phone.
  - `vcard` object, nullable: The route's Contact Card (a vCard that recipients can save to their address book). Only present for routes associated with a phone number that can send messages. When updating this field, only the provided properties are changed. To attach the sending route's Contact Card to a message, include the media item `{"type": "route_vcard"}` in the `media` parameter of project.sendMessage and related methods.
    - `enabled` boolean: Whether the Contact Card can be attached to messages sent from this route.
    - `name` string: Name shown on the Contact Card (defaults to the organization name).
    - `version` string: vCard version. `3.0` is recommended for compatibility.
    - `logo_url` string: URL of the Contact Card's logo image, or null if there is no logo. Read-only.
    - `phone_number` string: Phone number stored on the Contact Card (always the route's own phone number). Read-only.
    - `logo_file_id` string: To set the logo, upload a JPEG or PNG image (max 1MB) via [project.uploadFile](#Project.uploadFile) and provide the resulting file ID; set to null to remove the logo. Write-only; not returned by the API.
  - `url` string: URL to this phone in the Telerivet web app

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

[API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)