Telnyx Managed Accounts API

openapi: 3.2.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Managed Accounts API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Managed Accounts operations
  name: Managed Accounts
paths:
  /managed_accounts:
    get:
      description: Lists the accounts managed by the current user. Users need to be explictly approved by Telnyx in order to become manager accounts.
      operationId: ListManagedAccounts
      parameters:
      - $ref: '#/components/parameters/managed-accounts_FilterConsolidated'
      - $ref: '#/components/parameters/PageConsolidated'
      - $ref: '#/components/parameters/managed-accounts_Sort'
      - $ref: '#/components/parameters/IncludeCancelledAccounts'
      responses:
        '200':
          $ref: '#/components/responses/ListManagedAccountsResponse'
        '401':
          $ref: '#/components/responses/managed-accounts_UnauthorizedResponse'
      summary: Lists accounts managed by the current user
      tags:
      - Managed Accounts
      x-endpoint-cost: medium
      x-latency-category: responsive
    post:
      description: Create a new managed account owned by the authenticated user. You need to be explictly approved by Telnyx in order to become a manager account.
      operationId: CreateManagedAccount
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateManagedAccountRequest'
        description: Parameters that define the managed account to be created
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ManagedAccountResponse'
        '401':
          $ref: '#/components/responses/managed-accounts_UnauthorizedResponse'
        '422':
          $ref: '#/components/responses/UnprocessableManagedAccountEntity'
      summary: Create a new managed account
      tags:
      - Managed Accounts
      x-endpoint-cost: medium
      x-latency-category: responsive
  /managed_accounts/allocatable_global_outbound_channels:
    get:
      description: Display information about allocatable global outbound channels for the current user. Only usable by account managers.
      operationId: ListAllocatableGlobalOutboundChannels
      responses:
        '200':
          $ref: '#/components/responses/ListManagedAccountsAllocatableGlobalOutboundChannelsResponse'
        '401':
          $ref: '#/components/responses/managed-accounts_UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/managed-accounts_ForbiddenResponse'
      summary: Display information about allocatable global outbound channels for the current…
      tags:
      - Managed Accounts
      x-endpoint-cost: medium
      x-latency-category: responsive
  /managed_accounts/{id}:
    get:
      description: Retrieves the details of a single managed account.
      operationId: RetrieveManagedAccount
      parameters:
      - description: Managed Account User ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/ManagedAccountResponse'
        '401':
          $ref: '#/components/responses/managed-accounts_UnauthorizedResponse'
        '404':
          description: Resource not found
      summary: Retrieve a managed account
      tags:
      - Managed Accounts
      x-latency-category: responsive
    patch:
      description: Update a single managed account.
      operationId: UpdateManagedAccount
      parameters:
      - description: Managed Account User ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateManagedAccountRequest'
        description: Parameters that define the updates to the managed account
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ManagedAccountResponse'
        '401':
          $ref: '#/components/responses/managed-accounts_UnauthorizedResponse'
        '404':
          description: Resource not found
        '422':
          $ref: '#/components/responses/UnprocessableManagedAccountEntity'
      summary: Update a managed account
      tags:
      - Managed Accounts
      x-latency-category: responsive
  /managed_accounts/{id}/actions/disable:
    post:
      description: Disables a managed account, forbidding it to use Telnyx services, including sending or receiving phone calls and SMS messages. Ongoing phone calls will not be affected. The managed account and its sub-users will no longer be able to log in via the mission control portal.
      operationId: DisableManagedAccount
      parameters:
      - description: Managed Account User ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/ManagedAccountResponse'
        '401':
          $ref: '#/components/responses/managed-accounts_UnauthorizedResponse'
        '404':
          description: Resource not found
        '422':
          $ref: '#/components/responses/UnprocessableManagedAccountEntity'
      summary: Disables a managed account
      tags:
      - Managed Accounts
      x-latency-category: responsive
  /managed_accounts/{id}/actions/enable:
    post:
      description: Enables a managed account and its sub-users to use Telnyx services.
      operationId: EnableManagedAccount
      parameters:
      - description: Managed Account User ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                reenable_all_connections:
                  default: false
                  description: 'When true, all connections owned by this managed account will automatically be re-enabled. Note: Any connections that do not pass validations will not be re-enabled.'
                  example: true
                  type: boolean
              type: object
        description: Additional parameters for what to do when enabling the managed account
        required: false
      responses:
        '200':
          $ref: '#/components/responses/ManagedAccountResponse'
        '401':
          $ref: '#/components/responses/managed-accounts_UnauthorizedResponse'
        '404':
          description: Resource not found
        '422':
          $ref: '#/components/responses/UnprocessableManagedAccountEntity'
      summary: Enables a managed account
      tags:
      - Managed Accounts
      x-latency-category: responsive
  /managed_accounts/{id}/update_global_channel_limit:
    patch:
      description: Update the amount of allocatable global outbound channels allocated to a specific managed account.
      operationId: UpdateManagedAccountGlobalChannelLimit
      parameters:
      - description: Managed Account User ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateManagedAccountGlobalChannelLimitRequest'
        description: Parameters that define the changes to the global outbounds channels for the managed account
        required: true
      responses:
        '200':
          $ref: '#/components/responses/UpdateManagedAccountGlobalChannelLimitResponse'
        '401':
          $ref: '#/components/responses/managed-accounts_UnauthorizedResponse'
        '404':
          description: Resource not found
        '422':
          $ref: '#/components/responses/UnprocessableManagedAccountEntity'
      summary: Update the amount of allocatable global outbound channels allocated to a…
      tags:
      - Managed Accounts
      x-latency-category: responsive
components:
  schemas:
    ManagedAccount:
      properties:
        api_key:
          description: The managed account's V2 API access key
          example: KEY01236170692E74656C6E79782E636F6D_YmlnIGlyb24gaXMgZGVhZA
          type: string
        api_token:
          description: The managed account's V1 API token
          example: x6oexQNHTs-fZ7-QsDMOeg
          type: string
        api_user:
          description: The manager account's email, which serves as the V1 API user identifier
          example: managed_account@example.com
          type: string
        balance:
          $ref: '#/components/schemas/ManagedAccountBalance'
        created_at:
          description: ISO 8601 formatted date indicating when the resource was created.
          example: '2018-02-02T22:25:27.521Z'
          type: string
        email:
          description: The managed account's email.
          example: user@example.com
          format: email
          type: string
        id:
          description: Uniquely identifies the managed account.
          example: f65ceda4-6522-4ad6-aede-98de83385123
          format: uuid
          type: string
        managed_account_allow_custom_pricing:
          description: Boolean value that indicates if the managed account is able to have custom pricing set for it or not. If false, uses the pricing of the manager account. Defaults to false. There may be time lag between when the value is changed and pricing changes take effect.
          example: true
          type: boolean
        manager_account_id:
          description: The ID of the manager account associated with the managed account.
          example: f65ceda4-6522-4ad6-aede-98de83385123
          type: string
        organization_name:
          description: The organization the managed account is associated with.
          example: Example Company LLC
          type: string
        record_type:
          description: Identifies the type of the resource.
          enum:
          - managed_account
          example: managed_account
          type: string
        rollup_billing:
          description: Boolean value that indicates if the billing information and charges to the managed account "roll up" to the manager account. If true, the managed account will not have its own balance and will use the shared balance with the manager account. This value cannot be changed after account creation without going through Telnyx support as changes require manual updates to the account ledger. Defaults to false.
          example: false
          type: boolean
        updated_at:
          description: ISO 8601 formatted date indicating when the resource was updated.
          example: '2018-02-02T22:25:27.521Z'
          type: string
      required:
      - record_type
      - id
      - email
      - api_key
      - api_user
      - api_token
      - manager_account_id
      - created_at
      - updated_at
      title: ManagedAccount
      type: object
    UnprocessableEntityError:
      properties:
        code:
          type: string
          x-format: int64
        detail:
          type: string
        meta:
          additionalProperties: true
          type: object
        source:
          properties:
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              format: json-pointer
              type: string
          type: object
        title:
          type: string
      required:
      - code
      - title
      type: object
    SingleManagedAccountGlobalOutboundChannels:
      example:
        channel_limit: 30
        email: allocate_demo@customer.com
        id: 096abcde-1122-3344-ab77-ff0123456789
        manager_account_id: beeabcde-1122-3344-ab77-ff0123456789
        record_type: managed_account_global_outbound_settings
      properties:
        channel_limit:
          description: Integer value that indicates the number of allocatable global outbound channels that are allocated to the managed account. If the value is 0 then the account will have no usable channels and will not be able to perform outbound calling.
          example: 30
          type: integer
        email:
          description: The email of the managed account.
          example: customer@example.org
          type: string
        id:
          description: The user ID of the managed account.
          example: 096abcde-1122-3344-ab77-ff0123456789
          type: string
        manager_account_id:
          description: The user ID of the manager of the account.
          example: beeabcde-1122-3344-ab77-ff0123456789
          type: string
        record_type:
          description: The name of the type of data in the response.
          example: managed_account_global_outbound_settings
          type: string
      title: Global Outbound Channels Details for a Managed Account
      type: object
    ManagedAccountBalance:
      example:
        available_credit: '400.00'
        balance: '300.00'
        credit_limit: '100.00'
        currency: USD
        record_type: balance
      properties:
        available_credit:
          description: Available amount to spend (balance + credit limit)
          example: '400.00'
          type: string
          x-format: decimal
        balance:
          description: The account's current balance.
          example: '300.00'
          type: string
          x-format: decimal
        credit_limit:
          description: The account's credit limit.
          example: '100.00'
          type: string
          x-format: decimal
        currency:
          description: The ISO 4217 currency identifier.
          example: USD
          type: string
          x-format: iso4217
        record_type:
          description: Identifies the type of the resource.
          enum:
          - balance
          example: balance
          type: string
      type: object
    CreateManagedAccountRequest:
      example:
        business_name: Larry's Cat Food Inc
        email: larry_cat_food@customer.org
        managed_account_allow_custom_pricing: false
        password: 3jVjLq!tMuWKyWx4NN*CvhnB
        rollup_billing: false
      properties:
        business_name:
          description: The name of the business for which the new managed account is being created, that will be used as the managed accounts's organization's name.
          example: Larry's Cat Food Inc
          type: string
        email:
          description: The email address for the managed account. If not provided, the email address will be generated based on the email address of the manager account.
          example: new_managed_account@customer.org
          type: string
        managed_account_allow_custom_pricing:
          description: Boolean value that indicates if the managed account is able to have custom pricing set for it or not. If false, uses the pricing of the manager account. Defaults to false. This value may be changed after creation, but there may be time lag between when the value is changed and pricing changes take effect.
          example: false
          type: boolean
        password:
          description: Password for the managed account. If a password is not supplied, the account will not be able to be signed into directly. (A password reset may still be performed later to enable sign-in via password.)
          example: 3jVjLq!tMuWKyWx4NN*CvhnB
          type: string
        rollup_billing:
          description: Boolean value that indicates if the billing information and charges to the managed account "roll up" to the manager account. If true, the managed account will not have its own balance and will use the shared balance with the manager account. This value cannot be changed after account creation without going through Telnyx support as changes require manual updates to the account ledger. Defaults to false.
          example: false
          type: boolean
      required:
      - business_name
      title: Create Managed Account Request
      type: object
    UpdateManagedAccountRequest:
      example:
        managed_account_allow_custom_pricing: true
      properties:
        managed_account_allow_custom_pricing:
          description: Boolean value that indicates if the managed account is able to have custom pricing set for it or not. If false, uses the pricing of the manager account. Defaults to false. This value may be changed, but there may be time lag between when the value is changed and pricing changes take effect.
          example: false
          type: boolean
      title: Update Managed Account Request
      type: object
    PaginationMeta:
      properties:
        page_number:
          example: 2
          type: integer
        page_size:
          example: 25
          type: integer
        total_pages:
          example: 3
          type: integer
        total_results:
          example: 55
          type: integer
      type: object
    ManagedAccountMultiListing:
      properties:
        api_user:
          description: The manager account's email, which serves as the V1 API user identifier
          example: managed_account@example.com
          type: string
        created_at:
          description: ISO 8601 formatted date indicating when the resource was created.
          example: '2018-02-02T22:25:27.521Z'
          type: string
        email:
          description: The managed account's email.
          example: user@example.com
          format: email
          type: string
        id:
          description: Uniquely identifies the managed account.
          example: f65ceda4-6522-4ad6-aede-98de83385123
          format: uuid
          type: string
        managed_account_allow_custom_pricing:
          description: Boolean value that indicates if the managed account is able to have custom pricing set for it or not. If false, uses the pricing of the manager account. Defaults to false. There may be time lag between when the value is changed and pricing changes take effect.
          example: true
          type: boolean
        manager_account_id:
          description: The ID of the manager account associated with the managed account.
          example: f65ceda4-6522-4ad6-aede-98de83385123
          type: string
        organization_name:
          description: The organization the managed account is associated with.
          example: Example Company LLC
          type: string
        record_type:
          description: Identifies the type of the resource.
          enum:
          - managed_account
          example: managed_account
          type: string
        rollup_billing:
          description: Boolean value that indicates if the billing information and charges to the managed account "roll up" to the manager account. If true, the managed account will not have its own balance and will use the shared balance with the manager account. This value cannot be changed after account creation without going through Telnyx support as changes require manual updates to the account ledger. Defaults to false.
          example: false
          type: boolean
        updated_at:
          description: ISO 8601 formatted date indicating when the resource was updated.
          example: '2018-02-02T22:25:27.521Z'
          type: string
      required:
      - record_type
      - id
      - email
      - api_user
      - manager_account_id
      - created_at
      - updated_at
      title: ManagedAccount
      type: object
    UpdateManagedAccountGlobalChannelLimitRequest:
      example:
        channel_limit: 30
      properties:
        channel_limit:
          description: Integer value that indicates the number of allocatable global outbound channels that should be allocated to the managed account. Must be 0 or more. If the value is 0 then the account will have no usable channels and will not be able to perform outbound calling.
          example: 30
          type: integer
      title: Update Managed Account Global Outbound Channels Request
      type: object
    ManagedAccountsGlobalOutboundChannels:
      example:
        allocatable_global_outbound_channels: 500
        record_type: allocatable_global_outbound_channels
        total_global_channels_allocated: 135
      properties:
        allocatable_global_outbound_channels:
          description: The total amount of allocatable global outbound channels available to the authenticated manager. Will be 0 if the feature is not enabled for their account.
          example: 500
          type: integer
        managed_account_allow_custom_pricing:
          description: Boolean value that indicates if the managed account is able to have custom pricing set for it or not. If false, uses the pricing of the manager account. Defaults to false. This value may be changed, but there may be time lag between when the value is changed and pricing changes take effect.
          example: false
          type: boolean
        record_type:
          description: The type of the data contained in this record.
          example: allocatable_global_outbound_channels
          type: string
        total_global_channels_allocated:
          description: The total number of allocatable global outbound channels currently allocated across all managed accounts for the authenticated user. This includes any amount of channels allocated by default at managed account creation time. Will be 0 if the feature is not enabled for their account.
          example: 135
          type: integer
      title: Managed Accounts Global Outbound Channels
      type: object
  responses:
    ListManagedAccountsResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/ManagedAccountMultiListing'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            type: object
      description: Successful response with a list of managed accounts.
    ListManagedAccountsAllocatableGlobalOutboundChannelsResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/ManagedAccountsGlobalOutboundChannels'
            type: object
      description: Successful response with information about allocatable global outbound channels.
    managed-accounts_UnauthorizedResponse:
      description: Unauthenticated response. Happens when the current user cannot be authenticated.
    UnprocessableManagedAccountEntity:
      content:
        application/json:
          schema:
            properties:
              errors:
                items:
                  $ref: '#/components/schemas/UnprocessableEntityError'
                type: array
            type: object
      description: Unprocessable entity. Check the 'detail' field in response for details.
    managed-accounts_ForbiddenResponse:
      description: Unauthorized response. Happens when the current user is not authorized to access the endpoint.
    ManagedAccountResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/ManagedAccount'
            type: object
      description: Successful response with information about a single managed account.
    UpdateManagedAccountGlobalChannelLimitResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/SingleManagedAccountGlobalOutboundChannels'
            type: object
      description: Successful response with information about the allocatable global outbound channels for the given account.
  parameters:
    managed-accounts_FilterConsolidated:
      description: 'Consolidated filter parameter (deepObject style). Originally: filter[email][contains], filter[email][eq], filter[organization_name][contains], filter[organization_name][eq]'
      explode: true
      in: query
      name: filter
      required: false
      schema:
        additionalProperties: false
        example:
          email:
            contains: john
          organization_name:
            eq: Example Company LLC
        properties:
          email:
            additionalProperties: false
            properties:
              contains:
                description: If present, email containing the given value will be returned. Matching is not case-sensitive. Requires at least three characters.
                type: string
              eq:
                description: If present, only returns results with the <code>email</code> matching exactly the value given.
                type: string
            type: object
          organization_name:
            additionalProperties: false
            properties:
              contains:
                description: If present, only returns results with the <code>organization_name</code> containing the given value. Matching is not case-sensitive. Requires at least three characters.
                type: string
              eq:
                description: If present, only returns results with the <code>organization_name</code> matching exactly the value given.
                type: string
            type: object
        type: object
      style: deepObject
    managed-accounts_Sort:
      description: "Specifies the sort order for results. By default sorting direction is ascending. To have the results sorted in descending order add the <code> -</code> prefix.<br/><br/>\nThat is: <ul>\n  <li>\n    <code>email</code>: sorts the result by the\n    <code>email</code> field in ascending order.\n  </li>\n\n  <li>\n    <code>-email</code>: sorts the result by the\n    <code>email</code> field in descending order.\n  </li>\n</ul> <br/> If not given, results are sorted by <code>created_at</code> in descending order."
      in: query
      name: sort
      required: false
      schema:
        default: created_at
        enum:
        - created_at
        - email
        example: email
        type: string
    PageConsolidated:
      description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
      explode: true
      in: query
      name: page
      schema:
        properties:
          number:
            default: 1
            description: The page number to load
            minimum: 1
            type: integer
          size:
            default: 20
            description: The size of the page
            maximum: 250
            minimum: 1
            type: integer
        type: object
      style: deepObject
    IncludeCancelledAccounts:
      description: Specifies if cancelled accounts should be included in the results.
      in: query
      name: include_cancelled_accounts
      required: false
      schema:
        default: false
        example: true
        type: boolean
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    branded-calling_bearerAuth:
      description: API key passed as a Bearer token in the Authorization header
      scheme: bearer
      type: http
    oauthClientAuth:
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
      flows:
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
      type: oauth2
    outbound-voice-profiles_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    pronunciation-dicts_bearerAuth:
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
      scheme: bearer
      type: http
    stored-payment-transactions_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http