openapi: 3.1.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 Access Tokens Organization Users 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: Operations related to users in your organization
  name: Organization Users
paths:
  /organizations/users:
    get:
      description: Returns a list of the users in your organization.
      operationId: ListOrganizationUsers
      parameters:
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/users_PageSize'
      - $ref: '#/components/parameters/FilterOrganizationUserStatus'
      - $ref: '#/components/parameters/FilterOrganizationUserEmail'
      - $ref: '#/components/parameters/IncludeGroups'
      responses:
        '200':
          $ref: '#/components/responses/ListOrganizationUsersResponse'
        '400':
          $ref: '#/components/responses/users_BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthenticatedResponse'
        '403':
          $ref: '#/components/responses/users_UnauthorizedResponse'
      summary: List organization users
      tags:
      - Organization Users
      x-endpoint-cost: medium
      x-group-parameters: 'true'
      x-latency-category: interactive
  /organizations/users/users_groups_report:
    get:
      description: Returns a report of all users in your organization with their group memberships. This endpoint returns all users without pagination and always includes group information. The report can be retrieved in JSON or CSV format by sending specific content-type headers.
      operationId: GetOrganizationUsersGroupsReport
      parameters:
      - description: Specify the response format. Use 'application/json' for JSON format or 'text/csv' for CSV format.
        in: header
        name: Accept
        required: false
        schema:
          default: application/json
          enum:
          - application/json
          - text/csv
          type: string
      responses:
        '200':
          $ref: '#/components/responses/UsersGroupsReportResponse'
        '401':
          $ref: '#/components/responses/UnauthenticatedResponse'
        '403':
          $ref: '#/components/responses/users_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/users_NotFoundResponse'
      summary: Get organization users groups report
      tags:
      - Organization Users
      x-endpoint-cost: medium
      x-group-parameters: 'true'
      x-latency-category: interactive
  /organizations/users/{id}:
    get:
      description: Returns a user in your organization.
      operationId: GetOrganizationUser
      parameters:
      - description: Organization User ID
        in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/IncludeGroups'
      responses:
        '200':
          $ref: '#/components/responses/OrganizationUserResponse'
        '400':
          $ref: '#/components/responses/users_BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthenticatedResponse'
        '403':
          $ref: '#/components/responses/users_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/users_NotFoundResponse'
      summary: Get organization user
      tags:
      - Organization Users
      x-endpoint-cost: medium
      x-group-parameters: 'true'
      x-latency-category: interactive
  /organizations/users/{id}/actions/remove:
    post:
      description: Deletes a user in your organization.
      operationId: DeleteOrganizationUser
      parameters:
      - description: Organization User ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/OrganizationUserResponse'
        '400':
          $ref: '#/components/responses/users_BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthenticatedResponse'
        '403':
          $ref: '#/components/responses/users_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/users_NotFoundResponse'
      summary: Delete organization user
      tags:
      - Organization Users
      x-endpoint-cost: medium
      x-group-parameters: 'true'
      x-latency-category: interactive
components:
  schemas:
    users_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
      title: Pagination Meta
      type: object
    OrganizationUser:
      example:
        created_at: '2018-02-02T22:25:27.521Z'
        email: user@example.com
        id: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
        last_sign_in_at: '2018-02-02T22:25:27.521Z'
        organization_user_bypasses_sso: false
        record_type: organization_sub_user
        user_status: enabled
      properties:
        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 email address of the user.
          example: user@example.com
          format: email
          type: string
        groups:
          description: The groups the user belongs to. Only included when include_groups parameter is true.
          items:
            $ref: '#/components/schemas/UserGroupReference'
          type: array
        id:
          description: Identifies the specific resource.
          example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
          type: string
        last_sign_in_at:
          description: ISO 8601 formatted date indicating when the resource last signed into the portal. Null if the user has never signed in.
          example: '2018-02-02T22:25:27.521Z'
          type:
          - string
          - 'null'
        organization_user_bypasses_sso:
          description: Indicates whether this user is allowed to bypass SSO and use password authentication.
          example: false
          type: boolean
        record_type:
          description: Identifies the type of the resource. Can be 'organization_owner' or 'organization_sub_user'.
          example: organization_sub_user
          type: string
        user_status:
          default: enabled
          description: The status of the account.
          enum:
          - enabled
          - disabled
          - blocked
          example: enabled
          type: string
      title: OrganizationUser
      type: object
    ErrorResponse:
      properties:
        errors:
          items:
            properties:
              code:
                type: string
              detail:
                type: string
              meta:
                properties:
                  url:
                    format: uri
                    type: string
                type: object
              source:
                properties:
                  pointer:
                    type: string
                type: object
              title:
                type: string
            type: object
          type: array
      type: object
    OrganizationUserWithGroups:
      description: An organization user with their group memberships always included.
      example:
        created_at: '2018-02-02T22:25:27.521Z'
        email: user@example.com
        groups:
        - id: 7b09cdc3-8948-47f0-aa62-74ac943d6c59
          name: Engineering
        id: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
        last_sign_in_at: '2018-02-02T22:25:27.521Z'
        organization_user_bypasses_sso: false
        record_type: organization_sub_user
        user_status: enabled
      properties:
        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 email address of the user.
          example: user@example.com
          format: email
          type: string
        groups:
          description: The groups the user belongs to.
          items:
            $ref: '#/components/schemas/UserGroupReference'
          type: array
        id:
          description: Identifies the specific resource.
          example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
          type: string
        last_sign_in_at:
          description: ISO 8601 formatted date indicating when the resource last signed into the portal. Null if the user has never signed in.
          example: '2018-02-02T22:25:27.521Z'
          type:
          - string
          - 'null'
        organization_user_bypasses_sso:
          description: Indicates whether this user is allowed to bypass SSO and use password authentication.
          example: false
          type: boolean
        record_type:
          description: Identifies the type of the resource. Can be 'organization_owner' or 'organization_sub_user'.
          example: organization_sub_user
          type: string
        user_status:
          default: enabled
          description: The status of the account.
          enum:
          - enabled
          - disabled
          - blocked
          example: enabled
          type: string
      required:
      - id
      - record_type
      - email
      - user_status
      - created_at
      - groups
      title: OrganizationUserWithGroups
      type: object
    UserGroupReference:
      description: A reference to a group that a user belongs to.
      example:
        id: 7b09cdc3-8948-47f0-aa62-74ac943d6c59
        name: Engineering
      properties:
        id:
          description: The unique identifier of the group.
          example: 7b09cdc3-8948-47f0-aa62-74ac943d6c59
          type: string
        name:
          description: The name of the group.
          example: Engineering
          type: string
      required:
      - id
      - name
      title: UserGroupReference
      type: object
  responses:
    UsersGroupsReportResponse:
      content:
        application/json:
          example:
            data:
            - created_at: '2018-02-02T22:25:27.521Z'
              email: user@example.com
              groups:
              - id: 7b09cdc3-8948-47f0-aa62-74ac943d6c59
                name: Engineering
              - id: 8c09cdc3-8948-47f0-aa62-74ac943d6c60
                name: Sales
              id: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
              last_sign_in_at: '2018-02-02T22:25:27.521Z'
              organization_user_bypasses_sso: false
              record_type: organization_sub_user
              user_status: enabled
            - created_at: '2018-01-01T00:00:00.000Z'
              email: owner@example.com
              groups: []
              id: 9d09cdc3-8948-47f0-aa62-74ac943d6c61
              last_sign_in_at: '2018-02-02T22:25:27.521Z'
              organization_user_bypasses_sso: false
              record_type: organization_owner
              user_status: enabled
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/OrganizationUserWithGroups'
                type: array
            title: Users Groups Report Response
            type: object
        text/csv:
          example: 'id,email,user_status,created_at,last_sign_in_at,groups

            6a09cdc3-8948-47f0-aa62-74ac943d6c58,user@example.com,enabled,2018-02-02T22:25:27.521Z,2018-02-02T22:25:27.521Z,"Engineering, Sales"'
          schema:
            description: 'CSV formatted report of users and their groups. Columns: id, email, user_status, created_at, last_sign_in_at, groups (comma-separated list of group names).'
            type: string
      description: Successful response with a list of organization users and their group memberships.
    users_BadRequestResponse:
      content:
        application/json:
          examples:
            missingParameter:
              value:
                errors:
                - code: '10015'
                  detail: The request failed because it was not well-formed.
                  meta:
                    url: https://developers.telnyx.com/docs/overview/errors/10015
                  source:
                    pointer: /
                  title: Bad Request
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Bad request, the request was unacceptable, often due to missing a required parameter.
    users_UnauthorizedResponse:
      content:
        application/json:
          examples:
            notAuthorized:
              value:
                errors:
                - code: '10010'
                  detail: You are not authorized to access the requested resource.
                  meta:
                    url: https://developers.telnyx.com/docs/overview/errors/10010
                  source:
                    pointer: /
                  title: Not authorized
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: The user doesn't have the required permissions to perform the requested action.
    UnauthenticatedResponse:
      content:
        application/json:
          examples:
            Authentication Failed:
              value:
                errors:
                - code: '10009'
                  detail: Could not understand the provided credentials.
                  meta:
                    url: https://developers.telnyx.com/docs/overview/errors/10009
                  title: Authentication failed
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Unauthorized
    users_NotFoundResponse:
      content:
        application/json:
          examples:
            notFound:
              value:
                errors:
                - code: '10005'
                  detail: The requested resource or URL could not be found.
                  meta:
                    url: https://developers.telnyx.com/docs/overview/errors/10005
                  source:
                    pointer: /
                  title: Resource not found
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: The requested resource doesn't exist.
    ListOrganizationUsersResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/OrganizationUser'
                type: array
              meta:
                $ref: '#/components/schemas/users_PaginationMeta'
            title: List Organization Users Response
            type: object
      description: Successful response with a list of organization users.
    OrganizationUserResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/OrganizationUser'
            title: Organization User Response
            type: object
      description: Successful response with details about an Organization User.
  parameters:
    PageNumber:
      description: The page number to load
      in: query
      name: page[number]
      schema:
        default: 1
        minimum: 1
        type: integer
    FilterOrganizationUserStatus:
      description: Filter by user status
      in: query
      name: filter[user_status]
      schema:
        enum:
        - enabled
        - disabled
        - blocked
        type: string
    users_PageSize:
      description: The size of the page
      in: query
      name: page[size]
      schema:
        default: 250
        maximum: 250
        minimum: 1
        type: integer
    FilterOrganizationUserEmail:
      description: Filter by email address (partial match)
      in: query
      name: filter[email]
      schema:
        type: string
    IncludeGroups:
      description: When set to true, includes the groups array for each user in the response. The groups array contains objects with id and name for each group the user belongs to.
      in: query
      name: include_groups
      schema:
        default: false
        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