--- title: "Create a basic route" method: POST path: "/v1/projects/{project_id}/phones" tags: ["Phone"] --- # Create a basic route `POST /v1/projects/{project_id}/phones` ## Request - Base URL: `https://api.telerivet.com` - URL: `https://api.telerivet.com/v1/projects/{project_id}/phones` - Auth: one of: - HTTP basic - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`) Creates a new basic route (phone) with external API credentials. For some external API providers, this method automatically updates webhook URLs configured with the external provider so that incoming messages/calls and call status events are routed to Telerivet. In this case, if you have already configured a webhook URL with the external provider, it will be overwritten. For other external API providers, webhook URLs may require manual configuration in order for the route to be fully functional. Note: This API can only create routes that connect to external gateway APIs using your own account credentials. To add Android phones, WhatsApp routes, or routes with Telerivet-managed billing, use the web app instead. Credentials are passed via the `external_account_id`, `external_id`, `external_secret`, and `external_config` parameters. The meaning of these parameters for each phone type is as follows: **Twilio Virtual Number** (`phone_type`: twilio): - external_id (optional): Twilio phone number SID (starts with 'PN'); looked up by phone_number if not provided - external_account_id (required): Twilio Account SID (starts with 'AC') - external_secret (required): Twilio Auth Token **Twilio Messaging Service** (`phone_type`: twilio_messaging_service): - external_id (required): Twilio messaging service SID (starts with 'MG') - external_account_id (required): Twilio Account SID (starts with 'AC') - external_secret (required): Twilio Auth Token **Twilio Shortcode** (`phone_type`: twilio_shortcode): - external_id (optional): Twilio shortcode SID (starts with 'SC'); looked up by phone_number if not provided - external_account_id (required): Twilio Account SID (starts with 'AC') - external_secret (required): Twilio Auth Token **Twilio Caller ID** (`phone_type`: twilio_caller_id): - external_account_id (required): Twilio Account SID (starts with 'AC') - external_secret (required): Twilio Auth Token **Vonage Virtual Number** (`phone_type`: nexmo): - external_account_id (required): Vonage API Key - external_secret (required): Vonage API Secret **Vonage Sender ID** (`phone_type`: nexmo_sender_id): - external_account_id (required): Vonage API Key - external_secret (required): Vonage API Secret **Telesign SMS** (`phone_type`: telesign): - external_account_id (required): Telesign Customer ID - external_secret (required): Telesign API Key - external_config.message_type: ARN, MKT, or OTP - external_config.sender_type: one_way (default) or two_way **Infobip SMS** (`phone_type`: infobip): - external_account_id (required): Infobip username - external_secret (required): Infobip API key - external_config.sender_type: one_way (default) or two_way - external_config.india_dlt_principal_entity_id: India DLT Principal Entity ID (only for India) **Infobip USSD** (`phone_type`: infobip_ussd): - No external credentials required **Africa's Talking SMS** (`phone_type`: africas_talking): - external_account_id (required): Africa's Talking username - external_secret (required): Africa's Talking API key - external_config.sender_type: one_way (default) or two_way **Africa's Talking USSD** (`phone_type`: africas_talking_ussd): - No external credentials required **Simulated Phone** (`phone_type`: simulated): - No external credentials required - Messages are simulated locally and not sent to any external provider - Useful for testing #### Webhook URL Setup Some route types require manual configuration of callback URLs in the external provider's dashboard. When the Phone response includes an `external_setup` object, you will need to configure the webhook URLs in your provider's account settings. The following phone types require manual webhook setup: - `africas_talking`: `message_status_url` (always), `incoming_message_url` (if two_way) - `africas_talking_ussd`: `incoming_call_url` - `infobip_ussd`: `incoming_call_url` - `twilio_messaging_service`: `incoming_message_url` - `telesign` (two_way only): `incoming_message_url` Telerivet automatically configures webhooks for the following phone types as follows: - `twilio` - automatically updates incoming SMS and voice configuration for the Twilio virtual number associated with the phone_number or external_id parameter - `twilio_shortcode` - automatically updates incoming SMS configuration for the Twilio short code associated with the phone_number or external_id parameter - `nexmo` - automatically updates incoming SMS and voice configuration for the Vonage virtual number matching the phone_number parameter - `infobip` - automatically updates incoming SMS configuration for the Infobip virtual number matching the phone_number parameter or external_id parameter ## Path parameters - `project_id` string, required ## Request body - object - `name` string: Name of the basic route to create - `phone_number` string, required: Phone number or sender ID - `phone_type` string, required: Type of basic route to create. Supported values: twilio, twilio_messaging_service, twilio_shortcode, twilio_caller_id, nexmo, infobip, africas_talking, africas_talking_ussd, infobip_ussd, telesign, simulated. Other types of basic routes can only be created via the web app. - `external_account_id` string: Account ID for the external API (e.g. Twilio Account SID, Vonage API Key). See the description above for the meaning of this parameter for each phone type. - `external_id` string: External phone/resource ID within the external API account (if applicable). For `twilio` and `twilio_shortcode` routes, this is optional and will be looked up automatically from the phone_number if not provided. - `external_secret` string: Secret/API key for the external API (e.g. Twilio Auth Token, Vonage API Secret). This value is required when creating a new route but is never returned in API responses. See the description above for the meaning of this parameter for each phone type. - `external_config` object: Additional configuration settings specific to the phone_type. See the description above for available settings for each phone type. - `country` string: 2-letter country code (ISO 3166-1 alpha-2) where phone is from. This country code is used to automatically convert phone numbers in local format to international format. If not provided, will be set to the organization's country by default. - `send_paused` boolean: True if sending messages should initially be paused, false otherwise - `timezone_id` string: A string specifying the time zone used when sending messages; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). When not provided, the project's default time zone is used. - `validate_recipient_numbers` boolean: Set to true to validate recipient phone numbers before sending. Messages to invalid numbers will fail without being sent. - `allowed_recipient_countries` string[]: Array of 2-letter country codes (ISO 3166-1 alpha-2) to which this phone is allowed to send messages. If not provided, there is no restriction. - `send_delay` number: Number of seconds to wait after sending each message, to avoid exceeding carrier rate limits. - `quiet_mode` 'off' | 'delay' | 'confirm': Controls behavior during quiet hours. Possible values: 'off' (disabled), 'delay' (messages delayed until quiet hours end), 'confirm' (requires manual confirmation; worker-based routes only). - `quiet_start` string: Time when quiet hours begin, in HH:MM format (24-hour time). Only applicable when quiet_mode is not 'off'. - `quiet_end` string: Time when quiet hours end, in HH:MM format (24-hour time). Only applicable when quiet_mode is not 'off'. - `vars` object: Custom variables and values to set for this basic route ## 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)