Vonage (Nexmo)
App · 19 actions
Send SMS, verify phone numbers, inspect number information and pricing, and manage your Vonage account and virtual numbers.
Actions
| Action | What it does |
|---|---|
| Buy number | Buy a number. |
| Cancel number | Cancel a number. |
| Check verification | Verify Check. |
| Control verification | Verify Control. |
| Get advanced number insight | Advanced Number Insight (sync). |
| Get all country pricing | Retrieve outbound pricing for all countries. |
| Get balance | Get Account Balance. |
| Get basic number insight | Basic Number Insight. |
| Get country pricing | Retrieve outbound pricing for a specific country. |
| Get prefix pricing | Retrieve outbound pricing for a specific dialing prefix. |
| Get standard number insight | Standard Number Insight. |
| Get verification | Verify Search. |
| List owned numbers | List the numbers you own. |
| Search available numbers | Search available numbers. |
| Send sms | Send an SMS. |
| Start payment verification | PSD2 (Payment Services Directive 2) Request. |
| Start verification | Request a Verification. |
| Update account settings | Change Account Settings. |
| Update number | Update a number. |
Buy number
Buy a number.
Inputs
- Country
countrytextRequired - The two character country code in ISO 3166-1 alpha-2 formatOne of:
AD(Andorra),AE(United Arab Emirates),AF(Afghanistan),AG(Antigua & Barbuda),AI(Anguilla),AL(Albania),AM(Armenia),AO(Angola),AQ(Antarctica),AR(Argentina), and 240 more. - Msisdn
msisdntextRequired - An available inbound virtual number.
- Target API key
target_api_keytext - If you’d like to perform an action on a subaccount, provide the `api_key` of that account here. If you’d like to perform an action on your own account, you do not need to provide this field.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"error-code": "example",
"error-code-label": "example"
}
}Cancel number
Cancel a number.
Inputs
- Country
countrytextRequired - The two character country code in ISO 3166-1 alpha-2 formatOne of:
AD(Andorra),AE(United Arab Emirates),AF(Afghanistan),AG(Antigua & Barbuda),AI(Anguilla),AL(Albania),AM(Armenia),AO(Angola),AQ(Antarctica),AR(Argentina), and 240 more. - Msisdn
msisdntextRequired - An available inbound virtual number.
- Target API key
target_api_keytext - If you’d like to perform an action on a subaccount, provide the `api_key` of that account here. If you’d like to perform an action on your own account, you do not need to provide this field.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"error-code": "example",
"error-code-label": "example"
}
}Check verification
Verify Check.
Inputs
- Request ID
request_idtextRequired - The Verify request to check. This is the `request_id` you received in the response to the Verify request.
- Code
codetextRequired - The verification code entered by your user.
- IP address
ip_addresstext - (This field is no longer used)
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"currency": "example",
"estimated_price_messages_sent": "example",
"event_id": "example",
"price": "example",
"request_id": "example",
"status": "example"
}
}Control verification
Verify Control.
Inputs
- Request ID
request_idtextRequired - The `request_id` you received in the response to the Verify request.
- Cmd
cmdtextRequired - The possible commands are `cancel` to request cancellation of the verification process, or `trigger_next_event` to advance to the next verification event (if any). Cancellation is only possible 30 seconds after the start of the verification request and before the second event (either TTS or SMS) has taken place.One of:
cancel,trigger_next_event(Trigger next event).
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"command": "cancel",
"status": "example"
}
}Get advanced number insight
Advanced Number Insight (sync).
Inputs
- Real time data
real_time_datatrue/false - [This parameter is deprecated] Real time data about the number. This is applicable to mobile numbers only.
- Number
numbertextRequired - A single phone number that you need insight about in national or international format.
- Country
countrytext - If a number does not have a country code or is uncertain, set the two-character country code. This code must be in ISO 3166-1 alpha-2 format and in upper case. For example, GB or US. If you set country and number is already in [E.164](https://en.wikipedia.org/wiki/E.164) format, country must match the country code in number.One of:
AD(Andorra),AE(United Arab Emirates),AF(Afghanistan),AG(Antigua & Barbuda),AI(Anguilla),AL(Albania),AM(Armenia),AO(Angola),AQ(Antarctica),AR(Argentina), and 240 more. - Cnam
cnamtrue/false - Indicates if the name of the person who owns the phone number should be looked up and returned in the response. Set to true to receive phone number owner name in the response. This feature is available only for US numbers but not all US numbers are supported. It incurs an additional charge for US numbers regardless of whether any information is returned. For non-US numbers and for non-approved users, the CNAM response attributes are omitted and no additional charges are incurred.Default:
false. - IP
iptext - This parameter is deprecated as we are no longer able to retrieve reliable IP data globally from carriers.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"caller_identity": {
"caller_name": "example",
"caller_type": "business",
"first_name": "example",
"last_name": "example"
},
"country_code": "example",
"country_code_iso3": "example",
"country_name": "example",
"country_prefix": "example",
"current_carrier": {
"country": "example",
"name": "example",
"network_code": "example",
"network_type": "mobile"
},
"international_format_number": "example",
"lookup_outcome": 0,
"lookup_outcome_message": "example",
"national_format_number": "example",
"original_carrier": {
"country": "example",
"name": "example",
"network_code": "example",
"network_type": "mobile"
},
"ported": "unknown",
"reachable": "unknown",
"real_time_data": {
"active_status": "example",
"handset_status": "example"
},
"refund_price": "example",
"remaining_balance": "example",
"request_id": "example",
"request_price": "example",
"roaming": {
"roaming_country_code": "example",
"roaming_network_code": "example",
"roaming_network_name": "example",
"status": "roaming"
},
"status": 0,
"status_message": "example",
"valid_number": "unknown"
}
}Get all country pricing
Retrieve outbound pricing for all countries.
Inputs
- Type
typetextRequired - The type of service you wish to retrieve data about: either `sms`, `sms-transit` or `voice`.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"count": "example",
"countries": []
}
}Get balance
Get Account Balance.
Inputs
None.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"autoReload": true,
"value": 1.0
}
}Get basic number insight
Basic Number Insight.
Inputs
- Number
numbertextRequired - A single phone number that you need insight about in national or international format.
- Country
countrytext - If a number does not have a country code or is uncertain, set the two-character country code. This code must be in ISO 3166-1 alpha-2 format and in upper case. For example, GB or US. If you set country and number is already in [E.164](https://en.wikipedia.org/wiki/E.164) format, country must match the country code in number.One of:
AD(Andorra),AE(United Arab Emirates),AF(Afghanistan),AG(Antigua & Barbuda),AI(Anguilla),AL(Albania),AM(Armenia),AO(Angola),AQ(Antarctica),AR(Argentina), and 240 more.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"country_code": "example",
"country_code_iso3": "example",
"country_name": "example",
"country_prefix": "example",
"international_format_number": "example",
"national_format_number": "example",
"request_id": "example",
"status": 0,
"status_message": "example"
}
}Get country pricing
Retrieve outbound pricing for a specific country.
Inputs
- Type
typetextRequired - The type of service you wish to retrieve data about: either `sms`, `sms-transit` or `voice`.
- Country
countrytextRequired - A two letter [country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). For example, `CA`.One of:
AD(Andorra),AE(United Arab Emirates),AF(Afghanistan),AG(Antigua & Barbuda),AI(Anguilla),AL(Albania),AM(Armenia),AO(Angola),AQ(Antarctica),AR(Argentina), and 240 more.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"countryCode": "example",
"countryDisplayName": "example",
"countryName": "example",
"currency": "example",
"defaultPrice": "example",
"dialingPrefix": "example",
"networks": []
}
}Get prefix pricing
Retrieve outbound pricing for a specific dialing prefix.
Inputs
- Type
typetextRequired - The type of service you wish to retrieve data about: either `sms`, `sms-transit` or `voice`.
- Prefix
prefixtextRequired - The numerical dialing prefix to look up pricing for. Examples include 44, 1 and so on.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"count": "example",
"countries": []
}
}Get standard number insight
Standard Number Insight.
Inputs
- Number
numbertextRequired - A single phone number that you need insight about in national or international format.
- Country
countrytext - If a number does not have a country code or is uncertain, set the two-character country code. This code must be in ISO 3166-1 alpha-2 format and in upper case. For example, GB or US. If you set country and number is already in [E.164](https://en.wikipedia.org/wiki/E.164) format, country must match the country code in number.One of:
AD(Andorra),AE(United Arab Emirates),AF(Afghanistan),AG(Antigua & Barbuda),AI(Anguilla),AL(Albania),AM(Armenia),AO(Angola),AQ(Antarctica),AR(Argentina), and 240 more. - Cnam
cnamtrue/false - Indicates if the name of the person who owns the phone number should be looked up and returned in the response. Set to true to receive phone number owner name in the response. This feature is available only for US numbers but not all US numbers are supported. It incurs an additional charge for US numbers regardless of whether any information is returned. For non-US numbers and for non-approved users, the CNAM response attributes are omitted and no additional charges are incurred.Default:
false.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"caller_identity": {
"caller_name": "example",
"caller_type": "business",
"first_name": "example",
"last_name": "example"
},
"caller_name": "example",
"caller_type": "business",
"current_carrier": {
"country": "example",
"name": "example",
"network_code": "example",
"network_type": "mobile"
},
"first_name": "example",
"last_name": "example",
"original_carrier": {
"country": "example",
"name": "example",
"network_code": "example",
"network_type": "mobile"
},
"ported": "unknown",
"refund_price": "example",
"remaining_balance": "example",
"request_price": "example"
}
}Get verification
Verify Search.
Inputs
- Request ID
request_idtextRequired - The `request_id` you received in the Verify Request Response. Required if `request_ids` not provided.
- Request IDS
request_idslist - More than one `request_id`. Each `request_id` is a new parameter in the Verify Search request. Required if `request_id` not provided.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"account_id": "example",
"checks": [],
"currency": "example",
"date_finalized": "example",
"date_submitted": "example",
"estimated_price_messages_sent": "example",
"events": [],
"first_event_date": "example",
"last_event_date": "example",
"number": "example",
"price": "example",
"request_id": "example",
"sender_id": "example",
"status": "IN PROGRESS"
}
}List owned numbers
List the numbers you own.
Inputs
- Application ID
application_idtext - The Application that you want to return the numbers for.
- Has application
has_applicationtrue/false - Set this optional field to `true` to restrict your results to numbers associated with an Application (any Application). Set to `false` to find all numbers not associated with any Application. Omit the field to avoid filtering on whether or not the number is assigned to an Application.
- Country
countrytext - The two character country code in ISO 3166-1 alpha-2 formatOne of:
AD(Andorra),AE(United Arab Emirates),AF(Afghanistan),AG(Antigua & Barbuda),AI(Anguilla),AL(Albania),AM(Armenia),AO(Angola),AQ(Antarctica),AR(Argentina), and 240 more. - Pattern
patterntext - The number pattern you want to search for. Use in conjunction with `search_pattern`.
- Search pattern
search_patternnumber - The strategy you want to use for matching: * `0` - Search for numbers that start with `pattern` (Note: all numbers are in E.164 format, so the starting pattern includes the country code, such as 1 for USA) * `1` - Search for numbers that contain `pattern` * `2` - Search for numbers that end with `pattern`One of:
0,1,2. Default:0. - Size
sizenumber - Page sizeFrom 1 to 100. Default:
10. - Index
indexnumber - Page indexDefault:
1.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"count": 1,
"numbers": []
}
}Search available numbers
Search available numbers.
Inputs
- Country
countrytextRequired - The two character country code to filter on (in ISO 3166-1 alpha-2 format)One of:
AD(Andorra),AE(United Arab Emirates),AF(Afghanistan),AG(Antigua & Barbuda),AI(Anguilla),AL(Albania),AM(Armenia),AO(Angola),AQ(Antarctica),AR(Argentina), and 240 more. - Type
typetext - Set this parameter to filter the type of number, such as mobile or landlineOne of:
landline,mobile-lvn,landline-toll-free. - Pattern
patterntext - The number pattern you want to search for. Use in conjunction with `search_pattern`.
- Search pattern
search_patternnumber - The strategy you want to use for matching: * `0` - Search for numbers that start with `pattern` (Note: all numbers are in E.164 format, so the starting pattern includes the country code, such as 1 for USA) * `1` - Search for numbers that contain `pattern` * `2` - Search for numbers that end with `pattern`One of:
0,1,2. Default:0. - Features
featurestext - Available features are `SMS`, `VOICE` and `MMS`. To look for numbers that support multiple features, use a comma-separated value: `SMS,MMS,VOICE`.One of:
SMS,VOICE,SMS,VOICE,MMS,SMS,MMS,VOICE,MMS,SMS,MMS,VOICE. - Size
sizenumber - Page sizeFrom 1 to 100. Default:
10. - Index
indexnumber - Page indexDefault:
1.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"count": 1,
"numbers": []
}
}Send sms
Send an SMS.
Inputs
- Sender
sendertextRequired - The name or number the message should be sent from. Alphanumeric senderID's are not supported in all countries, see [Global Messaging](https://developer.vonage.com/messaging/sms/guides/global-messaging#country-specific-features) for more details. If alphanumeric, spaces will be ignored. Numbers are specified in E.164 format.
- To
totextRequired - The number that the message should be sent to. Numbers are specified in E.164 format.
- Text
texttextRequired - The body of the message being sent. If your message contains characters that can be encoded according to the GSM Standard and Extended tables then you can set the `type` to `text`. If your message contains characters outside this range, then you will need to set the `type` to `unicode`.
- Ttl
ttlnumber - **Advanced**: The duration in milliseconds the delivery of an SMS will be attempted. By default Vonage attempts delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours. We recommend this value should be kept at its default or at least 30 minutes.From 20000 to 604800000. Default:
259200000. - Status report req
status_report_reqtrue/false - **Advanced**: Boolean indicating if you like to receive a [Delivery Receipt](/messaging/sms/building-blocks/receive-a-delivery-receipt).Default:
true. - Callback
callbacktext - **Advanced**: The webhook endpoint the delivery receipt for this sms is sent to. This parameter overrides the webhook endpoint you set in Dashboard. Max 100 characters.
- Type
typetext - **Advanced**: The format of the message bodyOne of:
text,unicode. Default:text. - Client ref
client_reftext - **Advanced**: You can optionally include your own reference of up to 100 characters.
- Entity ID
entity_idtext - **Advanced**: A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the [Country-Specific Outbound SMS Features](https://api.support.vonage.com/hc/en-us/articles/115011781468)
- Content ID
content_idtext - **Advanced**: A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the [Country-Specific Outbound SMS Features](https://api.support.vonage.com/hc/en-us/articles/115011781468)
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"message-count": "example",
"messages": []
}
}Start payment verification
PSD2 (Payment Services Directive 2) Request.
Inputs
- Number
numbertextRequired - The mobile or landline phone number to verify. Unless you are setting `country` explicitly, this number must be in [E.164](https://en.wikipedia.org/wiki/E.164) format.
- Country
countrytext - If you do not provide `number` in international format or you are not sure if `number` is correctly formatted, specify the two-character country code in `country`. Verify will then format the number for you.One of:
AD(Andorra),AE(United Arab Emirates),AF(Afghanistan),AG(Antigua & Barbuda),AI(Anguilla),AL(Albania),AM(Armenia),AO(Angola),AQ(Antarctica),AR(Argentina), and 240 more. - Payee
payeetextRequired - An alphanumeric string to indicate to the user the name of the recipient that they are confirming a payment to.
- Amount
amountnumberRequired - The decimal amount of the payment to be confirmed, in Euros
- Code length
code_lengthnumber - The length of the verification code.One of:
4,6. Default:4. - Lg
lgtext - By default, the SMS or text-to-speech (TTS) message is generated in the locale that matches the `number`. For example, the text message or TTS message for a `33*` number is sent in French. Use this parameter to explicitly control the language used. *Note: Voice calls in English for `bg-bg`, `ee-et`, `ga-ie`, `lv-lv`, `lt-lt`, `mt-mt`, `sk-sk`, `sk-si`One of:
en-gb,bg-bg,cs-cz,da-dk,de-de,ee-et,el-gr,es-es,fi-fi,fr-fr, and 11 more. Default:en-gb. - Pin expiry
pin_expirynumber - How long the generated verification code is valid for, in seconds. When you specify both `pin_expiry` and `next_event_wait` then `pin_expiry` must be an integer multiple of `next_event_wait` otherwise `pin_expiry` is defaulted to equal next_event_wait. See [changing the event timings](https://developer.nexmo.com/verify/verify-v1/guides/changing-default-timings).From 60 to 3600. Default:
300. - Next event wait
next_event_waitnumber - Specifies the wait time in seconds between attempts to deliver the verification code.From 60 to 900. Default:
300. - Verification sequence
verification_workflow_idnumber - Selects the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your user. For example, an id of 1 identifies the workflow SMS - TTS - TTS. For a list of all workflows and their associated ids, please visit the [developer portal](https://developer.nexmo.com/verify/verify-v1/guides/workflows-and-events).One of:
1,2,3,4,5,6,7. Default:1.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"request_id": "example",
"status": "example"
}
}Start verification
Request a Verification.
Inputs
- Number
numbertextRequired - The mobile or landline phone number to verify. Unless you are setting `country` explicitly, this number must be in [E.164](https://en.wikipedia.org/wiki/E.164) format.
- Country
countrytext - If you do not provide `number` in international format or you are not sure if `number` is correctly formatted, specify the two-character country code in `country`. Verify will then format the number for you.One of:
AD(Andorra),AE(United Arab Emirates),AF(Afghanistan),AG(Antigua & Barbuda),AI(Anguilla),AL(Albania),AM(Armenia),AO(Angola),AQ(Antarctica),AR(Argentina), and 240 more. - Brand
brandtextRequired - An 18-character alphanumeric string you can use to personalize the verification request SMS body, to help users identify your company or application name. For example: "Your `Acme Inc` PIN is ..."
- Sender ID
sender_idtext - An 11-character alphanumeric string that represents the [identity of the sender](https://developer.nexmo.com/messaging/sms/guides/custom-sender-id) of the verification request. Depending on the destination of the phone number you are sending the verification SMS to, restrictions might apply.Default:
VERIFY. - Code length
code_lengthnumber - The length of the verification code.One of:
4,6. Default:4. - Lg
lgtext - By default, the SMS or text-to-speech (TTS) message is generated in the locale that matches the `number`. For example, the text message or TTS message for a `33*` number is sent in French. Use this parameter to explicitly control the language used for the Verify request. A list of languages is available:One of:
ar-xa,cs-cz,cy-cy,cy-gb,da-dk,de-de,el-gr,en-au,en-gb,en-in, and 29 more. Default:en-us. - Pin expiry
pin_expirynumber - How long the generated verification code is valid for, in seconds. When you specify both `pin_expiry` and `next_event_wait` then `pin_expiry` must be an integer multiple of `next_event_wait` otherwise `pin_expiry` is defaulted to equal next_event_wait. See [changing the event timings](https://developer.nexmo.com/verify/verify-v1/guides/changing-default-timings).From 60 to 3600. Default:
300. - Next event wait
next_event_waitnumber - Specifies the wait time in seconds between attempts to deliver the verification code.From 60 to 900. Default:
300. - Verification sequence
verification_workflow_idnumber - Selects the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your user. For example, an id of 1 identifies the workflow SMS - TTS - TTS. For a list of all workflows and their associated ids, please visit the [developer portal](https://developer.nexmo.com/verify/verify-v1/guides/workflows-and-events).One of:
1,2,3,4,5,6,7. Default:1. - Pin code
pin_codetext - A custom PIN to send to the user. If a PIN is not provided, Verify will generate a random PIN for you. This feature is not enabled by default - please discuss with your Account Manager if you would like it enabled. If this feature is not enabled on your account, error status `20` will be returned.From 4 to 10.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"request_id": "example",
"status": "example"
}
}Update account settings
Change Account Settings.
Inputs
- MoCallBackUrl
moCallBackUrltext - The default webhook URL for inbound SMS. If an SMS is received at a Vonage number that does not have its own inbound SMS webhook configured, Vonage makes a request here. Send an empty string to unset this value.
- DrCallBackUrl
drCallBackUrltext - The webhook URL that Vonage makes a request to when a delivery receipt is available for an SMS sent by one of your Vonage numbers. Send an empty string to unset this value.
- HttpForwardMethod
httpForwardMethodtext - The HTTP method to use when making requests to the callback URLs.One of:
GET_QUERY_PARAMS(Get query params),POST_QUERY_PARAMS(Post query params),POST_JSON(Post json).
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"dr-callback-url": "example",
"max-calls-per-second": 1,
"max-inbound-request": 1,
"max-outbound-request": 1,
"mo-callback-url": "example"
}
}Update number
Update a number.
Inputs
- Country
countrytextRequired - The two character country code in ISO 3166-1 alpha-2 formatOne of:
AD(Andorra),AE(United Arab Emirates),AF(Afghanistan),AG(Antigua & Barbuda),AI(Anguilla),AL(Albania),AM(Armenia),AO(Angola),AQ(Antarctica),AR(Argentina), and 240 more. - Msisdn
msisdntextRequired - An available inbound virtual number.
- App ID
app_idtext - The Application that will handle inbound traffic to this number.
- MoHttpUrl
moHttpUrltext - An URL-encoded URI to the webhook endpoint that handles inbound messages. Your webhook endpoint must be active before you make this request. Vonage makes a `GET` request to the endpoint and checks that it returns a `200 OK` response. Set this parameter's value to an empty string to remove the webhook.
- MoSmppSysType
moSmppSysTypetext - The associated system type for your SMPP client
- VoiceCallbackType
voiceCallbackTypetext - Specify whether inbound voice calls on your number are forwarded to a SIP or a telephone number. This must be used with the `voiceCallbackValue` parameter. If set, `sip` or `tel` are prioritized over the Voice capability in your Application. *Note: The `app` value is deprecated and will be removed in future.*One of:
sip,tel,app. - VoiceCallbackValue
voiceCallbackValuetext - A SIP URI or telephone number. Must be used with the `voiceCallbackType` parameter.
- VoiceStatusCallback
voiceStatusCallbacktext - A webhook URI for Vonage to send a request to when a call ends
- MessagesCallbackType
messagesCallbackTypetext - DEPRECATED - We recommend that you use `app_id` instead. Specifies the Messages webhook type (always `app`) associated with this number and must be used with the `messagesCallbackValue` parameter.One of:
app. - MessagesCallbackValue
messagesCallbackValuetext - DEPRECATED - We recommend that you use `app_id` instead. Specifies the Application ID of your Messages application. It must be used with the `messagesCallbackType` parameter.
Outputs
dataobject- The result returned by Vonage (Nexmo).
Example output
{
"data": {
"error-code": "example",
"error-code-label": "example"
}
}