openapi: 3.0.0
info:
  title: jambonz REST API
  description: jambonz REST API
  contact:
    email: daveh@drachtio.org
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.0.0
servers:
  - url: /v1
    description: development server
paths:
  /BetaInviteCodes:
    post:
      summary: generate one or more beta invite codes
      operationId: generateInviteCode
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                count:
                  type: number
                  format: integer
      responses:
        200:
          description: invite codes successfully generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - ok
                      - failed
                  added:
                    type: number
                    format: integer
                required:
                  - status
                  - added
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /PredefinedCarriers:
    get:
      summary: get a list of predefined carriers
      operationId: listPredefinedCarriers
      responses:
        200:
          description: list of predefined carriers
          content:
            application/json:
              schema:
                type:
                  array
                items:
                  $ref: '#/components/schemas/PredefinedCarrier'
  /Accounts/{AccountSid}/PredefinedCarriers/{PredefinedCarrierSid}:
    parameters:
      - name: AccountSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: PredefinedCarrierSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      summary: add a VoiPCarrier to an account based on PredefinedCarrier template
      operationId: createVoipCarrierFromTemplate
      responses:
        201:
          description:  voip carrier successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'      
  /Sbcs:
    post:
      summary: add an SBC address
      operationId: createSbc
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ipv4:
                  type: string
                port:
                  type: number
                service_provider_sid:
                  type: string
                  description: service provider scope for the generated api key
              required:
                - ipv4
      responses:
        201:
          description:  sbc address successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: retrieve public IP addresses of the jambonz Sbcs
      operationId: listSbcs
      parameters:
        - in: query
          name: service_provider_sid
          required: false
          schema:
            type: string
            description: return only the SBCs operated for the sole use of this service provider
      responses:
        200:
          description: list of SBC addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    ipv4:
                      type: string
                      description: ip address of one of our Sbcs 
                  required:
                    - ipv4
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /Sbcs/{SbcSid}:
      parameters:
      - name: SbcSid
        in: path
        required: true
        schema:
          type: string
      delete:
        summary: delete sbc address
        operationId: deleteSbcAddress      
        responses:
          200:
            description: sbc address deleted
          404:
            description: sbc address not found
  /Smpps:
    get:
      summary: retrieve public IP addresses of the jambonz smpp servers
      operationId: listSmpps
      parameters:
        - in: query
          name: service_provider_sid
          required: false
          schema:
            type: string
            description: return only the smpp servers operated for the sole use of this service provider
      responses:
        200:
          description: list of smpp server addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    ipv4:
                      type: string
                      description: ip address of one of our Sbcs
                    port:
                      type: number
                    use_tls:
                      type: boolean
                    is_primary:
                      type: boolean
                  required:
                    - ipv4
                    - port
                    - use_tls
                    - is_primary
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /InviteCodes:
    post:
      summary: validate an invite code
      operationId: validateInviteCode
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
              required:
                - code
      responses:
        204:
          description: code successfully validated
        404:
          description: code not found
        
  /ApiKeys:
    post:
      summary: create an api key
      operationId: createApikey
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                service_provider_sid:
                  type: string
                  description: service provider scope for the generated api key
                account_sid:
                  type: string
                  description: account scope for the generated api key
                expiry_secs:
                  type: number
                  description: duration of key validity, in seconds
      responses:
        201:
          description: api key successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulApiKeyAdd'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

        500:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /Apikeys/{ApiKeySid}:
      parameters:
      - name: ApiKeySid
        in: path
        required: true
        schema:
          type: string
      delete:
        summary: delete api key
        operationId: deleteApiKey          
        responses:
          200:
            description: api key deleted
          404:
            description: api key or account not found
  /signin:
    post:
      summary: sign in using email and password
      operationId: loginUser
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                password:
                  type: string
      responses:
        200:
          description: successfully signed in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
              example:
                user_sid: 3192af15-8260-439f-939d-184613f6bbfb
                account_sid: 7be2d35a-da6e-4faf-a382-1b37a571c7fd
                name: Dave Horton
                email: daveh@drachtio.org
                provider: github
                provider_userid: davehorton
                pristine: true
                account_validated: true
                scope: read-write
        403:
          description: Invalid password
        404:
          description: email not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /logout:
    post:
      summary: log out and deactivate jwt
      operationId: logoutUser
      responses:
        204:
          description: user logged out
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /forgot-password:
    post:
      summary: send link to reset password
      operationId: forgotPassword
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
      responses:
        204:
          description: email sent
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
              example:
                msg: service_provider_sid is missing
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /change-password:
    post:
      summary: changePassword
      operationId: changePassword
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                old_password:
                  type: string
                new_password:
                  type: string
      responses:
        204:
          description: password changed
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
              example:
                msg: service_provider_sid is missing
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /register:
    post:
      summary: create a new user and account
      operationId: registerUser
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                service_provider_sid:
                  type: string
                  example: 2708b1b3-2736-40ea-b502-c53d8396247f
                provider:
                  type: string
                  enum:
                    - github
                    - google
                    - twitter
                    - local
                  example: github
                email:
                  type: string
                password:
                  type: string
                email_activation_code:
                  type: string
                oauth2_code:
                  type: string
                  example: f82659563e061e7347de
                oauth2_state:
                  type: string
                  example: 386d2e990ad
                oauth2_client_id:
                  type: string
                  example: a075a5889264b8fbc831
                oauth2_redirect_uri:
                  type: string
                  example: https://localhost:3000/oauth-gh-callback
              required:
                - service_provider_sid
                - provider
      responses:
        200:
          description: user and account created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
              example:
                user_sid: 3192af15-8260-439f-939d-184613f6bbfb
                account_sid: 7be2d35a-da6e-4faf-a382-1b37a571c7fd
                name: Dave Horton
                email: daveh@drachtio.org
                provider: github
                provider_userid: davehorton
                pristine: true
                account_validated: true
                scope: read-write

        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
              example:
                msg: service_provider_sid is missing
        422:
          description: User exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
              example:
                msg: invalid service_provider_sid   
        403:
          description: invalid/expired oauth2 code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
              example:
                msg: code is expired or invalid
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /Invoices:
    get:
      summary: retrieve upcoming invoice for customer
      operationId: retrieveInvoice
      responses:
        200:
          description: upcoming invoice
          content:
            application/json:
              schema:
                type: object
        404:
          description: Not Found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /Users/{UserSid}:
    parameters:
      - name: UserSid
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
    put:
      summary: update user information
      operationId: updateUser
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email: 
                  type: string
                email_activation_code:
                  type: string
                old_password:
                  type: string
                  description: existing password, which is to be replaced
                new_password:
                  type: string
                  description: new password
      responses:
        204:
          description: user updated
        403:
          description: password change failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /Users/me:
    get:
      summary: retrieve details about logged-in user and associated account
      operationId: getMyDetails
      responses:
        200:
          description: full-ish detail about the logged-in user and account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAndAccountDetail'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

  /Availability:
    get:
      summary: check if a limited-availability entity such as a subdomain, email or phone number is already in use
      operationId: checkAvailability
      parameters:
        - in: query
          name: type
          required: true
          schema:
            type: string
            enum:
              - email
              - phone
              - subdomain
            example: subdomain
        - in: query
          name: value
          required: true
          schema:
            type: string
            example: mycorp.sip.jambonz.us
      responses:
        200:
          description: indicates whether value is already in use
          content:
            application/json:
              schema:
                type: object
                properties:
                  available:
                    type: boolean
                    description: true if value requested is available
                required:
                  - available
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /Prices:
    get:
      summary: list all prices
      operationId: listPrices
      responses:
        200:
          description: price listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /StripeCustomerId:
    get:
      summary: retrieve stripe customer id for an account, creating if necessary
      operationId: getStripeCustomerId
      responses:
        200:
          description: customer successfully provisioned or retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  stripe_customer_id: 
                    type: string
                required:
                  - stripe_customer_id
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /Subscriptions:
    get:
      summary: get subscription details from stripe
      operationId: getSubscription
      responses:
        200:
          description: stripe subscription entity
          content:
            application/json:
              schema:
                type: object
    post:
      summary: create or modify subscriptions in Stripe for a customer
      operationId: manageSubscription
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum:
                    - upgrade-to-paid
                    - downgrade-to-free
                    - update-payment-method
                    - update-quantities
                payment_method_id:
                  type: string
                dry_run:
                  type: boolean
                products:
                  type: array
                  items:
                    properties:
                      product_sid:
                        type: string
                      price_id:
                        type: string 
                      quantity:
                        type: number
                        format: integer
              required:
                - action
      responses:
        201:
          description: subscription successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                      - card error
                      - action required
                  customer_id:
                    type: string
                  client_secret:
                    type: string
                required:
                  - status
                  - customer_id
        400:
          description: bad request
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    
  /ActivationCode:
    post:
      summary: send an activation code to the user
      operationId: sendActivationCode
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  description: activation code
                  example: A74DF
                user_sid:
                  type: string
                  format: uuid
                  description: identifies user to send to
                type:
                  type: string
                  enum:
                  - email
                  - phone
                value:
                  type: string
                  description: the new email or phone number to be activated
      responses:
        204:
          description: activation code successfully sent
        404:
          description: User Not Found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /ActivationCode/{Code}:
    parameters:
      - name: Code
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
    put:
      summary: validate an activation code
      operationId: validateActivationCode
      requestBody:
        content:
          application/json:
             schema:
              type: object
              properties:
                user_sid:
                  type: string
                  format: uuid
                  description: identifies user to send to
                type:
                  type: string
                  enum:
                  - email
                  - phone
      responses:
        204:
          description: activation code validated
        404:
          description: User or activation code Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /AccountTest/:ServiceProviderSid:
    parameters:
    - name: ServiceProviderSid
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type: string
    get:
      summary: get test phone numbers and applications
      operationId: getTestData
      responses:
        200:
          description: test data for this service provider
          content:
            application/json:
              schema:
                type: object
                properties:
                  phonenumbers:
                    type: array
                    items:
                      type: string
                  applications:
                    type: array
                    items:
                      $ref: '#/components/schemas/Application'
        404:
          description: Service Provider Not Found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

  /Webhooks/{WebhookSid}:
    parameters:
      - name: WebhookSid
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
    get:
      summary: retrieve webhook
      operationId: getWebhook
      responses:
        200:
          description: webhook found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        404:
          description: webhook not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

  /VoipCarriers:
    post:
      summary: create voip carrier
      operationId: createVoipCarrier
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: voip carrier name
                  example: fastco
                description:
                  type: string
                  example: my US sip trunking provider
                account_sid:
                  type: string
                application_sid:
                  type: string
                e164_leading_plus:
                  type: boolean
                  description: whether a leading + is required on INVITEs to this provider
                  example: true
                requires_register:
                  type: boolean
                  description: wehther this provider requires us to send a REGISTER to them in order to receive calls
                register_username:
                  type: string
                  description: sip username to authenticate with, if registration is required
                  example: foo
                register_sip_realm:
                  type: string
                  description: sip realm to authenticate with, if registration is required
                  example: sip.fastco.com
                register_password:
                  type: string
                  description: sip password to authenticate with, if registration is required
                  example: bar
                tech_prefix:
                  type: string
                  description: prefix to be applied to the called number for outbound call attempts
                inbound_auth_username:
                  type: string
                  description: challenge inbound calls with this username/password if supplied
                inbound_auth_password:
                  type: string
                  description: challenge inbound calls with this username/password if supplied
                diversion:
                  type: string
                  description: Diversion header or phone number to apply to outbound calls
              required: 
                - name
      responses:
        201:
          description: voip carrier successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: list voip carriers
      operationId: listVoipCarriers
      responses:
        200:
          description: list of voip carriers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VoipCarrier'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /VoipCarriers/{VoipCarrierSid}:
    parameters:
      - name: VoipCarrierSid
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
    delete:
      summary: delete a voip carrier
      operationId: deleteVoipCarrier
      responses:
        204:
          description: voip carrier successfully deleted
        404:
          description: voip carrier not found
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
                example:
                  msg: a service provider with active accounts can not be deleted
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: retrieve voip carrier
      operationId: getVoipCarrier
      responses:
        200:
          description: voip carrier found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoipCarrier'
        404:
          description: voip carrier not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    put:
      summary: update voip carrier
      operationId: updateVoipCarrier
      parameters:
      - name: VoipCarrierSid
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoipCarrier'
      responses:
        204:
          description: voip carrier updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoipCarrier'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        404:
          description: voip carrier not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

  /SipGateways:
    post:
      summary: create sip gateway
      operationId: createSipGateway
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                voip_carrier_sid:
                  type: string
                  description: voip carrier that provides this gateway
                  format: uuid
                ipv4:
                  type: string
                port:
                  type: number
                is_active:
                  type: boolean
                inbound:
                  type: boolean
                outbound:
                  type: boolean
              required: 
                - voip_carrier_sid
                - ipv4
      responses:
        201:
          description: sip gateway successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: list sip gateways
      operationId: listSipGateways
      parameters:
        - in: query
          name: voip_carrier_sid
          required: true
          schema:
            type: string
            description: return only the SipGateways operated for this VoipCarrier
      responses:
        200:
          description: list of sip gateways
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SipGateway'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /SipGateways/{SipGatewaySid}:
    parameters:
      - name: SipGatewaySid
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
    delete:
      summary: delete a sip gateway
      operationId: deleteSipGateway
      responses:
        204:
          description: sip gateway successfully deleted
        404:
          description: sip gateway not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: retrieve sip gateway
      operationId: getSipGateway
      responses:
        200:
          description: sip gateway found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipGateway'
        404:
          description: sip gateway not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    put:
      summary: update sip gateway
      operationId: updateSipGateway
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SipGateway'
      responses:
        204:
          description: sip gateway updated
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        404:
          description: sip gateway not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /SmppGateways:
    post:
      summary: create smpp gateway
      operationId: createSmppGateway
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                voip_carrier_sid:
                  type: string
                  description: voip carrier that provides this gateway
                  format: uuid
                ipv4:
                  type: string
                port:
                  type: number
                netmask:
                  type: number
                inbound:
                  type: boolean
                outbound:
                  type: boolean
                is_primary:
                  type: boolean
                use_tls:
                  type: boolean
              required: 
                - voip_carrier_sid
                - ipv4
      responses:
        201:
          description: smpp gateway successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: list smpp gateways
      operationId: listSmppGateways
      responses:
        200:
          description: list of smpp gateways
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SmppGateway'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /SmppGateways/{SmppGatewaySid}:
    parameters:
      - name: SmppGatewaySid
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
    delete:
      summary: delete a smpp gateway
      operationId: deleteSmppGateway
      responses:
        204:
          description: smpp gateway successfully deleted
        404:
          description: smpp gateway not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: retrieve smpp gateway
      operationId: getSmppGateway
      responses:
        200:
          description: smpp gateway found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmppGateway'
        404:
          description: smpp gateway not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    put:
      summary: update sip gateway
      operationId: updateSmppGateway
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmppGateway'
      responses:
        204:
          description: smpp gateway updated
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        404:
          description: smpp gateway not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError' 
  /PhoneNumbers:
    post:
      summary: provision a phone number into inventory from a Voip Carrier
      operationId: provisionPhoneNumber
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                number:
                  type: string
                  description: telephone number
                voip_carrier_sid:
                  type: string
                  format: uuid
              required: 
                - number
                - voip_carrier_sid
      responses:
        201:
          description: phone number successfully provisioned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
              example:
                msg: invalid telephone number format
        404:
          description: voip carrier not found
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
                example:
                  msg: the phone number provided already exists in inventory
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: list phone numbers
      operationId: listProvisionedPhoneNumbers
      responses:
        200:
          description: list of phone numbers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PhoneNumber'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /PhoneNumbers/{PhoneNumberSid}:
    parameters:
      - name: PhoneNumberSid
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
    delete:
      summary: delete a phone number
      operationId: deletePhoneNumber
      responses:
        204:
          description: phone number successfully deleted
        404:
          description: phone number not found
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
                example:
                  msg: phone number that is assigned to an account may not be deleted
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: retrieve phone number
      operationId: getPhoneNumber
      responses:
        200:
          description: phone number found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        404:
          description: phone number not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    put:
      summary: update phone number
      operationId: updatePhoneNumber
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneNumber'
      responses:
        204:
          description: phone number updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoipCarrier'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        404:
          description: phone number not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  
  /ServiceProviders:
    post:
      summary: create service provider
      operationId: createServiceProvider
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: service provider name
                  example: fastcomms
                description:
                  type: string
                root_domain:
                  type: string
                  description: root domain for group of accounts that share a registration hook
                  example: example.com
                registration_hook:
                  $ref: '#/components/schemas/Webhook'
                  description: authentication webhook for registration
                ms_teams_fqdn:
                  type: string
                  description: SBC domain name for Microsoft Teams
                  example: contoso.com
              required: 
                - name
      responses:
        201:
          description: service provider successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

    get:
      summary: list service providers
      operationId: listServiceProviders
      responses:
        200:
          description: list of service providers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceProvider'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

  /ServiceProviders/{ServiceProviderSid}:
    parameters:
    - name: ServiceProviderSid
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type: string
    delete:
      summary: delete a service provider
      operationId: deleteServiceProvider
      responses:
        204:
          description: service provider successfully deleted
        404:
          description: service provider not found
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

    get:
      summary: retrieve service provider
      operationId: getServiceProvider
      responses:
        200:
          description: service provider found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceProvider'
        404:
          description: service provider not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

    put:
      summary: update service provider
      operationId: updateServiceProvider
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceProvider'
      responses:
        204:
          description: service provider updated
        404:
          description: service provider not found
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

  /ServiceProviders/{ServiceProviderSid}/Accounts:
    parameters:
      - name: ServiceProviderSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: get all accounts for a service provider
      operationId: getServiceProviderAccounts
      responses:
        200:
          description: account listing
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        403:
          description: unauthorized
        404:
          description: service provider not found

  /ServiceProviders/{ServiceProviderSid}/VoipCarriers:
    parameters:
      - name: ServiceProviderSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: get all carriers for a service provider
      operationId: getServiceProviderCarriers
      responses:
        200:
          description: account listing
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VoipCarrier'
        403:
          description: unauthorized
        404:
          description: service provider not found
    post:
      summary: create a carrier
      operationId: createCarrierForServiceProvider
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoipCarrier'
      responses:
        201:
          description: service provider successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        404:
          description: service provider not found
  /ServiceProviders/{ServiceProviderSid}/PredefinedCarriers/{PredefinedCarrierSid}:
    parameters:
      - name: ServiceProviderSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: PredefinedCarrierSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      summary: add a VoiPCarrier to a service provider based on PredefinedCarrier template
      operationId: createVoipCarrierFromTemplate
      responses:
        201:
          description:  voip carrier successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

  /ServiceProviders/{ServiceProviderSid}/SpeechCredentials/:
    parameters:
      - name: ServiceProviderSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      summary: create a speech credential for a service provider
      operationId: addSpeechCredentialForSeerviceProvider
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpeechCredential'
      responses:
        201:
          description: speech credential successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        404:
          description: credential not found
  /ServiceProviders/{ServiceProviderSid}/SpeechCredentials/{SpeechCredentialSid}:
    parameters:
      - name: ServiceProviderSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: SpeechCredentialSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: get a specific speech credential
      operationId: getSpeechCredential
      responses:
        200:
          description: retrieve speech credentials for a specified account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeechCredential'
        404:
          description: credential not found
    put:
      summary: update a speech credential
      operationId: updateSpeechCredential
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpeechCredentialUpdate'
      responses:
        204:
          description: credential successfully updated
        404:
          description: credential not found
        422:
          description: credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    delete:
      summary: delete a speech credential
      operationId: deleteSpeechCredential
      responses:
        204:
          description: credential successfully deleted
        404:
          description: credential not found
  /ServiceProviders/{ServiceProviderSid}/SpeechCredentials/{SpeechCredentialSid}/test:
    get:
      summary: test a speech credential
      operationId: testSpeechCredential
      parameters:
        - name: AccountSid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: SpeechCredentialSid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: credential test results
          content:
            application/json:
              schema:
                type: object
                properties:
                  tts:
                    type: object
                    properties:
                      status:
                        type: string
                        enum: 
                            - success 
                            - fail
                            - not tested
                      reason:
                        type: string
                  stt:
                    type: object
                    properties:
                      status:
                        type: string
                        enum: 
                            - success 
                            - fail
                      reason:
                        type: string
        404:
          description: credential not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /MicrosoftTeamsTenants:
    post:
      summary: provision a customer tenant for MS Teams
      operationId: createMsTeamsTenant
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                service_provider_sid:
                  type: string
                  format: uuid
                  example: 85f9c036-ba61-4f28-b2f5-617c23fa68ff
                account_sid:
                  type: string
                  format: uuid
                  example: 85f9c036-ba61-4f28-b2f5-617c23fa68ff
                application_sid:
                  type: string
                  format: uuid
                  example: 85f9c036-ba61-4f28-b2f5-617c23fa68ff
                tenant_fqdn:
                  type: string
                  example: customer.contoso.com
              required:
                - service_provider_sid
                - account
                - tenant_fqdn
      responses:
        201:
          description: tenant successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: list MS Teams tenants
      operationId: listMsTeamsTenants
      responses:
        200:
          description: list of tenants
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MsTeamsTenant'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /MicrosoftTeamsTenants/{TenantSid}:
    parameters:
      - name: TenantSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
    delete:
      summary: delete an MS Teams tenant
      operationId: deleteTenant
      responses:
        204:
          description: tenant successfully deleted
        404:
          description: tenant not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: retrieve an MS Teams tenant
      operationId: getTenant
      responses:
        200:
          description: tenant found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MsTeamsTenant'
        404:
          description: account not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

    put:
      summary: update tenant
      operationId: updateAccount
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MsTeamsTenant'
      responses:
        204:
          description: tenant updated
        404:
          description: tenant not found
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'


  /Accounts:
    post:
      summary: create an account
      operationId: createAccount
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: account name
                  example: foobar
                sip_realm:
                  type: string
                  description: sip realm for registration
                  example: sip.mycompany.com
                registration_hook:
                  $ref: '#/components/schemas/Webhook'
                  description: authentication webhook for registration
                service_provider_sid:
                  type: string
                  format: uuid
                  example: 85f9c036-ba61-4f28-b2f5-617c23fa68ff
              required: 
                - name
                - service_provider_sid
      responses:
        201:
          description: account successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

      callbacks:
        onRegistrationAttempt:
          '{$request.body#/registrationUrl}/auth':
            post:
              requestBody:
                description: |
                  provides details of the authentication request.  The receiving server is responsible for authenticating the 
                  request as per [RFC 2617](https://tools.ietf.org/html/rfc2617)
                content:
                  application/json:
                    schema:
                      required:
                        - method
                        - realm
                        - username
                        - expires
                        - nonce
                        - uri
                        - response
                      type: object
                      properties:
                        method:
                          type: string
                          description: sip request method
                          example: REGISTER
                        realm:
                          type: string
                          description: sip realm
                          example: mycompany.com
                        username:
                          type: string
                          description: sip username provided
                          example: daveh
                        expires:
                          type: number
                          description: expiration requested, in seconds
                          example: 3600
                        scheme:
                          type: string
                          description: encryption protocol
                          example: digest
                        nonce:
                          type: string
                          description: nonce value
                          example: InFriVGWVoKeCckYrTx7wg=="
                        uri:
                          type: string
                          format: uri
                          description: sip uri in request
                          example: sip:mycompany.com
                        algorithm:
                          type: string
                          description: encryption algorithm used, default to MD5 if not provided
                          example: MD5
                        qop:
                          type: string
                          description: qop value
                          example: auth 
                        cnonce:
                          type: string
                          description: cnonce value
                          example: 6b8b4567
                        nc:
                          type: string
                          description: nc value
                          example: 00000001
                        response:
                          type: string
                          description: digest value calculated by the client
                          example: be641cf7951ff23ab04c57907d59f37d
              responses:
                '200':
                  description: |
                    Your callback should return this HTTP status code in all cases.
                    if the request was authenticated and you wish to admit 
                    the client to the network, this is indicated by setting the 'response' 
                    attribute in the body to 'ok'
                  content:
                    application/json:
                      schema:
                        type: object
                        required:
                          - status
                        properties:
                          status:
                            type: string
                            description: indicates whether the request was successfully authenticated
                            enum:
                              - ok
                              - fail
                            example: ok
                          message:
                            type: string
                            description: a human-readable message
                            example: authentication granted
                          call_hook:
                            type: string
                            format: url
                            description: url of application to invoke when this device places a call
                          expires:
                            type: number
                            description: |
                              The expires value to grant to the requesting user.
                              If not provided, the expires value in the request is observed.
                              If provided, must be less than the requested expires value.
                          blacklist:
                            type: number
                            description: |
                              If provided, represents a period in seconds during which the source IP 
                              address should be blacklisted by the platform (0 means forever).

    get:
      summary: list accounts
      operationId: listAccounts
      responses:
        200:
          description: list of accounts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

  /Accounts/{AccountSid}:
    parameters:
      - name: AccountSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
    delete:
      summary: delete an account
      operationId: deleteAccount
      responses:
        204:
          description: account successfully deleted
        404:
          description: account not found
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: retrieve account
      operationId: getAccount
      responses:
        200:
          description: account found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        404:
          description: account not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

    put:
      summary: update account
      operationId: updateAccount
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
      responses:
        204:
          description: account updated
        404:
          description: account not found
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /Accounts/{AccountSid}/WebhookSecret:
    parameters:
      - name: AccountSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: regenerate
        in: query
        required: false
        schema:
          type: boolean
    get:
      summary: get webhook signing secret, regenerating if requested
      operationId: getWebhookSecret
      responses:
        200:
          description: secret
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook_secret:
                    type: string
        404:
          description: account not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

  /Accounts/{AccountSid}/ApiKeys:
    parameters:
      - name: AccountSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: get all api keys for an account
      operationId: getAccountApiKeys
      responses:
        200:
          description: list of api keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
        404:
          description: account not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

  /Accounts/{AccountSid}/SipRealms/{SipRealm}:
    parameters:
      - name: AccountSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: SipRealm
        in: path
        required: true
        schema:
          type: string
    post:
      summary: add or change the sip realm
      operationId: createSipRealm
      responses:
        204:
          description: sip_realm updated and DNS entries successfully created
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

  /Accounts/{AccountSid}/SpeechCredentials:
    parameters:
      - name: AccountSid
        in: path
        required: true
        schema:
          type: string
          format: uuid

    post:
      summary: add a speech credential
      operationId: createSpeechCredential
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpeechCredential'
      responses:
        201:
          description: speech credential successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: retrieve all speech credentials for an account
      operationId: listSpeechCredentials
      responses:
        200:
          description: retrieve speech credentials for a specified account
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpeechCredential'
        404:
          description: account not found
  /Accounts/{AccountSid}/SpeechCredentials/{SpeechCredentialSid}:
    parameters:
      - name: AccountSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: SpeechCredentialSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: get a specific speech credential
      operationId: getSpeechCredential
      responses:
        200:
          description: retrieve speech credentials for a specified account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeechCredential'
        404:
          description: credential not found
    put:
      summary: update a speech credential
      operationId: updateSpeechCredential
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpeechCredentialUpdate'
      responses:
        204:
          description: credential successfully deleted
        404:
          description: credential not found
        422:
          description: credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    delete:
      summary: delete a speech credential
      operationId: deleteSpeechCredential
      responses:
        204:
          description: credential successfully deleted
        404:
          description: credential not found
  /Accounts/{AccountSid}/SpeechCredentials/{SpeechCredentialSid}/test:
    get:
      summary: test a speech credential
      operationId: testSpeechCredential
      parameters:
        - name: AccountSid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: SpeechCredentialSid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: credential test results
          content:
            application/json:
              schema:
                type: object
                properties:
                  tts:
                    type: object
                    properties:
                      status:
                        type: string
                        enum: 
                            - success 
                            - fail
                            - not tested
                      reason:
                        type: string
                  stt:
                    type: object
                    properties:
                      status:
                        type: string
                        enum: 
                            - success 
                            - fail
                      reason:
                        type: string
        404:
          description: credential not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /Accounts/{AccountSid}/RecentCalls:
    parameters:
      - name: AccountSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: page
        required: true
        schema:
          type: number
          format: integer
          description: page number of data to retrieve
      - in: query
        name: count
        required: true
        schema:
          type: number
          format: integer
          description: number of rows to retrieve in each page set
      - in: query
        name: days
        required: false
        schema:
          type: number
          format: integer
          description: number of days back to retrieve, must be ge 1 and le 30
      - in: query
        name: start
        required: false
        schema:
          type: string
          format: date-time
          description: start date to retrieve
      - in: query
        name: end
        required: false
        schema:
          type: string
          format: date-time
          description: end date to retrieve
      - in: query
        name: answered
        required: false
        schema:
          type: string
          enum:
            - true
            - false
          description: retrieve only answered calls
      - in: query
        name: direction
        required: false
        schema:
          type: string
          enum:
            - inbound
            - outbound
    get:
      summary: retrieve recent calls for an account
      operationId: listRecentCalls
      responses:
        200:
          description: retrieve recent call records for a specified account
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: number
                    format: integer
                    description: total number of records in that database that match the filter criteria
                  batch:
                    type: number
                    format: integer
                    description: total number of records returned in this page set
                  page:
                    type: number
                    format: integer
                    description: page number that was requested, and is being returned
                  data:
                      type: array
                      items:
                        type: object
                        properties:
                          account_sid:
                            type: string
                            format: uuid
                          call_sid:
                            type: string
                            format: uuid
                          from:
                            type: string
                          to: 
                            type: string
                          answered:
                            type: boolean
                          sip_call_id:
                            type: string
                          sip_status:
                            type: number
                            format: integer
                          duration:
                            type: number
                            format: integer
                          attempted_at:
                            type: number
                            format: integer
                          answered_at:
                            type: number
                            format: integer
                          terminated_at:
                            type: number
                            format: integer
                          termination_reason:
                            type: string
                          host:
                            type: string
                          remote_host:
                            type: string
                          direction:
                            type: string
                            enum:
                              - inbound
                              - outbound
                          trunk:
                            type: string
                        required:
                          - account_sid
                          - call_sid
                          - attempted_at
                          - terminated_at
                          - answered
                          - direction
                          - from 
                          - to
                          - sip_status
                          - duration
        404:
          description: account not found
  /Accounts/{AccountSid}/Alerts:
    parameters:
      - name: AccountSid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: page
        required: true
        schema:
          type: number
          format: integer
          description: page number of data to retrieve
      - in: query
        name: count
        required: true
        schema:
          type: number
          format: integer
          description: number of rows to retrieve in each page set
      - in: query
        name: days
        required: false
        schema:
          type: number
          format: integer
          description: number of days back to retrieve, must be ge 1 and le 30
      - in: query
        name: start
        required: false
        schema:
          type: string
          format: date-time
          description: start date to retrieve
      - in: query
        name: end
        required: false
        schema:
          type: string
          format: date-time
          description: end date to retrieve
      - in: query
        name: alert_type
        required: false
        schema:
          type: string
          enum:
            - webhook-failure
            - webhook-connection-failure
            - webhook-auth-failure
            - no-tts
            - no-stt
            - tts-failure
            - stt-failure
            - no-carrier
            - call-limit
            - device-limit
            - api-limit
    get:
      summary: retrieve alerts for an account
      operationId: listAlerts
      responses:
        200:
          description: retrieve alerts for a specified account
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: number
                    format: integer
                    description: total number of records in that database that match the filter criteria
                  batch:
                    type: number
                    format: integer
                    description: total number of records returned in this page set
                  page:
                    type: number
                    format: integer
                    description: page number that was requested, and is being returned
                  data:
                      type: array
                      items:
                        type: object
                        properties:
                          time:
                            type: string
                            format: date-time
                          account_sid:
                            type: string
                            format: uuid
                          alert_type:
                            type: string
                          message:
                            type: string
                          detail:
                            type: string
                        required:
                          - time
                          - account_sid
                          - alert_type
                          - message
        404:
          description: account not found
  /Applications:
    post:
      summary: create application
      operationId: createApplication
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: application name
                account_sid:
                  type: string
                  format: uuid
                call_hook:
                  $ref: '#/components/schemas/Webhook'
                  description: application webhook to handle inbound voice calls
                call_status_hook:
                  $ref: '#/components/schemas/Webhook'
                  description: webhook to report call status events
                messaging_hook:
                  $ref: '#/components/schemas/Webhook'
                  description: application webhook to handle inbound SMS/MMS messages
                speech_synthesis_vendor:
                  type: string
                speech_synthesis_voice:
                  type: string
                speech_recognizer_vendor:
                  type: string
                speech_recognizer_language:
                  type: string
              required: 
                - name
                - account_sid
                - call_hook
                - call_status_hook
      responses:
        201:
          description: application successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulAdd'
        400:
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: list applications
      operationId: listApplications
      responses:
        200:
          description: list of applications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Application'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'

  /Applications/{ApplicationSid}:
    parameters:
      - name: ApplicationSid
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
    delete:
      summary: delete an application
      operationId: deleteApplication
      responses:
        204:
          description: application successfully deleted
        404:
          description: application not found
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: retrieve an application
      responses:
        200:
          description: application found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        404:
          description: application not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    put:
      summary: update application
      operationId: updateApplication
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application'
      responses:
        204:
          description: application updated
        404:
          description: application not found
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        
  
  /Accounts/{AccountSid}/Calls:
    post:
      summary: create a call
      operationId: createCall
      parameters:
      - name: AccountSid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - from
                - to
              type: object
              properties:
                application_sid:
                  type: string
                  format: uuid
                  description: The application to use to control this call.  Either applicationSid or url is required.
                call_hook:
                  $ref: '#/components/schemas/Webhook'
                call_status_hook:
                  $ref: '#/components/schemas/Webhook'
                  example: {"url": "https://acme.com/status", "method": "POST"}
                from:
                  type: string
                  description: The calling party number
                  example: "16172375089"
                timeout:
                  type: integer
                  description: the number of seconds to wait for call to be answered.  Defaults to 60.
                  example: 30
                tag:
                  type: object
                  description: initial set of customer-supplied metadata to associate with the call (see jambonz 'tag' verb)
                  example: {"callCount": 10}
                to:
                  $ref: '#/components/schemas/Target'
                  description: destination for call
      responses:
        201:
          description: call successfully created
          content:
            application/json:
              schema:
                required:
                  - sid
                properties:
                  sid:
                    type: string
                    format: uuid
                    example: 2531329f-fb09-4ef7-887e-84e648214436
        400:
          description: bad request
    get:
      summary: list calls
      operationId: listCalls
      parameters:
      - name: AccountSid
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: list of calls for a specified account
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Call'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /Accounts/{AccountSid}/Calls/{CallSid}:
    parameters:
      - name: AccountSid
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: CallSid
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
    delete:
      summary: delete a call
      operationId: deleteCall
      responses:
        204:
          description: call successfully deleted
        404:
          description: call not found
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    get:
      summary: retrieve a call
      operationId: getCall
      responses:
        200:
          description: call found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Call'
        404:
          description: call not found
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
    post:
      summary: update a call
      operationId: updateCall
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                call_hook:
                  $ref: '#/components/schemas/Webhook'
                call_status:
                  type: string
                  enum:
                    - completed
                    - no-answer
                listen_status:
                  type: string
                  enum:
                    - pause
                    - resume
                mute_status:
                  type: string
                  enum:
                    - mute
                    - unmute
                whisper:
                  $ref: '#/components/schemas/Webhook'         
      responses:
        202:
          description: Accepted
        400:
          description: bad request
        404:
          description: call not found
        422:
          description: unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        500:
          description: system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
  /Accounts/{AccountSid}/Messages:
    post:
      summary: create an outgoing SMS message
      operationId: createMessage
      parameters:
      - name: AccountSid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
      responses:
        201:
          description: call successfully created
          content:
            application/json:
              schema:
                required:
                  - sid
                properties:
                  sid:
                    type: string
                    format: uuid
                    example: 2531329f-fb09-4ef7-887e-84e648214436
                  providerResponse:
                    type: string
        400:
          description: bad request         
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
  schemas:
    Login:
      type: object
      properties:
        user_sid: 
          type: string
        api_token:
          type: string
        change_password:
          type: boolean
      required:
        - user_sid
    SuccessfulApiKeyAdd:
      type: object
      required:
        - sid
        - token
      properties:
        sid:
          type: string
        token:
          type: string
      example:
        sid: 9d26a637-1679-471f-8da8-7150266e1254
        token: 589cead6-de24-4689-8ac3-08ffaf102811
    SuccessfulAdd:
      type: object
      required:
        - sid
      properties:
        sid:
          type: string
      example:
        sid: 9d26a637-1679-471f-8da8-7150266e1254
    GeneralError:
      type: object
      required:
        - msg
      properties:
        msg:
          type: string
      example:
        msg: specific error detail will be provided here
    ServiceProvider:
      type: object
      properties:
        service_provider_sid:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        root_domain:
          type: string
        registration_hook:
          $ref: '#/components/schemas/Webhook'
          description: authentication webhook for registration
        ms_teams_fqdn:
          type: string
        test_number:
          type: string
          description: used for inbound testing for accounts on free plan
        test_application_name:
          type: string
          description: name of test application that can be used for new signups
        test_application_sid:
          type: string
          description: identifies test application that can be used for new signups
      required:
        - service_provider_sid
        - name
    VoipCarrier:
      type: object
      properties:
        voip_carrier_sid:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        account_sid:
          type: string
          format: uuid
        application_sid:
          type: string
          format: uuid          
        e164_leading_plus:
          type: boolean
        requires_register:
          type: boolean
        register_username:
          type: string
        register_sip_realm:
          type: string
        register_password:
          type: string
        tech_prefix:
          type: string
        inbound_auth_username:
          type: string
        inbound_auth_password:
          type: string
        diversion:
          type: string
        is_active:
          type: boolean
        smpp_system_id:
          type: string
        smpp_password:
          type: string
        smpp_inbound_system_id:
          type: string
        smpp_inbound_password:
          type: string
        smpp_enquire_link_interval:
          type: number
          format: integer
      required:
        - voip_carrier_sid
        - name
    SipGateway:
      type: object
      properties:
        sip_gateway_sid:
          type: string
          format: uuid
        ipv4:
          type: string
        port:
          type: number
        netmask:
          type: number
        voip_carrier_sid:
          type: string
          format: uuid
        inbound:
          type: boolean
        outbound:
          type: boolean
      required:
        - sip_gateway_sid
        - voip_carrier_sid
        - ipv4
        - port
        - netmask
    SmppGateway:
      type: object
      properties:
        smpp_gateway_sid:
          type: string
          format: uuid
        ipv4:
          type: string
        port:
          type: number
        netmask:
          type: number
        voip_carrier_sid:
          type: string
          format: uuid
        is_primary:
          type: boolean
        use_tls:
          type: boolean
        inbound:
          type: boolean
        outbound:
          type: boolean
      required:
        - smpp_gateway_sid
        - voip_carrier_sid
        - ipv4
        - port
        - netmask
    Account:
      type: object
      properties:
        account_sid:
          type: string
          format: uuid
        name:
          type: string
        sip_realm:
          type: string
        registration_hook:
          $ref: '#/components/schemas/Webhook'
          description: authentication webhook for registration
        device_calling_application_sid:
          type: string
          format: uuid
        service_provider_sid:
          type: string
          format: uuid
      required:
        - account_sid
        - name
        - service_provider_sid
    Application:
      type: object
      properties:
        application_sid:
          type: string
          format: uuid
        name:
          type: string
        account_sid:
          type: string
          format: uuid
        call_hook:
          $ref: '#/components/schemas/Webhook'
          description: application webhook for inbound voice calls
        call_status_hook:
          $ref: '#/components/schemas/Webhook'
          description: webhhok for reporting call status events
        messaging_hook:
          $ref: '#/components/schemas/Webhook'
          description: application webhook for inbound SMS/MMS
        speech_synthesis_vendor:
          type: string
        speech_synthesis_voice:
          type: string
        speech_recognizer_vendor:
          type: string
        speech_recognizer_language:
          type: string
      required:
        - application_sid
        - name
        - account_sid
    ApiKey:
      type: object
      properties:
        api_key_sid:
          type: string
          format: uuid
        token:
          type: string
          format: uuid
        account_sid:
          type: string
          format: uuid
        service_provider_sid:
          type: string
          format: uuid
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        last_used:
          type: string
          format: date-time
      required:
        - api_key_sid
        - token
    PhoneNumber:
      type: object
      properties:
        phone_number_sid:
          type: string
          format: uuid
        number:
          type: string
        voip_carrier_sid:
          type: string
          format: uuid
        account_sid:
          type: string
          format: uuid
        application_sid:
          type: string
          format: uuid
      required:
        - phone_number_sid
        - number
        - voip_carrier_sid
    Registration:
      type: object
      properties:
        registration_sid:
          type: string
          format: uuid
        username:
          type: string
        domain:
          type: string
        sip_contact:
          type: string
        sip_user_agent:
          type: string
      required:
        - registration_sid
        - username
        - domain
        - sip_contact
    Webhook:
      type: object
      properties:
        webhook_sid:
          type: string
          format: uuid
        url:
          type: string
          format: url
        method:
          type: string
          enum:
            - get
            - post
        username:
          type: string
        password:
          type: string
      required:
        - url
      example: {"url": "https://acme.com", "method": "POST"}
    MsTeamsTenant:
      type: object
      properties:
        service_provider_sid:
          type: string
          format: uuid
        account_sid:
          type: string
          format: uuid
        application_sid:
          type: string
          format: uuid
        tenant_fqdn:
          type: string
      required:
        - service_provider_sid
        - tenant_fqdn
    Call:
      type: object
      properties:
        account_sid:
          type: string
          format: uuid
        application_sid:
          type: string
          format: uuid
        call_id:
          type: string
        call_sid:
          type: string
          format: uuid
        call_status:
          type: string
          enum:
            - trying
            - ringing
            - alerting
            - in-progress
            - completed
            - busy
            - no-answer
            - failed
            - queued
        caller_name:
          type: string
        direction:
          type: string
          enum:
            - inbound
            - outbound 
        duration:
          type: integer
        from:
          type: string
        originating_sip_trunk_name:
          type: string
        parent_call_sid:
          type: string
          format: uuid
        service_url:
          type: string
        sip_status:
          type: integer
        to:
          type: string
      required:
        - account_sid
        - call_id
        - call_sid
        - call_status
        - direction
        - from
        - service_url
        - sip_status
        - to
    Target:
      properties:
        type:
          type: string
          enum:
            - phone
            - sip
            - user
        number:
          type: string
        sipUri:
          type: string
        name:
          type: string
        auth:
          type: object
          properties:
            username:
              type: string
            password:
              type: string
      required:
        - type
      example: {"type": "phone", "number": "+16172375080"}
    Message:
      properties:
        provider:
          type: string
        from:
          type: string
        to:
          type: string
        text:
          type: string
        media:
          type: string
      required:
        - from
        - to
      example: {"from": "13394445678", "to": "16173333456", "text": "please call when you can"}
    SpeechCredential:
      properties:
        speech_credential_sid:
          type: string
          format: uuid
        account_sid:
          type: string
          format: uuid
        vendor:
          type: string
          enum:
            - google
            - aws
        service_key:
          type: string
        access_key_id:
          type: string
        secret_access_key:
          type: string
        aws_region:
          type: string
        last_used:
          type: string
          format: date-time
        last_tested:
          type: string
          format: date-time
        use_for_tts:
          type: boolean
        use_for_stt:
          type: boolean
        tts_tested_ok:
          type: boolean
        stt_tested_ok:
          type: boolean
    SpeechCredentialUpdate:
      properties:
        use_for_tts:
          type: boolean
        use_for_stt:
          type: boolean
    UserAndAccountDetail:
      type: object
      properties:
        user:
          type: object
          properties:
            user_sid:
              type: string
            name: 
              type: string
            email:
              type: string
            phone:
              type: string
            service_provider_sid:
              type: string
            force_change:
              type: boolean
            provider:
              type: string
            provider_userid:
              type: string
            scope:
              type: string
            email_validated:
              type: boolean
            phone_validated:
              type: string
        account:
          type: object
          properties:
            account_sid:
              type: string
            sip_realm:
              type: string
            service_provider_sid:
              type: string
            registration_hook_sid:
              type: string
            device_calling_application_sid:
              type: string
            is_active:
              type: boolean
            created_at:
              type: string
              format: date-time
        testapp:
          type: object
          properties:
            application_sid:
              type: string
            name:
              type: string
            service_provider_sid:
              type: string
            account_sid:
              type: string
            call_hook_sid:
              type: string
            call_status_hook_sid:
              type: string
            messaging_hook_sid:
              type: string
            speech_synthesis_vendor:
              type: string
            speech_synthesis_language:
              type: string
            speech_synthesis_voice:
              type: string
            speech_recognizer_vendor:
              type: string
            speech_recognizer_language:
              type: string
        balance:
          type: object
          properties:
            currency:
              type: string
              enum:
                - USD 
                - EUR
            balance:
              type: number
            last_updated_at:
              type: string
              format: date-time
            created_at:
              type: string
              format: date-time
            last_transaction_id:
              type: string
        capacities:
          type: object
          properties:
            effective_start_date:
              type: string
              format: date-time
            effective_end_date:
              type: string
              format: date-time
            limit_sessions:
              type: integer
            limit_registrations:
              type: integer
        api_keys:
          type: array
          items:
            type: object
            properties:
              token:
                type: string
              last_used:
                type: string
                format: date-time
              created_at:
                type: string
                format: date-time
        products:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              category:
                type: string
              quantity:
                type: string
              in_starter_set:
                type: boolean
              product_sid:
                type: string
              effective_start_date:
                type: string
                format: date-time
              effective_end_date:
                type: string
                format: date-time
    UserProfile:
      type: object
      properties:
        user_sid: 
          type: string
          example: a5bce31e-a028-45cd-94c4-f121b72fec61
        account_sid:
          type: string
          example: a5bce31e-a028-45cd-94c4-f121b72fec61
        is_active:
          type: boolean
          description: indicates whether account is active
          example: true
        name:
          type: string
          description: full user name
          example: Dave Horton
        email:
          type: string
          description: email associated with user
          example: daveh@drachtio.org
        phone:
          type: string
          description: phone associated with user
        provider:
          type: string
          description: authentication provider
          enum:
            - github
            - google
            - local
          example: github
        scope:
          type: string
          description: scope of user permissions
          enum:
            - read-only
            - read-write
          example: read-write
        pristine:
          type: boolean
          description: true if account was newly created
          example: true
        email_validated:
          type: boolean
          description: indicates whether user has validated their email address
          example: true
        phone_validated:
          type: boolean
          description: indicates whether user has validated their mobile phone
          example: true
        tutorial_completion:
          type: number
          description: bitmask indicating which tutorials have been completed
          example: 1
        jwt:
          type: string
          description: json web token to be used as bearer token in API requests
      required:
        - user_sid
        - provider
        - name
        - email
        - scope
        - account_validated
        - pristine
        - jwt
        - is_active
    Charge:
      type: object
      properties:
        charge_sid:
          type: string
          format: uuid
        account_sid:
          type: string
          format: uuid
        application_sid:
          type: string
          format: uuid
        billed_at:
          type: string
          format: date-time
        billed_activity:
          type: string
          enum:
            - inbound-call
            - outbound-call
            - inbound-sms
            - outbound-sms
            - inbound-mms
            - outbound-mms
            - tts
            - stt
        call_billing_record_sid:
          type: string
          format: uuid
        message_record_sid:
          type: string
          format: uuid
        call_secs_billed:
          type: number
          format: integer
        tts_chars_billed:
          type: number
          format: integer
        stt_secs_billed:
          type: number
          format: integer
        amount_charged:
          type: number
          format: double
      required:
        - account_sid
        - billed_activity
        - amount_charged
    RecentCalls:
      type: object
      properties:
        account_sid:
          type: string
          format: uuid
        call_sid:
          type: string
          format: uuid
        from:
          type: string
        to: 
          type: string
        answered:
          type: boolean
        sip_call_id:
          type: string
        sip_status:
          type: number
          format: integer
        duration:
          type: number
          format: integer
        attempted_at:
          type: number
          format: integer
        answered_at:
          type: number
          format: integer
        terminated_at:
          type: number
          format: integer
        termination_reason:
          type: string
        host:
          type: string
        remote_host:
          type: string
        direction:
          type: string
          enum:
            - inbound
            - outbound
        trunk:
          type: string
      required:
        - account_sid
        - call_sid
        - attempted_at
        - terminated_at
        - answered
        - direction
        - from 
        - to
        - sip_status
        - duration
    Alert:
      type: object
      properties:
        alert_sid:
          type: string
          format: uuid
        call_sid:
          type: string
          format: uuid
        account_sid:
          type: string
          format: uuid
        application_sid:
          type: string
          format: uuid
        occurred_at:
          type: string
          format: date-time
        alert_type:
          type: string
          enum:
          - webhook-failed
          - bad-application-syntax
          - speech-operation-failed
          - limit-exceeded
        details:
          type: string
      required:
        - alert_sid
        - account_sid
        - occurred_at
        - alert_type
    Product:
      type: object
      properties:
        product_sid:
          type: string
        name:
          type: string
        description:
          type: string
        unit_label:
          type: string
        category:
          type: string
      required:
        - product_sid
        - name
        - unit_label
        - category
    PredefinedCarrier:
      type: object
      properties:
        predefined_carrier_sid:
          type: string
          format: uuid
        name:
          type: string
        requires_static_ip:
          type: boolean
        e164_leading_plus:
          type: boolean
        requires_register:
          type: boolean
        register_username:
          type: string
        register_sip_realm:
          type: string
        register_password:
          type: string
        tech_prefix:
          type: string
        inbound_auth_username:
          type: string
        inbound_auth_password:
          type: string
        diversion:
          type: string
      required:
        - predefined_carrier_sid
        - name
        - requires_static_ip
        - e164_leading_plus
        - requires_register

security:
  - bearerAuth: []