{"__v":1,"_id":"5450f1397abbbc0800a5eaf6","category":{"__v":5,"_id":"5450b045a66f020800dba73d","pages":["5450b9fb7abbbc0800a5e953","5450c166a66f020800dba820","5450f1397abbbc0800a5eaf6","5450ea98a66f020800dba92e","5450ee92a66f020800dba965"],"project":"542dbe0ecb19820800c1f4d7","version":"542ecc0a6b0eb6080066ca77","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-29T09:15:49.477Z","from_sync":false,"order":13,"slug":"incoming-phone-numbers","title":"Incoming Phone Numbers"},"editedParams":true,"editedParams2":true,"is_link":false,"parentDoc":null,"project":"542dbe0ecb19820800c1f4d7","user":"544a586d27b7fc140078db12","version":{"__v":29,"_id":"542ecc0a6b0eb6080066ca77","forked_from":"542dbe0fcb19820800c1f4da","project":"542dbe0ecb19820800c1f4d7","createdAt":"2014-10-03T16:17:14.165Z","releaseDate":"2014-10-03T16:17:14.165Z","categories":["542ecc0a6b0eb6080066ca78","542ef44f6b0eb6080066cb24","543bf3e22a30961a00b66eb3","5446952b82bd7e08002768a0","544821ae8d7af31a00dd41ce","544a7885f1aefa08006efc69","544c758e11845f0e001ed8de","544e5565b80812080035be55","544e558dbd51b9080037f8ca","5450b045a66f020800dba73d","5450eb6aa66f020800dba945","5450f39ea66f020800dba989","5450f877a66f020800dba9cf","54510356a66f020800dbaa17","5451274514af501a00b50c99","54513345a66f020800dbab24","54513cc014af501a00b50d24","54515eec14af501a00b50db9","54519b1d14af501a00b50ea9","54519b2aa66f020800dbacb4","54524f9704160008005b1d27","54538d2308d1800800473d95","54538d420c09721000a06a03","54538e5608d1800800473d9a","5453ea9547c30114004fb375","5453eb12b077c31c00067bcb","5453eb27b077c31c00067bcd","5453ed5db077c31c00067bde","548075cbe291c51a00e7e096"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-10-29T13:52:57.255Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":true,"method":"post","results":{"codes":[{"name":"","code":"{\n    \"date_updated\": \"Wed, 29 Oct 2014 13:13:26 -0000\",\n    \"voice_url\": \"http://telapi.com/ivr/welcome/call\",\n    \"voice_fallback_method\": \"GET\",\n    \"capabilities\": {\n        \"voice\": \"true\",\n        \"sms\": \"false\"\n    },\n    \"sid\": \"{IncomingPhoneNumberSid}\",\n    \"heartbeat_method\": \"POST\",\n    \"type\": \"local\",\n    \"status_callback_method\": \"GET\",\n    \"voice_fallback_url\": \"\",\n    \"phone_number\": \"+38551770214\",\n    \"hangup_callback\": \"http://webhookr.com/3TvvBQ\",\n    \"hangup_callback_method\": \"GET\",\n    \"heartbeat_url\": null,\n    \"sms_url\": \"http://telapi.com/ivr/welcome/sms\",\n    \"voice_method\": \"POST\",\n    \"voice_caller_id_lookup\": \"false\",\n    \"friendly_name\": \"testing it\",\n    \"uri\": \"/v2/Accounts/{AccountSid}/IncomingPhoneNumbers/{IncomingPhoneNumberSid}\",\n    \"sms_fallback_url\": \"\",\n    \"account_sid\": \"{AccountSid}\",\n    \"sms_method\": \"POST\",\n    \"api_version\": \"v2\",\n    \"sms_fallback_method\": \"POST\",\n    \"next_renewal_date\": \"Wed, 12 Nov 2014 15:38:43 -0000\",\n    \"date_created\": \"Mon, 13 Oct 2014 15:38:42 -0000\",\n    \"status_callback\": \"http://webhookr.com/3TvvBQ\"\n}","language":"json","status":200},{"name":"","code":"{\n    \"status\": 404,\n    \"message\": \"The requested resource was not found: /v2/Accounts/bad/bad_response.json\"\n}","language":"json","status":404}]},"settings":"","try":true,"auth":"required","params":[{"_id":"5450f1397abbbc0800a5eb09","ref":"","in":"path","required":true,"desc":"Account SID.","default":"","type":"string","name":"AccountSid"},{"_id":"5450f1397abbbc0800a5eb08","ref":"","in":"body","required":false,"desc":"A specific available phone number you wish to add.","default":"","type":"string","name":"PhoneNumber"},{"_id":"5450f1397abbbc0800a5eb07","ref":"","in":"body","required":false,"desc":"The area code from which a random available number will be added.","default":"","type":"string","name":"AreaCode"},{"_id":"5450f1397abbbc0800a5eb06","ref":"","in":"body","required":false,"desc":"User generated name for the incoming number.","default":"","type":"string","name":"FriendlyName"},{"_id":"5450f1397abbbc0800a5eb05","ref":"","in":"body","required":false,"desc":"The URL returning InboundXML incoming calls should execute when connected.","default":"","type":"string","name":"VoiceUrl"},{"_id":"5450f1397abbbc0800a5eb04","ref":"","in":"body","required":false,"desc":"Specifies the HTTP method used to request the VoiceUrl once incoming call connects.","default":"POST","type":"string","name":"VoiceMethod"},{"_id":"5450f1397abbbc0800a5eb03","ref":"","in":"body","required":false,"desc":"URL used if any errors occur during execution of InboundXML on a call or at initial request of the VoiceUrl.","default":"","type":"string","name":"VoiceFallbackUrl"},{"_id":"5450f1397abbbc0800a5eb02","ref":"","in":"body","required":false,"desc":"Specifies the HTTP method used to request the VoiceFallbackUrl once incoming call connects.","default":"POST","type":"string","name":"VoiceFallbackMethod"},{"_id":"5450f1397abbbc0800a5eb01","ref":"","in":"body","required":false,"desc":"Look up the caller’s caller-ID name from the CNAM database (additional charges apply).","default":"","type":"string","name":"VoiceCallerIdLookup"},{"_id":"5450f1397abbbc0800a5eb00","ref":"","in":"body","required":false,"desc":"The URL returning InboundXML incoming phone numbers should execute when receiving an SMS.","default":"","type":"string","name":"SmsUrl"},{"_id":"5450f1397abbbc0800a5eaff","ref":"","in":"body","required":false,"desc":"Specifies the HTTP method used to request the SmsUrl once an incoming SMS is received.","default":"POST","type":"string","name":"SmsMethod"},{"_id":"5450f1397abbbc0800a5eafe","ref":"","in":"body","required":false,"desc":"URL used if any errors occur during execution of InboundXML from an SMS or at initial request of the SmsUrl.","default":"","type":"string","name":"SmsFallbackUrl"},{"_id":"5450f1397abbbc0800a5eafd","ref":"","in":"body","required":false,"desc":"Specifies the HTTP method used to request the SmsFallbackUrl.","default":"POST","type":"string","name":"SmsFallbackMethod"},{"_id":"5450f1397abbbc0800a5eafc","ref":"","in":"body","required":false,"desc":"URL that can be used to monitor the phone number.","default":"","type":"string","name":"HeartbeatUrl"},{"_id":"5450f1397abbbc0800a5eafb","ref":"","in":"body","required":false,"desc":"The HTTP method TelAPI will use when requesting the HeartbeatURL.","default":"POST","type":"string","name":"HeartbeatMethod"},{"_id":"5450f1397abbbc0800a5eafa","ref":"","in":"body","required":false,"desc":"URL that can be requested to receive notification when and how incoming call has ended.","default":"","type":"string","name":"StatusCallback"},{"_id":"5450f1397abbbc0800a5eaf9","ref":"","in":"body","required":false,"desc":"The HTTP method TelAPI will use when requesting the HangupCallback URL.","default":"POST","type":"string","name":"StatusCallbackMethod"},{"_id":"5450f1397abbbc0800a5eaf8","ref":"","in":"body","required":false,"desc":"This is a StatusCallback clone that will be phased out in future versions.","default":"","type":"string","name":"HangupCallback"},{"_id":"5450f1397abbbc0800a5eaf7","ref":"","in":"body","required":false,"desc":"This is a StatusCallbackMethod clone that will be phased out in future versions.","default":"POST","type":"string","name":"HangupCallbackMethod"},{"_id":"556c7e9175996f2d00c2b3eb","ref":"","in":"body","required":false,"desc":"The SID of the Voice Application you wish to associate with this incoming number.","default":"","type":"string","name":"VoiceApplicationSid"},{"_id":"556c7e9075996f2d00c2b3ea","ref":"","in":"body","required":false,"desc":"The SID of the SMS Application you wish to associate with this incoming number.","default":"","type":"string","name":"SmsApplicationSid"}],"url":"/:version/Accounts/:AccountSid/IncomingPhoneNumbers.json"},"isReference":false,"order":2,"body":"TelAPI incoming phone numbers can be added or removed from an account through our REST API. When adding a phone number, users can either make the request for a specific available phone number using the PhoneNumber parameter, or a random phone number within a specific area code using the AreaCode parameter. To view a list of numbers available for purchase, a GET request to the AvailablePhoneNumbers URI can be made.\n\n# **Response Parameters**\n\nResponse parameters are equal to those on [\"View Incoming Number\" API call](/v2/docs/view-incoming-number).\n\n# **Example cURL**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST -d 'AreaCode={SomeAreaCode}' -u '{AccountSid}:{AuthToken}' 'https://api.telapi.com/v2/Accounts/{AccountSid}/IncomingPhoneNumbers.json'\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]","excerpt":"purchases a new incoming number","slug":"purchase-incoming-number","type":"endpoint","title":"Purchase Incoming Number"}

postPurchase Incoming Number

purchases a new incoming number

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

AccountSid:
required
string
Account SID.

Body Params

PhoneNumber:
string
A specific available phone number you wish to add.
AreaCode:
string
The area code from which a random available number will be added.
FriendlyName:
string
User generated name for the incoming number.
VoiceUrl:
string
The URL returning InboundXML incoming calls should execute when connected.
VoiceMethod:
stringPOST
Specifies the HTTP method used to request the VoiceUrl once incoming call connects.
VoiceFallbackUrl:
string
URL used if any errors occur during execution of InboundXML on a call or at initial request of the VoiceUrl.
VoiceFallbackMethod:
stringPOST
Specifies the HTTP method used to request the VoiceFallbackUrl once incoming call connects.
VoiceCallerIdLookup:
string
Look up the caller’s caller-ID name from the CNAM database (additional charges apply).
SmsUrl:
string
The URL returning InboundXML incoming phone numbers should execute when receiving an SMS.
SmsMethod:
stringPOST
Specifies the HTTP method used to request the SmsUrl once an incoming SMS is received.
SmsFallbackUrl:
string
URL used if any errors occur during execution of InboundXML from an SMS or at initial request of the SmsUrl.
SmsFallbackMethod:
stringPOST
Specifies the HTTP method used to request the SmsFallbackUrl.
HeartbeatUrl:
string
URL that can be used to monitor the phone number.
HeartbeatMethod:
stringPOST
The HTTP method TelAPI will use when requesting the HeartbeatURL.
StatusCallback:
string
URL that can be requested to receive notification when and how incoming call has ended.
StatusCallbackMethod:
stringPOST
The HTTP method TelAPI will use when requesting the HangupCallback URL.
HangupCallback:
string
This is a StatusCallback clone that will be phased out in future versions.
HangupCallbackMethod:
stringPOST
This is a StatusCallbackMethod clone that will be phased out in future versions.
VoiceApplicationSid:
string
The SID of the Voice Application you wish to associate with this incoming number.
SmsApplicationSid:
string
The SID of the SMS Application you wish to associate with this incoming number.

Result Format


Documentation

TelAPI incoming phone numbers can be added or removed from an account through our REST API. When adding a phone number, users can either make the request for a specific available phone number using the PhoneNumber parameter, or a random phone number within a specific area code using the AreaCode parameter. To view a list of numbers available for purchase, a GET request to the AvailablePhoneNumbers URI can be made. # **Response Parameters** Response parameters are equal to those on ["View Incoming Number" API call](/v2/docs/view-incoming-number). # **Example cURL** [block:code] { "codes": [ { "code": "curl -X POST -d 'AreaCode={SomeAreaCode}' -u '{AccountSid}:{AuthToken}' 'https://api.telapi.com/v2/Accounts/{AccountSid}/IncomingPhoneNumbers.json'", "language": "shell" } ] } [/block]