Telstra free trial numbers API

openapi: 3.2.0
info:
  title: Messaging API v3.x free trial numbers API
  version: 3.x
  description: 'Send and receive SMS & MMS programmatically, leveraging Australia''s leading mobile network.

    With Telstra''s Messaging API, we take out the complexity to allow seamless messaging integration into your app, with just a few lines of code.

    Our REST API is enterprise grade, allowing you to communicate with engaging SMS & MMS messaging in your web and mobile apps in near real-time on a global scale.'
servers:
- url: https://products.api.telstra.com/messaging/v3
  description: Messaging API
security:
- bearer_auth: []
tags:
- name: free trial numbers
paths:
  /free-trial-numbers:
    post:
      security:
      - bearer_auth: []
      tags:
      - free trial numbers
      summary: create free trial number list
      description: 'Your Free Trial Numbers are the 10 recipient mobile numbers that you can message during the Free Trial. The first five numbers you send an SMS/MMS to will automatically be added to your Free Trial Numbers list. After that, you can use this endpoint to register another five. Alternatively, you can use this endpoint to register all 10 numbers.


        Use this endpoint to register a Free Trial Number to your account. To test out all the features that the trial has to offer, we recommend registering your own mobile number to your Free Trial Numbers list.


        Note that you can only message mobile numbers that have been added to your Free Trial list and once registered, a Free Trial Number cannot be removed or replaced.'
      operationId: createTrialNumbers
      parameters:
      - $ref: '#/components/parameters/TelstraAPIVersion'
      - $ref: '#/components/parameters/ContentLanguage'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/AcceptCharset'
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        $ref: '#/components/requestBodies/trial-numbers'
      responses:
        '201':
          description: 'A 201 OK response means your request has been successful. Your registered Free Trial Number(s) will be returned in the response.

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
            Location:
              schema:
                type: string
                example: /free-trial-numbers/{number}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FreeTrialNumbers'
        '400':
          description: 'Bad Request


            | code | suggested_action |

            | :--- | :--- |

            | FIELD_INVALID | Check the field and the field formatting are correct. |

            | FIELD_LENGTH_ERR | Check the field is within character limits. |

            | FIELD_MISSING | Ensure you''ve supplied all the required fields. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: 'Unauthorized


            | code | suggested_action |

            | :--- | :--- |

            | TOKEN_INVALID | Check the access token. |

            | TOKEN_EXPIRED | Please refresh the token. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '402':
          description: "Payment Required\n\n| code | suggested_action |\n| :--- | :--- |\n| FREE_TRIAL_INTERNATIONAL_ERR | Move to a paid plan to send a message to an international destination. | \n| ACCOUNT_ERR | Contact [support](mailto:telstradev@team.telstra.com) for help with your account. |\n| RATE_PLAN_ERR | Contact [support](mailto:telstradev@team.telstra.com) for help with your account. |\n| ACCOUNT_NOT_LINKED | Check you've registered for the Messaging API [here](https://dev.telstra.com). |\n| ACCOUNT_LIMIT_ERROR | You've reached the maximum quota of Free Trial Numbers that can be registered to your account. Upgrade to a paid plan to send a message to this recipient.   |\n"
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: 'Forbidden


            | code | suggested_action |

            | :--- | :--- |

            | FREE_TRIAL_ERR | This call is only applicable to Free Trial users. Check if the call is required. |

            | RESOURCE_AUTH_ERR | Check the permissions associated with your account. |

            | INSUFFICIENT_SCOPE | The access token you generated does not have sufficient permissions for this request. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: 'Not Found


            | code | suggested_action |

            | :--- | :--- |

            | RESOURCE_TEMP_ERR | Check the API status page to see if an active incident is causing a temporary issue with the resource. |

            | RESOURCE_NOT_FOUND | Check the endpoint is correct. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '405':
          description: 'Method Not Allowed


            | code | suggested_action |

            | :--- | :--- |

            | METHOD_INVALID | Ensure the method is POST. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '413':
          description: 'Payload Too Large


            | code | suggested_action |

            | :--- | :--- |

            | PAYLOAD_TOO_LARGE | Reduce body payload size |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: 'Too Many Requests


            | code | suggested_action |

            | :--- | :--- |

            | TOO_MANY_REQUESTS | Reduce the number of concurrent calls. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
            Retry-After:
              schema:
                type: number
                example: 3600
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: 'Internal Server Error


            | code | suggested_action |

            | :--- | :--- |

            | INTERNAL_TIMEOUT | Try the call again. If the issue persists, check the API [status page](https://dev.telstra.com/api/status) to see if there''s an active incident. |

            | INTERNAL_SERVER_ERR | Check the API [status page](https://dev.telstra.com/api/status) to see if an active incident is causing the internal error. |

            | NETWORK_ERR | Please try again later. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        default:
          description: 'Unexpected

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    get:
      security:
      - bearer_auth: []
      tags:
      - free trial numbers
      summary: get all free trial numbers
      description: 'Use this endpoint to fetch the Free Trial Number(s) currently assigned to your account. These are the mobile numbers that you can message during the Free Trial.


        If you''re using a paid plan, there''s no limit to the number of recipients that you can message, so you don''t need to register Free Trial Numbers.'
      operationId: getTrialNumbers
      parameters:
      - $ref: '#/components/parameters/TelstraAPIVersion'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/AcceptCharset'
      responses:
        '200':
          description: 'A 200 OK response means your request has been successful. Your Free Trial Number(s) will be returned in the response body.

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FreeTrialNumbers'
        '400':
          description: 'Bad Request


            | code | suggested_action |

            | :--- | :--- |

            | FIELD_INVALID | Check the field and the field formatting are correct. |

            | FIELD_LENGTH_ERR | Check the field is within character limits. |

            | FIELD_MISSING | Ensure you''ve supplied all the required fields. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: 'Unauthorized


            | code | suggested_action |

            | :--- | :--- |

            | TOKEN_INVALID | Check the access token. |

            | TOKEN_EXPIRED | Please refresh the token. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '402':
          description: 'Payment Required


            | code | suggested_action |

            | :--- | :--- |

            | ACCOUNT_ERR | Contact [support](mailto:telstradev@team.telstra.com) for help with your account. |

            | RATE_PLAN_ERR | Contact [support](mailto:telstradev@team.telstra.com) for help with your account. |

            | ACCOUNT_NOT_LINKED | Check you''ve registered for the Messaging API [here](https://dev.telstra.com). |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: 'Forbidden


            | code | suggested_action |

            | :--- | :--- |

            | FREE_TRIAL_ERR | This call is only applicable to Free Trial users. Check if the call is required. |

            | RESOURCE_AUTH_ERR | Check the permissions associated with your account. |

            | INSUFFICIENT_SCOPE | The access token you generated does not have sufficient permissions for this request. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: 'Not Found


            | code | suggested_action |

            | :--- | :--- |

            | RESOURCE_TEMP_ERR | Check the API status page to see if an active incident is causing a temporary issue with the resource. |

            | RESOURCE_NOT_FOUND | Check the endpoint is correct. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '405':
          description: 'Method Not Allowed


            | code | suggested_action |

            | :--- | :--- |

            | METHOD_INVALID | Ensure the method is GET. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: 'Too Many Requests


            | code | suggested_action |

            | :--- | :--- |

            | TOO_MANY_REQUESTS | Reduce the number of concurrent calls. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
            Retry-After:
              schema:
                type: number
                example: 3600
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: 'Internal Server Error


            | code | suggested_action |

            | :--- | :--- |

            | INTERNAL_TIMEOUT | Try the call again. If the issue persists, check the API [status page](https://dev.telstra.com/api/status) to see if there''s an active incident. |

            | INTERNAL_SERVER_ERR | Check the API [status page](https://dev.telstra.com/api/status) to see if an active incident is causing the internal error. |

            | NETWORK_ERR | Please try again later. |

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        default:
          description: 'Unexpected

            '
          headers:
            Content-Language:
              schema:
                type: string
                example: en-au
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
components:
  parameters:
    ContentLanguage:
      name: Content-Language
      in: header
      required: true
      schema:
        type: string
        example: en-au
    AcceptCharset:
      name: Accept-Charset
      in: header
      required: true
      schema:
        type: string
        example: utf-8
    ContentType:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        example: application/json
    TelstraAPIVersion:
      name: Telstra-api-version
      in: header
      required: false
      schema:
        type: string
        example: 3.1.0
    Accept:
      name: Accept
      in: header
      required: true
      schema:
        type: string
        example: application/json
    Authorization:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
        example: Bearer <access_token>
  schemas:
    Errors:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/Error'
    FreeTrialNumbers:
      type: object
      required:
      - freeTrialNumbers
      properties:
        freeTrialNumbers:
          type: array
          maxItems: 10
          minItems: 0
          items:
            type: string
            minLength: 10
            maxLength: 10
          example:
          - 0412345678
          - 0487654321
          description: 'The recipient number(s) registered to your Free Trial Numbers List. These are the mobile numbers that you can message during the Free Trial.

            '
    Error:
      type: object
      required:
      - code
      - issue
      - suggested_action
      properties:
        code:
          type: string
          minLength: 1
          maxLength: 100
          description: Unique code of the error
        issue:
          type: string
          minLength: 1
          maxLength: 99999
          description: The reason for the error
        suggested_action:
          type: string
          minLength: 1
          maxLength: 99999
          description: Suggest practical actions for this particular issue.
        field:
          type: string
          minLength: 1
          maxLength: 99999
          description: The field that caused the error
        value:
          type: string
          minLength: 1
          maxLength: 99999
          description: The value of the field that caused the error
        location:
          type: string
          description: The location of the field that caused the error.
          enum:
          - body
          - path
          - query
        link:
          type: string
          minLength: 1
          maxLength: 99999
          description: URI for detailed information related to this error for the developer.
  requestBodies:
    trial-numbers:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
            - freeTrialNumbers
            properties:
              freeTrialNumbers:
                oneOf:
                - type: array
                  maxItems: 10
                  minItems: 1
                  items:
                    type: string
                    minLength: 10
                    maxLength: 10
                  example:
                  - 0412345678
                  - 0487654321
                - type: string
                  minLength: 10
                  maxLength: 10
                description: 'These are the mobile numbers you want to message during your Free Trial. Write Australian numbers in national format (e.g. "0412345678"). Use a string for a single recipient, and an array of strings for multiple recipients, (e.g. ["0412345678", "0487654321"]).

                  '
  securitySchemes:
    bearer_auth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://products.api.telstra.com/v2/oauth/token
          scopes:
            free-trial-numbers:read: read information for free trial numbers
            free-trial-numbers:write: write information for free trial numbers
            messages:read: read information for messages
            messages:write: write information for messages
            reports:read: read information for reports
            reports:write: write information for reports
            virtual-numbers:read: read information for virtual-numbers
            virtual-numbers:write: write information for virtual numbers