Alianza Public API

openapi: 3.0.3
info:
  title: Alianza Public API
  version: '2'
  description: |-
    Welcome to the Alianza Public API documentation, based on the OpenAPI 3.0 specification.

    _If you need the Swagger 2.0/OAS 2.0 version of the Alianza Public API, click [here](https://api.alianza.com/v2/apidocs/)._

    Authentication for most API endpoints requires the use of an <a href="data.html#xauthtoken" hidden>X-AUTH-TOKEN</a> X-AUTH-TOKEN header. Please reach out to your account manager for login credentials.
    To obtain an X-AUTH-TOKEN, use the POST /v2/authorize endpoint under the <a href="#/~operation/Authorize/">Authorize</a> group, which will return an authToken value. 
    Click the Authorize button below and provide the returned token. 

    <div hidden>
    Some useful links:
    - [Brief introduction to Alianza components](data.html) such as Partitions, Accounts and Users
    </div>
servers:
  - url: https://api.d2.alianza.com
    description: Development
  - url: https://api.q2.alianza.com
    description: QA
  - url: https://api.b2.alianza.com
    description: Beta
  - url: https://api.alianza.com
    description: Production
security:
  - X-Auth-Token: []
tags:
  - name: Account
    description: An account is the basic unit of telephone service for a business or home.
  - name: Account Device
    description: A device is an equipment, such as a VoIP or a soft phone, associated to an account.
  - name: Account Device Line
    description: A device line helps define the different features available, depending on the equipment type being used.
  - name: Account Prevalidate
    description: Operations for validating voice service of an account.
  - name: Account User
    description: An Account User (also known as an account manager) does not have a device on the system and has access to manage an account.
  - name: Address
    description: Search and validate addresses.
  - name: Asynchronous JOB Tracker
    description: Operations for managing asynchronous jobs
  - name: Authorize
    description: Retrieves authorization tokens and login info.
  - name: Brand Settings
    description: Brand settings toggles
  - name: Bulk Operation Collection
    description: Manage collections used in the bulk process.
  - name: Bulk Operation Job
    description: Manage jobs used in the bulk process.
  - name: Business Line
    description: Operations for managing business lines.
  - name: Business Line Hunt Group
    description: Operations for managing business line hunt groups
  - name: Call Group
    description: Call groups are the call destinations of <a href="#/~operation/Paging%20Group/">Paging</a> and <a href="#/~operation/Pickup%20Group/">Pickup</a> groups.
  - name: Calling Plan
    description: Calling plans allow you to control where your customers are allowed to call and what, if any, the cost should be for those calls.  Each of your plans can be set up with a number of included minutes or a per-minute rate, depending on how you want to charge for services.  The calling plans created at the partition level can be assigned to individual accounts and users based on their needs or the bundle they purchased.
  - name: Calling Plan Product
    description: Operations for managing calling plan products.
  - name: Call Parking Spot
    description: Operations for managing call parking spot.
  - name: CDRs
    description: A call detail record (CDR) documents the details of a telephone call.
  - name: Cymbus User Product
    description: Operations for managing Cymbus User Product
  - name: Device
    description: Convenience operations related to devices
  - name: Device (Deprecated)
    description: These endpoints are all deprecated. Use the Account Device and Account Device Lines instead.
  - name: Device Inventory Management
    description: Operations for managing device inventories.
  - name: Document Repository
    description: Operations for managing documents
  - name: Dynamic Inventory
    description: Operations for managing dynamic inventories of telephone numbers.
  - name: Edge Node
    description: Operations for managing edge nodes
  - name: Emergency Notification
    description: These endpoints manage extra notifications which occur when a 911 call is made on the Alianza switch, in compliance with Kari's law.
  - name: End User
    description: End Users may have one or more devices and telephone numbers assigned to them.
  - name: Inbound Rate Plan Product
    description: Operations for managing inbound rate plan products.
  - name: IVR
    description: An IVR is a menu system that allows callers to navigate through a series of options to reach a destination.
  - name: Language Reference
    description: Get language information.
  - name: Local Calling Areas
    description: Operations for managing local calling areas.
  - name: Management User
    description: Management users are employees of a service provider who can setup and administrate their partition.
  - name: Media
    description: Operations for managing audio files which are used for hold music or interactive voice recording prompts.
  - name: Paging Group
    description: Paging groups contain <a href="#/~operation/Call%20Group/">call groups</a> as destinations for a one way broadcast communication.
  - name: Partition
    description: A partition is the logical separation between Alianza customers in the platform. Each partition has its own ID, which is required for every API interaction.
  - name: Pickup Group
    description: Pickup groups contain <a href="#/~operation/Call%20Group/">call groups</a> as destinations for a call that will ring simultaneously to all members of the groups.
  - name: Port
    description: Telephone number port requests are not initiated by any of these endpoints, but the ongoing management of an existing port request is handled here.
  - name: Rate Center Inventory
    description: Operations for managing rate centers. A rate center is a geographical area used to determine the boundaries for local calling, billing, and assigning specific phone numbers, which can encompass multiple area codes.
  - name: Reference Resources
    description: Retrieve a list of the resources supported by Alianza.
  - name: Report
    description: Operations for managing reports.
  - name: Security Groups
    description: Security groups (also called roles) are assigned to management users. These assignments control more granular access to the Alianza API.
  - name: Service Activation
    description: Operations for managing service activation.
  - name: SIP Trunk
    description: Operations for managing SIP trunks
  - name: Sip Trunk Caller ID Mapping
    description: Operations for managing Sip Trunk Caller ID mappings
  - name: SIP Trunk Group
    description: Operations for managing SIP trunk groups
  - name: Single Sign On - SSO
    description: Operations for managing SSO
  - name: SSO Authentication
    description: Operations for managing SSO authentication flows and callbacks
  - name: SSO Configuration
    description: Operations for managing SSO configurations for accounts and partitions
  - name: SSO Exemptions
    description: Operations for managing SSO exemptions for accounts and partitions
  - name: Specialty Line
    description: Managed Specialty Lines uses carefully curated CPE (Customer Premises Equipment) that can replace virtually any specialty use hardline for critical business and life safety systems.
  - name: Supported Rate Centers
    description: A rate center is a geographical area used to determine the boundaries for local calling, billing, and assigning specific phone numbers, which can encompass multiple area codes.
  - name: Telephone Number
    description: Operations for managing telephone numbers.
  - name: User Groups
    description: Operations for managing user groups.
  - name: Voicemail Box
    description: Operations for managing voicemail boxes.
  - name: Virtual Fax Line
    description: Operations for managing virtual fax lines.
  - name: Virtual Fax
    description: Operations for managing virtual fax.
  - name: Voicemail Message
    description: Operations for managing voicemail messages.
paths:
  /v2/address/state/{state}/city/{city}/zipcode:
    get:
      tags:
        - Address
      summary: Retrieves a zip code list for US cities
      description: Use to retrieve a set of ZipCodeX objects for the given city and state in the US.
      operationId: getZipCodeByCityAndState
      parameters:
        - name: city
          in: path
          required: true
          schema:
            type: string
        - name: state
          in: path
          description: A two-letter state abbreviation in the US
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ZipcodeX'
                uniqueItems: true
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '404':
          description: Zipcodes not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
  /v2/address/typeahead:
    get:
      tags:
        - Address
      summary: Retrieves a list of addresses
      description: Retrieves a list of strings containing addresses. Use to build features like autocomplete search. As an address is typed in a list of potential addresses will be returned. A partial address can be used, for example, for zipcode 13905, just inputting the number 135 will bring back several addresses in the zipcode that begin with 135. If 135 F is input several addresses are brought back, including Front St.
      operationId: typeAhead
      parameters:
        - name: address
          in: query
          description: Address to parse.
          required: true
          schema:
            type: string
        - name: country
          in: query
          description: Alianza supports accounts in the USA and Canada. If not sure, use UNK (unknown).
          required: true
          schema:
            type: string
            enum:
              - USA
              - CAN
              - UNK
        - name: postalCode
          in: query
          description: Postal / Zip code of address
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '404':
          description: Zipcodes not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
  /v2/address/validate:
    get:
      tags:
        - Address
      summary: Parses and validates an address
      description: Use to parse an address line into an AddressValidationX object and validate it.  Address format should be in the form of number, street name, street suffix, ie 135 Front St.  Please note that the <a href="#/~schema/AddressValidationX">addressValidation.customerServiceRecordX.country</a> is not currently being populated in the response.
      operationId: validateAddress
      parameters:
        - name: address
          in: query
          description: Address to parse
          required: true
          schema:
            type: string
        - name: country
          in: query
          description: Alianza supports accounts in the USA and Canada. If not sure, use UNK (unknown).
          required: true
          schema:
            type: string
            enum:
              - USA
              - CAN
              - UNK
        - name: postalCode
          in: query
          description: Postal / Zip code of address
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationX'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '404':
          description: Zipcodes not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
  /v2/app-branding/brand-settings:
    get:
      tags:
        - Brand Settings
      summary: Retrieve the general settings for all app brands of a partition.
      operationId: getBrandSettingsByPartitionId
      parameters:
        - name: partition
          in: query
          description: PartitionId for brands being retrieved.
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BrandSettingsDTO'
        '400':
          description: Invalid Partition ID supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandErrorResponse'
        '404':
          description: Partition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandErrorResponse'
    post:
      tags:
        - Brand Settings
      summary: Provision general settings associated to app branding for a new brand.
      operationId: createBrandByPartitionId
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBrandSettings'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandSettingsDTO'
        '400':
          description: Invalid Partition ID supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandErrorResponse'
        '404':
          description: Partition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandErrorResponse'
        '409':
          description: 'Conflict: Brand already exists for the partition'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandErrorResponse'
  /v2/app-branding/brand-settings/{brandId}:
    get:
      tags:
        - Brand Settings
      summary: Retrieve the general settings associated to a specific brand.
      operationId: getBrandSettingsById
      parameters:
        - name: brandId
          in: path
          description: ID of brand to return
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandSettingsDTO'
        '400':
          description: Invalid ID supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandErrorResponse'
        '404':
          description: Brand not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandErrorResponse'
    put:
      tags:
        - Brand Settings
      summary: Provision the general settings associated to a specific brand.
      operationId: updateBrandSettingsById
      parameters:
        - name: brandId
          in: path
          description: ID of brand whose settings are being updated
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandSettingsDTO'
      responses:
        '200':
          description: Settings updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandSettingsDTO'
        '404':
          description: Brand not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandErrorResponse'
        '409':
          description: Modification of brandingCompleted is not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandErrorResponse'
  /v2/authorize:
    put:
      tags:
        - Authorize
      summary: Update password
      description: Used to update an existing password
      operationId: changePassword
      requestBody:
        description: Login credentials with new password
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Login'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginTokenX'
        '400':
          description: FailedToUpdate, when new password doesn't satisfy the password requirements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
      security: []
      x-codegen-request-body-name: body
    post:
      tags:
        - Authorize
      summary: Login with login credentials
      description: 'Takes login credentials and returns token if successfully validates '
      operationId: logUserIn
      requestBody:
        description: Login credentials
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Login'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginTokenX'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
      security: []
      x-codegen-request-body-name: body
  /v2/authorize/jwt:
    post:
      tags:
        - Authorize
      summary: Login with token
      description: Takes a jwt and returns login token if successfully validates. For validating a jwt, Alianza needs your public key, please contact your account manager.
      operationId: loginWithJWT
      deprecated: true
      requestBody:
        content:
          application/json:
            schema:
              type: string
        required: false
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginTokenX'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
      security: []
      x-codegen-request-body-name: body
  /v2/authorize/logout:
    put:
      tags:
        - Authorize
      summary: Log out a user
      description: Log out user for the given token in the header
      operationId: logOut
      responses:
        '200':
          description: Logout completed successfully
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
  /v2/authorize/sso:
    get:
      tags:
        - Single Sign On - SSO
      summary: Get SSO data
      description: Returns data needed for the UI to initiate Single Sign On
      operationId: getClientId
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SsoDataX'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
      security: []
    post:
      tags:
        - Single Sign On - SSO
      summary: Authorization Code Exchange
      description: Pass the SSO response authorization code here to exchange it for an API authorization token
      operationId: getLoginInfo_1
      parameters:
        - name: code
          in: query
          schema:
            type: string
        - name: redirect_uri
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginTokenX'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
      security: []
  /v2/authn/sso-config/accounts/{accountId}:
    get:
      tags:
        - SSO Configuration
      summary: List SSO configurations for account
      description: Retrieves all SSO configurations associated with a specific account.
      operationId: listSSOConfigsByAccountId
      parameters:
        - name: accountId
          in: path
          required: true
          description: ID of account, refers to <a href="#/~schema/Account">account.id</a>
          schema:
            type: string
      responses:
        '200':
          description: SSO configurations retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SSOConfigResponse'
        '401':
          description: Unauthorized - Invalid or missing X-Auth-Token
        '404':
          description: Not Found - Account not found or no SSO configurations exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '500':
          description: Internal Server Error - Failed to retrieve configurations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
    put:
      tags:
        - SSO Configuration
      summary: Update SSO configuration
      description: Updates an existing SSO configuration for an account.
      operationId: updateSSOConfig
      parameters:
        - name: accountId
          in: path
          required: true
          description: ID of account, refers to <a href="#/~schema/Account">account.id</a>
          schema:
            type: string
      requestBody:
        required: true
        description: Updated SSO configuration details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteSSOConfigRequest'
          multipart/form-data:
            schema:
              type: object
              required:
                - ssoName
                - identityProviderSignInUrl
                - externalIdAttributeFieldMapping
                - identityProviderSigningCertificate
              properties:
                ssoName:
                  type: string
                  description: SSO configuration name
                identityProviderSignInUrl:
                  type: string
                  format: uri
                  description: Identity provider sign-in endpoint URL
                externalIdAttributeFieldMapping:
                  type: string
                  description: External ID attribute field mapping in SAML response
                externalEmailAttributeFieldMapping:
                  type: string
                  description: External email attribute field mapping in SAML response
                identityProviderSigningCertificate:
                  type: string
                  format: binary
                  description: IdP signing certificate file (PEM or CER format)
                samlRequestProtocolBinding:
                  $ref: '#/components/schemas/SAMLRequestProtocolBinding'
      responses:
        '200':
          description: SSO configuration updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SSOConfigResponse'
        '400':
          description: Bad Request - Invalid request parameters or validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '401':
          description: Unauthorized - Invalid or missing X-Auth-Token
        '404':
          description: Not Found - SSO configuration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '500':
          description: Internal Server Error - Failed to update configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
  /v2/authn/sso-config/accounts/{accountId}/{ssoName}/status:
    post:
      tags:
        - SSO Configuration
      summary: Enable SSO configuration
      description: Enables or disables the SSO configuration for an account.
      operationId: enableSSO
      parameters:
        - name: accountId
          in: path
          required: true
          description: ID of account, refers to <a href="#/~schema/Account">account.id</a>
          schema:
            type: string
        - name: ssoName
          in: path
          required: true
          description: SSO configuration name
          schema:
            type: string
        - name: enabled
          in: query
          required: false
          description: Set true to enable SSO config
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: SSO configuration enabled successfully
        '400':
          description: Bad Request - Invalid status transition or configuration incomplete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '401':
          description: Unauthorized - Invalid or missing X-Auth-Token
        '404':
          description: Not Found - SSO configuration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '500':
          description: Internal Server Error - Failed to enable configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
  /v2/authn/sso-config/accounts/{accountId}/signing-certificate:
    get:
      tags:
        - SSO Configuration
      summary: Download signing certificate
      description: Downloads the service provider signing certificate for SAML configuration.
      operationId: downloadSigningCertificate
      parameters:
        - name: accountId
          in: path
          required: true
          description: ID of account, refers to <a href="#/~schema/Account">account.id</a>
          schema:
            type: string
        - name: format
          in: query
          required: false
          description: Certificate format
          schema:
            type: string
            enum:
              - pem
              - cer
            default: pem
      responses:
        '200':
          description: Certificate downloaded successfully
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized - Invalid or missing X-Auth-Token
        '404':
          description: Not Found - Account or certificate not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
        '500':
          description: Internal Server Error - Failed to retrieve certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiException'
  /v2/authn/sso-config/accounts/{accountId}/user-validation:
    get:
      tags:
        - SSO Configuration
      summary: Validate user against account SSO configuration
      description: Validates the user context for the account-level SSO configuration.
      operationId: getUserValidation
      parameters:
        - name: accountId
          in: path
          required: true
          description: ID of account, refers to <a href="#/~schema/Account">account.id</a>
          schema:
            type: string
        - name: partitionId
          in: query
          required: true
          description: ID of partition, refers to <a href="#/~schema/PartitionX">partition.id</a>
          schema:
            type: string
        - name: userId
          in: query
          required: false
          description: ID of end-user
          schema

# --- truncated at 32 KB (948 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/alianza/refs/heads/main/openapi/alianza-openapi-original.yml