Telesign Bulk SMS API

openapi: 3.2.0
info:
  version: '1.0'
  title: Engage Bulk SMS API
  description: This spec contains details about the Telesign Engage API.
  contact:
    name: Telesign Customer Support Team
    email: support@telesign.com
servers:
- url: https://rest-ww.telesign.com
security:
- Basic: []
tags:
- name: Bulk SMS
paths:
  /v1/verify/bulk_sms:
    post:
      description: 'Use this endpoint to send the same SMS message to multiple recipients.


        ## General requirements

        * **Authentication:** Basic (easiest to implement) or Digest

        * **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.

        * **Accepts:** `application/x-www-form-urlencoded`

        * **Responds with:** `application/json`

        * **Required headers:** `Content-Type - application/x-www-form-urlencoded`

        * **Rate limit:** Default rate limits by product'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                recipients:
                  type: string
                  description: Comma separated list of recipient phone numbers (maximum of 1000). Optionally append a session ID to each phone number separated by a colon.
                  example: 381606878232:255E3E34382C0E049046BF14FF7F3435,381647559476:255DEBF29DA410049042F97AF48F3D04
                template:
                  type: string
                  description: The text of the message to your recipients.
                  example: Your message here.
                ucid:
                  description: 'A string specifying a use case code. Choices include -

                    * ATCK - for use in a 2FA situation like updating an account or logging in

                    * BACF - for creating an account where the service may be vulnerable to bulk attacks and fraudsters

                    * BACS - for creating an account where the service may be vulnerable to bulk attacks or individual spammers

                    * CHBK - for use when someone is trying to buy something expensive or unusual and you want to verify it is really them

                    * CLDR - calendar event

                    * LEAD - for use in a situation where you require a person to enter personal information in order to obtain information about something like a loan or realty or school, and you want to check if the person is bogus or not

                    * OTHR - if you have a situation not addressed by other tags

                    * PWRT - for use in a situation where a password reset is required

                    * RESV - for use when you have end users making reservations and not showing up, and you want to be able to include phone verification in the loop

                    * RXPF - for use when you are trying to prevent prescription fraud

                    * SHIP - for use when you are sending a shipping notification

                    * THEF - for use when you are trying to prevent an end user from deactivating or redirecting a phone number in order to take over someone else''s identity

                    * TRVF - for use when you are transferring money and you want to check to see if it is approved by sending a text message or phone call to your end user. This is similar to CHBK, but is specifically for a money transaction

                    * UNKN - if you have a situation not addressed by other tags (same as OTHR)

                    '
                  type: string
                sender_id:
                  description: The phone number from which to send these SMS messages.
                  type: string
              required:
              - recipients
              - template
      responses:
        '200':
          description: "**Success.** Your request to the service was created.\n\n| Status Code | Associated text string | Description|\n|-------------|------------------------|------------|\n| 293 | Bulk request accepted | The bulk request was accepted by Telesign. |   \n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postBulkSMSResponse'
              examples:
                Example:
                  value:
                    reference_id: B562A981D0E0010488434B07861B1862
                    sub_resource: bulk_sms
                    status:
                      code: 293
                      description: Bulk request accepted
                      updated_on: '2022-06-14T23:36:56.164428Z'
                    errors: []
        '400':
          description: '**Bad request.** The request could not be understood by the server due to malformed syntax. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.


            |Status Code | Status Description     | Error Code |Error Description |

            |------------|------------------------|------------|------------------|

            |500|Transaction not attempted|-10001|Invalid Request: Missing parameter Parameter: Template|

            |500|Transaction not attempted|-10002|Empty recipients list|

            |500|Transaction not attempted|-10003|Max number of recipients exceeded|

            |500|Transaction not attempted|-40006|Bad Request|

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postBulkSMSResponse'
              examples:
                Example:
                  value:
                    reference_id: B562A981D0E0010488434B07861B1862
                    sub_resource: bulk_sms
                    status:
                      code: 500
                      description: Transaction not attempted
                      updated_on: '2022-06-14T23:36:56.164428Z'
                    errors:
                    - code: -10002
                      description: Empty recipients list
        '401':
          description: '**Unauthorized.** The request requires user authentication. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.



            |Status Code | Status Description     | Error Code |Error Description |

            |------------|------------------------|------------|------------------|

            |500|Transaction not attempted|-10009|Invalid source IP address|

            |501|Not authorized|-20002|This product is not enabled for this Customer ID.|

            |501|Not authorized|-30000|Invalid Customer ID.|

            |501|Not authorized|-30001|Customer ID Account Suspended.|

            |501|Not authorized|-30006| Invalid Signature.|'
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/postBulkSMSResponse'
                - type: object
                  properties:
                    signature_string:
                      type: string
                      description: Returned when request signature is not valid. Signature from failed authorization requests - doesn’t contain all required data (like x-ts-auth-method), or it’s not ordered properly.
                      example: 'POST\napplication/x-www-form-urlencoded\n\nx-ts-auth-method: HMAC-SHA256\nx-ts-date:Tue, 31 Jan 2024 11:36:42 GMT\nx-ts-nonce:ab$CDef/gh123+II4jk\nrecipients=11234567890:0123456789ABCDEF0123456789ABCDEG,11234567891:0123456789ABCDEF0123456789ABCDEH&template=Your message here.&session_id=CustomExternalID1234\n/v1/verify/bulk_sms'
              examples:
                Unauthorized:
                  value:
                    reference_id: B562A981D0E0010488434B07861B1862
                    sub_resource: bulk_sms
                    status:
                      code: 500
                      description: Transaction not attempted
                      updated_on: '2022-06-14T23:36:56.164428Z'
                    errors:
                    - code: -20002
                      description: This product is not enabled for this Customer ID.
                Invalid signature string:
                  value:
                    reference_id: B562A981D0E0010488434B07861B1862
                    sub_resource: bulk_sms
                    status:
                      code: 501
                      description: Not authorized
                      updated_on: '2022-06-14T23:36:56.164428Z'
                    errors:
                    - code: -30006
                      description: Invalid Signature.
                    signature_string: 'POST\napplication/x-www-form-urlencoded\n\nx-ts-auth-method: HMAC-SHA256\nx-ts-date:Tue, 31 Jan 2024 11:36:42 GMT\nx-ts-nonce:ab$CDef/gh123+II4jk\nrecipients=11234567890:0123456789ABCDEF0123456789ABCDEG,11234567891:0123456789ABCDEF0123456789ABCDEH&template=Your message here.&session_id=CustomExternalID1234\n/v1/verify/bulk_sms'
        '429':
          description: '**Too Many Requests.** The user sent too many requests in a given amount of time. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.




            |Status Code | Status Description     | Error Code |Error Description |

            |------------|------------------------|------------|------------------|

            |500|Transaction not attempted|-40007|Rate Limit Exceeded|

            |500|Transaction not attempted|-40008|Verify SMS exceeded transaction hard cap. Request denied.|

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postBulkSMSResponse'
              examples:
                Example:
                  value:
                    reference_id: B562A981D0E0010488434B07861B1862
                    sub_resource: bulk_sms
                    status:
                      code: 500
                      description: Transaction not attempted
                      updated_on: '2022-06-14T23:36:56.164428Z'
                    errors:
                    - code: -40007
                      description: Rate Limit Exceeded
        '500':
          description: '**Service Unavailable.** System unavailable, try again.



            |Status Code | Status Description     | Error Code |Error Description |

            |------------|------------------------|------------|------------------|

            |500|Transaction not attempted|-90001|System Unavailable, please try again later.|

            '
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/postBulkSMSResponse'
                - type: object
                  properties:
                    signature_string:
                      type: string
                      example: 'POST\napplication/x-www-form-urlencoded\n\nx-ts-auth-method: HMAC-SHA256\nx-ts-date:Tue, 31 Jan 2024 11:36:42 GMT\nx-ts-nonce:ab$CDef/gh123+II4jk\nrecipients=11234567890:0123456789ABCDEF0123456789ABCDEG,11234567891:0123456789ABCDEF0123456789ABCDEH&template=Your message here.&session_id=CustomExternalID1234\n/v1/verify/bulk_sms'
                      description: Returned when request signature is not valid. Signature from failed authorization requests - doesn’t contain all required data (like x-ts-auth-method), or it’s not ordered properly.
              examples:
                Example:
                  value:
                    reference_id: B562A981D0E0010488434B07861B1862
                    sub_resource: bulk_sms
                    status:
                      code: 500
                      description: Transaction not attempted
                      updated_on: '2022-06-14T23:36:56.164428Z'
                    errors:
                    - code: -90001
                      description: System Unavailable, please try again later.
      summary: Send bulk SMS
      operationId: sendBulkSMS
      tags:
      - Bulk SMS
components:
  schemas:
    BulkSMSStatus:
      title: BulkSMSStatus
      type: object
      description: Contains properties related to the processing status of the transaction.
      properties:
        code:
          type: integer
          description: One of the status codes or error codes.
          example: 293
        description:
          type: string
          description: Text describing the transaction status.
          example: Bulk request accepted
        updated_on:
          type: string
          description: 'An [RFC 3339](http://www.ietf.org/rfc/rfc3339.txt) timestamp indicating when the transaction status was updated. '
          example: '2022-06-14T23:36:56.164428Z'
    postBulkSMSResponse:
      type: object
      title: postBulkSMSResponse
      properties:
        reference_id:
          type: string
          minLength: 32
          maxLength: 32
          description: The service's unique identifier for this transaction.
          example: B562A981D0E0010488434B07861B1862
        sub_resource:
          type: string
          example: bulk_sms
          description: The Telesign service you made this request to.
        status:
          $ref: '#/components/schemas/BulkSMSStatus'
        errors:
          type: array
          description: Each object in this array describes an error that occurred during the processing of this request.
          items:
            $ref: '#/components/schemas/BulkSMSError'
      required:
      - reference_id
    BulkSMSError:
      title: BulkSMSError
      type: object
      properties:
        code:
          type: integer
          example: -10002
          description: A 1 to 5-digit error code (possibly negative) that indicates the type of error that occurred.
        description:
          type: string
          example: Empty recipients list
          description: Text describing the error that occurred.
      required:
      - code
      - description
  securitySchemes:
    Basic:
      type: http
      description: Easiest to implement. See [Basic Authentication](/enterprise/docs/authentication#basic-authentication) for more details.
      scheme: basic
    Digest:
      type: apiKey
      name: Authorization
      in: header
      description: See [Digest Authentication](/enterprise/docs/authentication#basic-authentication) for more details.
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true