openapi: 3.2.0
info:
  title: SMS-Vonage Send SMS API
  version: v1.1.1
  termsOfService: https://developer.kpn.com/legal
  contact:
    name: API Support
    email: api_developer@kpn.com
    url: https://developer.kpn.com/support
  description: "Vonage's SMS API allows you to send and receive text messages to users around the globe through simple RESTful APIs.\n  \n  * Programmatically send and receive high volume of SMS anywhere in the world.\n  * Build apps that scale with the web technologies that you are already using.\n  * Send SMS with low latency and high delivery rates.\n  * Receive SMS for free using SMS-enabled local numbers in countries around the world.\n  * Only pay for what you use, nothing more.\n\n  \n## [Source view](https://app.swaggerhub.com/apis/kpn/sms-nexmo/)<br/> [Documentation view](https://app.swaggerhub.com/apis-docs/kpn/sms-nexmo/)\n---\n## [KPN Developer](https://developer.kpn.com/)<br/> [Getting Started](https://developer.kpn.com/getting-started)\n\n ---"
servers:
- url: https://api-prd.kpn.com/communication/nexmo/sms
tags:
- name: Send SMS
paths:
  /send:
    post:
      summary: Send SMS
      tags:
      - Send SMS
      description: Send an outbound SMS
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendSMSResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - OAuth2: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                from:
                  type: string
                  description: "The name or number the message should be sent from. Alphanumeric senderID's are not supported in all countries, see Global Messaging for more details. If alphanumeric, spaces will be ignored. Numbers are specified in E.164 format. You can use any alphanumeric string up to 11 characters (or up to 15 numeric characters).  It is recommended to send at least \"3\" characters (in case of alphanumeric), as it might show differently on different mobile devices. Moreover, alphanumeric cannot contain spaces as well.\n  example: `AcmeInc`.Note: If the value in your from parameter does not obey these rules it might be modified in transit or not delivered at all."
                to:
                  type: string
                  description: "The number that the message should be sent to. Numbers are specified in E.164 format.\n  minLength: 7\n  maxLength: 15\n  pattern: '\\d{7,15}'\n  example: 447700900000              "
                text:
                  type: string
                  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`.\n  example: Hello World! "
                ttl:
                  type: integer
                  description: "**Advanced**: The duration in milliseconds the delivery of an SMS will be attempted.§§ By default Vonage attempt 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.\n  minimum: 20000\n  maximum: 604800000\n  example: 900000"
                status-report-req:
                  type: boolean
                  default: false
                  description: '**Advanced**: Boolean indicating if you like to receive a [Delivery Receipt](/messaging/sms/building-blocks/receive-a-delivery-receipt).'''
                callback:
                  type: string
                  description: "**Advanced**: The webhook endpoint the delivery receipt for this sms is sent to. This parameter overrides the webhook endpoint you set in Dashboard.\n  "
                message-class:
                  type: integer
                  enum:
                  - 0
                  - 1
                  - 2
                  - 3
                  description: '**Advanced**: The Data Coding Scheme value of the message'
                type:
                  type: string
                  enum:
                  - text
                  - binary
                  - wappush
                  - unicode
                  - vcal
                  - vcard
                  description: '**Advanced**: The format of the message body'''' example: text'
                vcard:
                  type: string
                  format: vcard
                  description: '**Advanced**: A business card in [vCard format](https://en.wikipedia.org/wiki/VCard). Depends on `type` parameter having the value `vcard`.'
                vcal:
                  type: string
                  format: vcal
                  description: '**Advanced**: A calendar event in [vCal format](https://en.wikipedia.org/wiki/VCal). Depends on `type` parameter having the value `vcal`.'
                body:
                  type: string
                  description: '**Advanced**: Hex encoded binary data. Depends on `type` parameter having the value `binary`.'
                udh:
                  type: string
                  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`.'
                protocol-id:
                  type: integer
                  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`.'
                title:
                  type: string
                  description: '**Advanced**: The title for a wappush SMS. Depends on `type` parameter having the value `wappush`.   '
                url:
                  type: string
                  description: '**Advanced**: The URL of your website. Depends on `type` parameter having the value `wappush`.'
                validity:
                  type: string
                  description: '**Advanced**: The availability for an SMS in milliseconds. Depends on `type` parameter having the value `wappush`.'
                client-ref:
                  type: string
                  description: '**Advanced**: You can optionally include your own reference of up to 40 characters.'
              required:
              - from
              - to
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        transactionId:
          type: string
          description: transaction id of the the request
          title: Transaction ID
        status:
          type: string
          description: Status
          title: Status
        name:
          type: string
          description: Error name
          title: Error name
        message:
          type: string
          description: Error message
          title: Error message
        info:
          type: string
          description: Additional information about error
          title: Info
    SendSMSResponse:
      type: object
      properties:
        message-count:
          type: integer
          description: The amount of messages in the request
          example: 1
        messages:
          type: array
          items:
            $ref: '#/components/schemas/SendSMSResponseMessage'
    SendSMSResponseMessage:
      type: object
      properties:
        to:
          type: string
          description: The number the message was sent to
          example: '447700900000'
        message-id:
          type: string
          description: The ID of the message
          example: 0A0000000123ABCD1
        status:
          type: string
          description: "Code | Description\n   -- | --\n   '1' | You have exceeded the submission capacity allowed on this account. Please wait and retry.\n   '2' | Your request is incomplete and missing some mandatory parameters.\n   '3'\t| The value of one or more parameters is invalid.\n   '4'\t| The api_key / api_secret you supplied is either invalid or disabled.\n   '5'\t| There was an error processing your request in the Platform.\n   '6' | The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number.\n   '7'\t| The number you are trying to submit to is blacklisted and may not receive messages.\n   '8' | The api_key you supplied is for an account that has been barred from submitting messages.\n   '9' | Your pre-paid account does not have sufficient credit to process this message.\n   '11' | This account is not provisioned for REST submission, you should use SMPP instead.\n   '12' | The length of udh and body was greater than 140 octets for a binary type SMS request.\n   '13' |\tMessage was not submitted because there was a communication failure.\n   '14' |\tMessage was not submitted due to a verification failure in the submitted signature.\n   '15' |\tDue to local regulations, the SenderID you set in from in the request was not accepted. Please check the Global messaging section.\n   '16' |\tInvalid TTL\tThe value of ttl in your request was invalid.\n   '19' |\tYour request makes use of a facility that is not enabled on your account.\n   '20' |\tThe value of message-class in your request was out of range. See https://en.wikipedia.org/wiki/Data_Coding_Scheme.\n   '23' |\tYou did not include https in the URL you set in callback.\n   '29' |\tThe phone number you set in to is not in your pre-approved destination list. To send messages to this phone number, add it using Dashboard.\n   '34' |\tThe phone number you supplied in the to parameter of your request was either missing or invalid.\n"
          example: '0'
        network:
          type: string
          description: The ID of the network of the recipient
          example: '12345'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
externalDocs:
  description: HTTP response headers
  url: https://developer.kpn.com/documentation-response-headers