{
   "openapi": "3.0.0",
   "info": {
      "version": "1.5.0",
      "title": "SMS API",
      "x-metaTitle": "Vonage SMS API Reference | Vonage API Documentation",
      "x-metaDescription": "Get started with the Vonage SMS API, a powerful tool for automating text message communications. Learn more in Vonage's API documentation.",
      "description": "With the SMS API you can send SMS from your account and lookup messages both messages that you've sent as well as messages sent to your virtual numbers. Numbers are specified in E.164 format. More SMS API documentation is at <https://developer.vonage.com/messaging/sms/overview>",
      "contact": {
         "name": "Vonage DevRel",
         "email": "devrel@vonage.com",
         "url": "https://developer.vonage.com/"
      }
   },
   "servers": [
      {
         "url": "https://rest.nexmo.com"
      }
   ],
   "security": [
      {
         "basicAuth": []
      }
   ],
   "paths": {
      "/sms/{format}": {
         "post": {
            "operationId": "send-an-sms",
            "summary": "Send an SMS",
            "description": "Send an outbound SMS from your Vonage account",
            "parameters": [
               {
                  "name": "format",
                  "description": "The format of the response",
                  "in": "path",
                  "required": true,
                  "schema": {
                     "example": "json",
                     "type": "string",
                     "enum": [
                        "json",
                        "xml"
                     ],
                     "default": "json"
                  }
               }
            ],
            "requestBody": {
               "required": true,
               "content": {
                  "application/x-www-form-urlencoded": {
                     "schema": {
                        "$ref": "#/components/schemas/NewMessage"
                     }
                  }
               }
            },
            "responses": {
               "200": {
                  "description": "Success",
                  "content": {
                     "application/json": {
                        "schema": {
                           "oneOf": [
                              {
                                 "$ref": "#/components/schemas/SMS"
                              },
                              {
                                 "$ref": "#/components/schemas/Error"
                              }
                           ]
                        }
                     },
                     "text/xml": {
                        "schema": {
                           "oneOf": [
                              {
                                 "$ref": "#/components/schemas/SMSXml"
                              },
                              {
                                 "$ref": "#/components/schemas/ErrorXml"
                              }
                           ]
                        }
                     }
                  }
               }
            },
            "callbacks": {
               "delivery-receipt": {
                  "{$request.body#/callback}": {
                     "post": {
                        "summary": "Delivery Receipt",
                        "operationId": "delivery-receipt",
                        "description": "The following are parameters sent in as a [delivery receipt](/messaging/sms/guides/delivery-receipts) callback. You can subscribe to [webhooks](/getting-started/concepts/webhooks) to receive notification when the delivery status of an SMS that you have sent with Vonage changes.",
                        "requestBody": {
                           "required": true,
                           "content": {
                              "application/json": {
                                 "schema": {
                                    "$ref": "#/components/schemas/DeliveryReceipt"
                                 }
                              }
                           }
                        },
                        "responses": {
                           "200": {
                              "description": "Your server returns this code if it accepts the callback"
                           }
                        }
                     }
                  }
               }
            }
         }
      }
   },
   "x-webhooks": {
      "inbound-sms": {
         "{$request.body#/callback}": {
            "post": {
               "summary": "Inbound SMS",
               "operationId": "inbound-sms",
               "x-example-path": "/webhooks/inbound-sms",
               "description": "If you rent one or more virtual numbers from Vonage, inbound messages to that number are sent to your [webhook endpoint](/getting-started/concepts/webhooks).\n\nWhen you receive an inbound message, you must send a 2xx response. If you do not send a 2xx response Vonage will resend the inbound message for the next 24 hours.\n",
               "requestBody": {
                  "required": true,
                  "content": {
                     "application/json": {
                        "schema": {
                           "$ref": "#/components/schemas/InboundMessage"
                        }
                     }
                  }
               },
               "responses": {
                  "200": {
                     "description": "Your server returns this code if it accepts the callback"
                  }
               }
            }
         }
      }
   },
   "components": {
      "schemas": {
         "NewMessage": {
            "required": [
               "from",
               "to",
               "text"
            ],
            "properties": {
               "api_key": {
                  "description": "Your API key. Only required if setting `sig`.",
                  "type": "string",
                  "minLength": 8,
                  "maxLength": 8,
                  "example": "abcd1234"
               },
               "sig": {
                  "description": "The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See [Signing Requests](https://developer.vonage.com/getting-started/concepts/signing-messages) for more details.\nNote: **DO NOT** set an `Authorization` header when using `sig`.\n",
                  "type": "string",
                  "minLength": 16,
                  "maxLength": 60,
                  "example": "5d41402abc4b2a76b9719d911017c592"
               },
               "timestamp": {
                  "description": "An integer containing the number of seconds since the epoch (this is sometimes also known as UNIX time). Only required if setting `sig`. See [Signing Requests](https://developer.vonage.com/getting-started/concepts/signing-messages) for more details.",
                  "type": "integer",
                  "example": 1617187200
               },
               "from": {
                  "description": "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.",
                  "type": "string",
                  "example": "AcmeInc"
               },
               "to": {
                  "description": "The number that the message should be sent to. Numbers are specified in E.164 format.",
                  "type": "string",
                  "minLength": 7,
                  "maxLength": 15,
                  "pattern": "\\d{7,15}",
                  "example": "447700900000"
               },
               "text": {
                  "description": "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`.",
                  "type": "string",
                  "example": "Hello World!"
               },
               "ttl": {
                  "description": "**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.",
                  "type": "integer",
                  "example": 900000,
                  "default": 259200000,
                  "minimum": 20000,
                  "maximum": 604800000
               },
               "status-report-req": {
                  "description": "**Advanced**: Boolean indicating if you like to receive a [Delivery Receipt](/messaging/sms/building-blocks/receive-a-delivery-receipt).",
                  "type": "boolean",
                  "example": false,
                  "default": true
               },
               "callback": {
                  "description": "**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": "string",
                  "example": "https://example.com/sms-dlr"
               },
               "message-class": {
                  "description": "**Advanced**: The Data Coding Scheme value of the message",
                  "type": "integer",
                  "enum": [
                     0,
                     1,
                     2,
                     3
                  ]
               },
               "type": {
                  "description": "**Advanced**: The format of the message body",
                  "type": "string",
                  "enum": [
                     "text",
                     "binary",
                     "unicode"
                  ],
                  "example": "text",
                  "default": "text"
               },
               "body": {
                  "description": "**Advanced**: Hex encoded binary data. Depends on `type` parameter having the value `binary`.",
                  "type": "string",
                  "example": "0011223344556677"
               },
               "udh": {
                  "description": "**Advanced**: Your custom Hex encoded [User Data Header](https://en.wikipedia.org/wiki/User_Data_Header). Depends on `type` parameter having the value `binary`.",
                  "type": "string",
                  "example": "06050415811581"
               },
               "protocol-id": {
                  "description": "**Advanced**: The value of the [protocol identifier](https://en.wikipedia.org/wiki/GSM_03.40#Protocol_Identifier) to use. Ensure that the value is aligned with `udh`.",
                  "type": "integer",
                  "example": 127
               },
               "client-ref": {
                  "description": "**Advanced**: You can optionally include your own reference of up to 100 characters.",
                  "type": "string",
                  "example": "my-personal-reference"
               },
               "account-ref": {
                  "description": "**Advanced**: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email [support](mailto:${CUSTOMER_SUPPORT_EMAIL})",
                  "type": "string",
                  "example": "customer1234"
               },
               "entity-id": {
                  "description": "**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)",
                  "type": "string",
                  "example": "1101456324675322134"
               },
               "content-id": {
                  "description": "**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)",
                  "type": "string",
                  "example": "1107457532145798767"
               },
               "trusted-number": {
                  "description": "Setting this parameter to `true` overrides, on a per-message basis, any protections set up via [Fraud Defender](https://developer.vonage.com/en/fraud-defender/overview) (Traffic Rules, SMS Burst Protection, AIT Protection).\n\nThis parameter only has any effect for accounts subscribed to Fraud Defender Premium.\n",
                  "type": "boolean",
                  "example": true,
                  "default": false
               },
               "pool-id": {
                  "description": "The ID of the Number Pool to use as the sender of this message. If specified, a number from the pool will be used as the `from` number. \nThe `from` parameter is still required even when specifying a `pool-id` and will be used as a fall-back if the number pool cannot be used.\nSee the [Number Pools documentation](https://developer.vonage.com/numbers/number-pools-api/overview) for more information.\n",
                  "type": "string",
                  "example": "abc123"
               }
            }
         },
         "Error": {
            "description": "Error",
            "type": "object",
            "properties": {
               "message-count": {
                  "type": "string",
                  "description": "The amount of messages in the request",
                  "example": "1"
               },
               "messages": {
                  "type": "array",
                  "items": {
                     "$ref": "#/components/schemas/ErrorMessage"
                  }
               }
            }
         },
         "ErrorXml": {
            "type": "object",
            "description": "Error",
            "xml": {
               "name": "mt-submission-response"
            },
            "properties": {
               "messages": {
                  "type": "array",
                  "items": {
                     "$ref": "#/components/schemas/ErrorMessage"
                  }
               }
            }
         },
         "ErrorMessage": {
            "type": "object",
            "xml": {
               "name": "message"
            },
            "properties": {
               "status": {
                  "type": "string",
                  "description": "The error status of the message",
                  "example": "2"
               },
               "error-text": {
                  "type": "string",
                  "description": "The description of the error",
                  "example": "Missing to param"
               }
            }
         },
         "SMS": {
            "description": "Message sent",
            "type": "object",
            "properties": {
               "message-count": {
                  "type": "string",
                  "description": "The amount of messages in the request",
                  "example": "1"
               },
               "messages": {
                  "type": "array",
                  "items": {
                     "$ref": "#/components/schemas/Message"
                  }
               }
            }
         },
         "SMSXml": {
            "type": "object",
            "description": "Message sent",
            "xml": {
               "name": "mt-submission-response"
            },
            "properties": {
               "messages": {
                  "x-skip-response-description": true,
                  "type": "array",
                  "items": {
                     "$ref": "#/components/schemas/Message"
                  },
                  "properties": {
                     "count": {
                        "type": "integer",
                        "example": 1,
                        "xml": {
                           "attribute": true
                        }
                     }
                  }
               }
            }
         },
         "InboundMessage": {
            "type": "object",
            "required": [
               "msisdn",
               "to",
               "messageId",
               "text",
               "type",
               "keyword",
               "message-timestamp",
               "api-key"
            ],
            "properties": {
               "api-key": {
                  "type": "string",
                  "description": "The Vonage API Key of the receiving account.",
                  "example": "abcd1234"
               },
               "msisdn": {
                  "type": "string",
                  "description": "The phone number that this inbound message was sent from. Numbers are specified in E.164 format.",
                  "example": "447700900001"
               },
               "to": {
                  "type": "string",
                  "description": "The phone number the message was sent to. **This is your virtual number**. Numbers are specified in E.164 format.",
                  "example": "447700900000"
               },
               "messageId": {
                  "type": "string",
                  "description": "The ID of the message",
                  "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
               },
               "text": {
                  "type": "string",
                  "description": "The message body for this inbound message.",
                  "example": "Hello world"
               },
               "type": {
                  "type": "string",
                  "description": "Possible values are:\n\n  - `text` - standard text.\n  - `unicode` - URLencoded   unicode  . This is valid for standard GSM, Arabic, Chinese, double-encoded characters and so on.\n  - `binary` - a binary message.\n",
                  "example": "text"
               },
               "keyword": {
                  "type": "string",
                  "description": "The first word in the message body. Converted to upper case.",
                  "example": "HELLO"
               },
               "message-timestamp": {
                  "description": "The time when Vonage started to push this Delivery Receipt to your webhook endpoint.",
                  "type": "string",
                  "example": "2020-01-01 12:00:00"
               },
               "timestamp": {
                  "description": "A unix timestamp representation of message-timestamp.",
                  "type": "string",
                  "example": "1578787200"
               },
               "nonce": {
                  "type": "string",
                  "description": "A random string that forms part of the signed set of parameters, it adds an extra element of unpredictability into the signature for the request. You use the nonce and timestamp parameters with your shared secret to calculate and validate the signature for inbound messages.",
                  "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
               },
               "concat": {
                  "type": "string",
                  "description": "True - if this is a concatenated message. This field does not exist if it is a single message",
                  "example": "true"
               },
               "concat-ref": {
                  "type": "string",
                  "description": "The transaction reference. All parts of this message share this value.",
                  "example": "1"
               },
               "concat-total": {
                  "type": "string",
                  "description": "The number of parts in this concatenated message.",
                  "example": "3"
               },
               "concat-part": {
                  "type": "string",
                  "description": "The number of this part in the message. Counting starts at 1.",
                  "example": "2"
               },
               "data": {
                  "type": "string",
                  "format": "binary",
                  "description": "The content of this message, if type is binary."
               },
               "udh": {
                  "type": "string",
                  "description": "The hex encoded User Data Header, if type is binary"
               }
            }
         },
         "Message": {
            "type": "object",
            "properties": {
               "to": {
                  "type": "string",
                  "description": "The number the message was sent to. Numbers are specified in E.164 format.",
                  "example": "447700900000"
               },
               "message-id": {
                  "type": "string",
                  "description": "The ID of the message",
                  "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
                  "xml": {
                     "name": "messageId"
                  }
               },
               "status": {
                  "type": "string",
                  "description": "The status of the message. See [Troubleshooting Failed SMS](/messaging/sms/guides/troubleshooting-sms).",
                  "example": "0"
               },
               "remaining-balance": {
                  "type": "string",
                  "description": "Your estimated remaining balance",
                  "example": "3.14159265",
                  "xml": {
                     "name": "remainingBalance"
                  }
               },
               "message-price": {
                  "type": "string",
                  "description": "The estimated cost of the message",
                  "example": "0.03330000",
                  "xml": {
                     "name": "messagePrice"
                  }
               },
               "network": {
                  "type": "string",
                  "description": "The estimated ID of the network of the recipient",
                  "example": "12345"
               },
               "client-ref": {
                  "description": "If a `client-ref` was included when sending the SMS, this field will be included and hold the value that was sent.",
                  "type": "string",
                  "example": "my-personal-reference"
               },
               "account-ref": {
                  "type": "string",
                  "description": "**Advanced**: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email [support](mailto:${CUSTOMER_SUPPORT_EMAIL})",
                  "example": "customer1234"
               }
            }
         },
         "DeliveryReceipt": {
            "type": "object",
            "properties": {
               "msisdn": {
                  "type": "string",
                  "description": "The number the message was sent to. Numbers are specified in E.164 format.",
                  "example": "447700900000"
               },
               "to": {
                  "type": "string",
                  "description": "The SenderID you set in `from` in your request.",
                  "example": "AcmeInc"
               },
               "network-code": {
                  "type": "string",
                  "description": "The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with.",
                  "example": "12345"
               },
               "messageId": {
                  "type": "string",
                  "description": "The Vonage ID for this message.",
                  "example": "0A0000001234567B"
               },
               "price": {
                  "type": "string",
                  "description": "The cost of the message",
                  "example": "0.03330000"
               },
               "status": {
                  "type": "string",
                  "description": "A code that explains where the message is in the delivery process.",
                  "example": "delivered",
                  "x-possible-values": [
                     "delivered",
                     "expired",
                     "failed",
                     "rejected",
                     "accepted",
                     "buffered",
                     "unknown"
                  ]
               },
               "scts": {
                  "type": "string",
                  "description": "When the DLR was received from the carrier in the following format `YYMMDDHHMM`. For example, `2001011400` is at `2020-01-01 14:00`",
                  "example": "2001011400"
               },
               "err-code": {
                  "type": "string",
                  "description": "The status of the request. Will be a non `0` value if there has been an error, or if the status is unknown. See the [Delivery Receipt documentation](/messaging/sms/guides/delivery-receipts#dlr-error-codes) for more details",
                  "example": "0"
               },
               "api-key": {
                  "type": "string",
                  "description": "The API key that sent the SMS. This is useful when multiple accounts are sending webhooks to the same endpoint.",
                  "example": "abcd1234"
               },
               "message-timestamp": {
                  "description": "The time when Vonage started to push this Delivery Receipt to your webhook endpoint.",
                  "type": "string",
                  "example": "2020-01-01 12:00:00"
               }
            }
         }
      },
      "securitySchemes": {
         "basicAuth": {
            "type": "http",
            "scheme": "basic"
         }
      }
   },
   "x-errors": {
      "1": {
         "description": "Throttled. You are sending SMS faster than the account limit.",
         "resolution": "Refer to [What is the Throughput Limit for Outbound SMS?](https://api.support.vonage.com/hc/en-us/articles/203993598) for more information."
      },
      "2": {
         "description": "Missing Parameters. Your request is missing one of the required parameters `from`, `to`, `api_key`, `api_secret` or `text`.",
         "resolution": "Check your parameters and try again."
      },
      "3": {
         "description": "Invalid Parameters. The value of one or more parameters is invalid.",
         "resolution": "Check your parameters and try again."
      },
      "4": {
         "description": "Invalid Credentials. Your API key and/or secret are incorrect, invalid or disabled.",
         "resolution": "Visit the [Dashboard](${CUSTOMER_DASHBOARD_URL}) and check your credentials."
      },
      "5": {
         "description": "Internal Error. An error has occurred in the platform whilst processing this message.",
         "resolution": "If the error persists, contact [support](mailto:${CUSTOMER_SUPPORT_EMAIL})."
      },
      "6": {
         "description": "Invalid Message. The platform was unable to process this message, for example, an un-recognized number prefix.",
         "resolution": "N/A"
      },
      "7": {
         "description": "Number Barred. The number you are trying to send messages to is blacklisted and may not receive them.",
         "resolution": "N/A"
      },
      "8": {
         "description": "Partner Account Barred. Your Vonage account has been suspended.",
         "resolution": "Contact [support](mailto:${CUSTOMER_SUPPORT_EMAIL})."
      },
      "9": {
         "description": "Partner Quota Violation. You do not have sufficient credit to send the message.",
         "resolution": "Top-up and retry."
      },
      "10": {
         "description": "Too Many Existing Binds. The number of simultaneous connections to the platform exceeds your account allocation.",
         "resolution": "Back-off and retry."
      },
      "11": {
         "description": "Account Not Enabled For HTTP. This account is not provisioned for the SMS API.",
         "resolution": "This error usually indicates that you should use SMPP instead."
      },
      "12": {
         "description": "Message Too Long. The message length exceeds the maximum allowed.",
         "resolution": "Send shorter messages."
      },
      "14": {
         "description": "Invalid Signature. The signature supplied could not be verified.",
         "resolution": "Check the [documentation for signing messages](/getting-started/concepts/signing-messages) or use one of the [SDKs](/tools) to handle the signing."
      },
      "15": {
         "description": "Invalid Sender Address. You are using a non-authorized sender ID in the `from` field.",
         "resolution": "This is most commonly seen in North America, where a Vonage long virtual number or short code is required."
      },
      "17": {
         "description": "Message Blocked by Provider. The messaging provider has chosen to block this message. This may be due to content or restrictions imposed by the provider.",
         "resolution": "N/A"
      },
      "22": {
         "description": "Invalid Network Code. The network code supplied was either not recognized, or does not match the country of the destination address.",
         "resolution": "Check the network code or remove it from your request."
      },
      "23": {
         "description": "Invalid Callback Url. The callback URL supplied was either too long or contained illegal characters.",
         "resolution": "Supply a valid URL for the callback."
      },
      "29": {
         "description": "Non-Whitelisted Destination. Your Vonage account is still in demo mode. While in demo mode you must add target numbers to your whitelisted destination list.",
         "resolution": "Top-up your account to remove this limitation."
      },
      "32": {
         "description": "Signature And API Secret Disallowed. A signed request may not also present an `api_secret`.",
         "resolution": "Remove the API secret from your request, or don't sign the message."
      },
      "33": {
         "description": "Number De-activated. The number you are trying to send messages to is de-activated and may not receive them.",
         "resolution": "N/A"
      }
   }
}