swagger: "2.0"
schemes:
  - https
host: api.idtbeyond.com
basePath: /v1
info:
  description: Our active docs provide the ability to test out your account and to see the responses to your queries. The services are RESTful, and are accessed using standard HTTP methods over a secure HTTPS channel. Requests and responses are currently sent in JSON format, and have a base URL of /v1.
  termsOfService: https://app.idtbeyond.com/terms/
  title: Active Documentation for /v1
  version: 1.1.7
  x-apisguru-categories:
    - telecom
  x-logo:
    backgroundColor: "#222222"
    url: https://twitter.com/net2phone/profile_image?size=original
  x-origin:
    - format: swagger
      url: https://app.idtbeyond.com/swagger/spec-08ef3dc298.json
      version: "2.0"
  x-providerName: idtbeyond.com
consumes:
  - application/json
produces:
  - application/json
paths:
  /iatu/balance:
    get:
      description: Returns a JSON of the account balance.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
      responses:
        "200":
          description: Successful balance JSON response
      summary: Account balance
      tags:
        - account
  /iatu/charges/reports/all:
    get:
      description: Returns charges by date range.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
        - default: 2016-01-28
          description: The beginning date of the search IN YYYY-MM-DD format (America/New_York timezone). '2016-01-28'
          in: query
          name: date_from
          required: true
          type: string
        - default: 2016-01-28
          description: The ending date of the search IN YYYY-MM-DD format (America/New_York timezone). '2016-01-28'
          in: query
          name: date_to
          required: true
          type: string
      responses:
        "200":
          description: Successful charges JSON response
      summary: List of account charges in JSON
      tags:
        - charges
  /iatu/charges/reports/all.csv:
    get:
      description: Returns charges by date range in CSV.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
        - default: 2016-01-28
          description: The beginning date of the search IN YYYY-MM-DD format (America/New_York timezone). '2016-01-28'
          in: query
          name: date_from
          required: true
          type: string
        - default: 2016-01-28
          description: The ending date of the search IN YYYY-MM-DD format (America/New_York timezone). '2016-01-28'
          in: query
          name: date_to
          required: true
          type: string
      produces:
        - application/csv
      responses:
        "200":
          description: Successful charges CSV response
      summary: List of account charges in CSV
      tags:
        - charges
  /iatu/number-validator:
    get:
      description: Checks to verify if the phone number is valid for the country supplied.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
        - default: BR
          description: 2-digit code of the country in ISO 3166 format. 'BR'
          in: query
          name: country_code
          required: true
          type: string
        - default: "5521983115555"
          description: The mobile number you would like to validate. '5521983115555'
          in: query
          name: mobile_number
          required: true
          type: string
      responses:
        "200":
          description: Local value response
      summary: Mobile number validation
      tags:
        - utilities
  /iatu/products/promotions:
    get:
      description: Returns a JSON of the current promotions.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
      responses:
        "200":
          description: Successful Promotions JSON response
      summary: Current promotions
      tags:
        - utilities
  /iatu/products/reports/all:
    get:
      description: Returns a JSON list of products, ranges, and their commissions percentages.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
      responses:
        "200":
          description: Products JSON response
      summary: Get a list of products in JSON format
      tags:
        - products
  /iatu/products/reports/all.csv:
    get:
      description: Returns a CSV of products, ranges, and their commissions percentages.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
      produces:
        - application/csv
      responses:
        "200":
          description: Products CSV response
      summary: Get a list of products in CSV format
      tags:
        - products
  /iatu/products/reports/local-value:
    get:
      description: Returns a CSV of products, ranges, and their commissions percentages.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
        - default: GT
          description: 2-digit code of the country in ISO 3166 format. 'GT'
          in: query
          name: country_code
          required: true
          type: string
        - default: Claro
          description: Name of the mobile carrier. 'Claro'
          in: query
          name: carrier_code
          required: true
          type: string
        - default: 500
          description: This is the amount, in cents, of the product you are purchasing. '500' = $5.00
          in: query
          name: amount
          required: true
          type: integer
        - default: USD
          description: The currency code (ISO 4217) on the product you are querying. 'USD'
          in: query
          name: currency_code
          required: true
          type: string
      responses:
        "200":
          description: Local value response
      summary: Get the estimated Local Value of a product
      tags:
        - products
  /iatu/topups:
    post:
      description: Submits an IATU transaction request.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
        - description: Topups details
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/Topups"
      responses:
        "201":
          description: The transaction has been completed successfully.
        "202":
          description: The transaction has been received, but the final status is unknown. Please query by the client_transaction_id to get the current status of the transaction.
        "400":
          description: Invalid ID supplied
        "404":
          description: X not found
        "405":
          description: Validation exception
        "500":
          description: There is an error in your transaction. Please check the error code contained in the result for more information.
      summary: Topup a mobile phone
      tags:
        - topups
  /iatu/topups/reports:
    post:
      description: Search topups transactions, by date, with client_transaction_id or to_service_number. Use 'client_transaction_id' to search by transaction number, or 'to_service_number' to get transaction status.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
        - description: Topups reports request details
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/TopupsReports"
      responses:
        "200":
          description: Successful topups JSON response
      summary: Search topups transactions
      tags:
        - topups
  /iatu/topups/reports/all:
    get:
      description: Returns topups by date range.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
        - default: 2016-01-28
          description: The beginning date of the search IN YYYY-MM-DD format (America/New_York timezone). '2016-01-28'
          in: query
          name: date_from
          required: true
          type: string
        - default: 2016-01-28
          description: The ending date of the search IN YYYY-MM-DD format (America/New_York timezone). '2016-01-28'
          in: query
          name: date_to
          required: true
          type: string
      responses:
        "200":
          description: Successful topups JSON response
      summary: List of account topups in JSON
      tags:
        - topups
  /iatu/topups/reports/all.csv:
    get:
      description: Returns topups by date range in CSV.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
        - default: 2016-01-28
          description: The beginning date of the search IN YYYY-MM-DD format (America/New_York timezone). '2016-01-28'
          in: query
          name: date_from
          required: true
          type: string
        - default: 2016-01-28
          description: The ending date of the search IN YYYY-MM-DD format (America/New_York timezone). '2016-01-28'
          in: query
          name: date_to
          required: true
          type: string
      produces:
        - application/csv
      responses:
        "200":
          description: Successful topups CSV response
      summary: List of account topups in CSV
      tags:
        - topups
  /iatu/topups/reports/totals:
    get:
      description: Returns topups totals by date range.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
        - default: 2016-01-28
          description: The beginning date of the search IN YYYY-MM-DD format (America/New_York timezone). '2016-01-28'
          in: query
          name: date_from
          required: true
          type: string
        - default: 2016-01-28
          description: The ending date of the search IN YYYY-MM-DD format (America/New_York timezone). '2016-01-28'
          in: query
          name: date_to
          required: true
          type: string
      responses:
        "200":
          description: Successful topups JSON response
      summary: Summary of account topups in JSON
      tags:
        - topups
  /iatu/topups/reverse:
    post:
      description: Occasionally, a carrier will not be able to successfully complete a topup request. In this case, we will attempt to automatically reverse the transaction for you, and return the money into your account. In the case when this is not possible, you may need to request a reverse on the transaction that has a status of 'transaction_status' 'notredeemed'.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
        - description: Topups details
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/TopupsReversal"
      responses:
        "200":
          description: Successful charges JSON response
      summary: Reversal of a Topup
      tags:
        - topups
  /status:
    get:
      description: Returns a JSON of the API status.
      parameters:
        - default: APP_ID
          description: Application ID you would like to use
          in: header
          name: x-idt-beyond-app-id
          required: true
          type: string
        - default: APP_KEY
          description: Application KEY you would like to use
          in: header
          name: x-idt-beyond-app-key
          required: true
          type: string
      responses:
        "200":
          description: Successful status JSON response
      summary: Status check
      tags:
        - utilities
definitions:
  Topups:
    properties:
      amount:
        default: 500
        description: The amount, in cents, of the product you are purchasing. '500' = $5.00
        type: integer
      carrier_code:
        default: Claro
        description: Name of the mobile carrier. 'Claro'
        type: string
      client_transaction_id:
        default: ""
        description: UNIQUE 15 char ID you use to track topups. 'trans0123456789'
        type: string
      country_code:
        default: GT
        description: 2-digit code of the country in ISO 3166 format. 'GT'
        type: string
      mobile_number:
        default: "50231234567"
        description: Mobile number to topup. VALIDATE prior to submission. '50231234567'
        type: string
      plan:
        default: Sandbox
        description: The Application plan being used. Case-sensitive. 'Sandbox' or 'Production'
        type: string
      product_code:
        default: ""
        description: Optional code to distinguish one particular product from another. '76560'
        type: string
      terminal_id:
        default: Kiosk 5
        description: ID for the Terminal used to perform the topup. 'Kiosk 5'
        type: string
  TopupsReports:
    properties:
      client_transaction_id:
        default: trans0123456789
        description: The UNIQUE 15 char ID used to track topups. 'trans0123456789'
        type: string
      date_from:
        default: 2016-01-28
        description: The beginning date of the search IN YYYY-MM-DD format (America/New_York timezone). Not used in query by to_service_number. '2016-01-28'
        type: string
      date_to:
        default: 2016-01-28
        description: The ending date of the search IN YYYY-MM-DD format (America/New_York timezone). Not used in query by to_service_number. '2016-01-28'
        type: string
      to_service_number:
        default: 123456789
        description: Enter the to_service_number returned in the response to track the current transaction status. '0123456789'
        type: string
      type_of_report:
        default: client_transaction_id or to_service_number
        description: The type of query you would like to search by.
        type: string
  TopupsReversal:
    properties:
      client_transaction_id:
        default: trans0123456789
        description: UNIQUE 15 char ID you use to track topups. 'trans0123456789'
        type: string
      to_service_number:
        default: 123456789
        description: UNIQUE IDT transaction number found in the response of a successful topup request. '0123456789'
        type: string
