Telnyx Reputation Phone Numbers API

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 Reputation Phone Numbers 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: Associate phone numbers with an enterprise for reputation monitoring and retrieve reputation scores
  name: Reputation Phone Numbers
paths:
  /enterprises/{enterprise_id}/reputation/numbers:
    get:
      description: 'List all phone numbers associated with an enterprise for Number Reputation monitoring.


        Returns phone numbers with their cached reputation data (if available). Supports pagination and filtering by phone number.'
      operationId: ListReputationNumbers
      parameters:
      - $ref: '#/components/parameters/EnterpriseId'
      - description: Page number (1-indexed)
        in: query
        name: page[number]
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: Number of items per page
        in: query
        name: page[size]
        schema:
          default: 10
          maximum: 100
          minimum: 1
          type: integer
      - description: Filter by specific phone number (E.164 format)
        in: query
        name: phone_number
        schema:
          example: '+16035551234'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReputationPhoneNumberListWithReputation'
          description: List of phone numbers with reputation data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: List reputation phone numbers
      tags:
      - Reputation Phone Numbers
      x-latency-category: responsive
    post:
      description: 'Associate one or more phone numbers with an enterprise for Number Reputation monitoring.


        **Validations:**

        - Phone numbers must be in E.164 format (e.g., `+16035551234`)

        - Phone numbers must be in-service and belong to your account (verified via Warehouse)

        - Phone numbers must be US local numbers

        - Phone numbers cannot already be associated with any enterprise


        **Note:** This operation is atomic — if any number fails validation, the entire request fails.


        **Maximum:** 100 phone numbers per request.'
      operationId: AssociateReputationNumbers
      parameters:
      - $ref: '#/components/parameters/EnterpriseId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReputationPhoneNumberCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReputationPhoneNumberList'
          description: Phone numbers associated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Associate phone numbers for reputation
      tags:
      - Reputation Phone Numbers
      x-latency-category: responsive
  /enterprises/{enterprise_id}/reputation/numbers/{phone_number}:
    delete:
      description: 'Remove a phone number from Number Reputation monitoring for an enterprise.


        The number will no longer be tracked and reputation data will no longer be refreshed.'
      operationId: DisassociateReputationNumber
      parameters:
      - $ref: '#/components/parameters/EnterpriseId'
      - $ref: '#/components/parameters/PhoneNumber'
      responses:
        '204':
          description: Phone number disassociated successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Disassociate a phone number
      tags:
      - Reputation Phone Numbers
      x-latency-category: responsive
    get:
      description: 'Get detailed reputation data for a specific phone number associated with an enterprise.


        **Query Parameters:**

        - `fresh` (default: `false`): When `true`, fetches fresh reputation data (incurs API cost). When `false`, returns cached data. If no cached data exists, fresh data is automatically fetched.


        **Returns:**

        - `spam_risk`: Overall spam risk level (`low`, `medium`, `high`)

        - `spam_category`: Spam category classification

        - `maturity_score`: Maturity metric (0–100)

        - `connection_score`: Connection quality metric (0–100)

        - `engagement_score`: Engagement metric (0–100)

        - `sentiment_score`: Sentiment metric (0–100)

        - `last_refreshed_at`: Timestamp of last data refresh'
      operationId: GetPhoneNumberReputation
      parameters:
      - $ref: '#/components/parameters/EnterpriseId'
      - $ref: '#/components/parameters/PhoneNumber'
      - description: When true, fetches fresh reputation data (incurs API cost). When false, returns cached data.
        in: query
        name: fresh
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReputationPhoneNumberWithReputation'
          description: Phone number reputation data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branded-calling_ErrorResponse'
          description: Enterprise is not approved for reputation tracking
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branded-calling_ErrorResponse'
          description: Phone number is not associated with this enterprise
      summary: Get reputation data for a phone number
      tags:
      - Reputation Phone Numbers
      x-latency-category: responsive
  /reputation/numbers:
    get:
      description: 'List all phone numbers enrolled in Number Reputation monitoring for your account. This is a simplified endpoint that does not require an `enterprise_id` — it returns numbers across all your enterprises.


        Supports pagination and filtering by phone number.'
      operationId: ListReputationNumbersSimplified
      parameters:
      - description: Page number (1-indexed)
        in: query
        name: page[number]
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: Number of items per page
        in: query
        name: page[size]
        schema:
          default: 10
          maximum: 100
          minimum: 1
          type: integer
      - description: Filter by specific phone number (E.164 format)
        in: query
        name: phone_number
        schema:
          example: '+16035551234'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReputationPhoneNumberListWithReputation'
          description: List of phone numbers with reputation data
        '401':
          $ref: '#/components/responses/Unauthorized'
      summary: List reputation phone numbers (simplified)
      tags:
      - Reputation Phone Numbers
      x-latency-category: responsive
  /reputation/numbers/{phone_number}:
    delete:
      description: Remove a phone number from Number Reputation monitoring without requiring an `enterprise_id`.
      operationId: DisassociateReputationNumberSimplified
      parameters:
      - $ref: '#/components/parameters/PhoneNumber'
      responses:
        '204':
          description: Phone number disassociated successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Disassociate a phone number (simplified)
      tags:
      - Reputation Phone Numbers
      x-latency-category: responsive
    get:
      description: 'Get reputation data for a specific phone number without requiring an `enterprise_id`.


        Same response as the enterprise-scoped endpoint. Uses cached data by default.'
      operationId: GetPhoneNumberReputationSimplified
      parameters:
      - $ref: '#/components/parameters/PhoneNumber'
      - description: When true, fetches fresh reputation data (incurs API cost). When false, returns cached data.
        in: query
        name: fresh
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReputationPhoneNumberWithReputation'
          description: Phone number reputation data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Get reputation data for a phone number (simplified)
      tags:
      - Reputation Phone Numbers
      x-latency-category: responsive
components:
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/branded-calling_ErrorResponse'
      description: Bad request — invalid input or validation error
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/branded-calling_ErrorResponse'
      description: Unauthorized — missing or invalid API key
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/branded-calling_ErrorResponse'
      description: Resource not found
  parameters:
    EnterpriseId:
      description: Unique identifier of the enterprise (UUID)
      in: path
      name: enterprise_id
      required: true
      schema:
        example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
        format: uuid
        type: string
    PhoneNumber:
      description: Phone number in E.164 format
      in: path
      name: phone_number
      required: true
      schema:
        example: '+16035551234'
        type: string
  schemas:
    ReputationPhoneNumberWithReputation:
      properties:
        data:
          $ref: '#/components/schemas/ReputationPhoneNumberWithReputationData'
      type: object
    MetaInfo:
      properties:
        page_number:
          description: Current page number
          type: integer
        page_size:
          description: Items per page
          type: integer
        total_pages:
          description: Total number of pages
          type: integer
        total_results:
          description: Total number of results
          type: integer
      type: object
    branded-calling_ErrorResponse:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/TelnyxError'
          type: array
      type: object
    ReputationPhoneNumberListWithReputation:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ReputationPhoneNumberWithReputationData'
          type: array
        meta:
          $ref: '#/components/schemas/MetaInfo'
      type: object
    ReputationPhoneNumberList:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ReputationPhoneNumberPublic'
          type: array
        meta:
          $ref: '#/components/schemas/MetaInfo'
      type: object
    ReputationPhoneNumberCreate:
      properties:
        phone_numbers:
          description: List of phone numbers to associate for reputation monitoring (max 100)
          items:
            description: Phone number in E.164 format
            example: '+16035551234'
            type: string
          maxItems: 100
          minItems: 1
          type: array
      required:
      - phone_numbers
      type: object
    ReputationPhoneNumberPublic:
      properties:
        created_at:
          description: When the number was associated
          format: date-time
          type: string
        enterprise_id:
          description: ID of the associated enterprise
          format: uuid
          type: string
        id:
          description: Unique identifier
          format: uuid
          type: string
        phone_number:
          description: Phone number in E.164 format
          example: '+16035551234'
          type: string
        updated_at:
          description: When the record was last updated
          format: date-time
          type: string
      type: object
    TelnyxError:
      properties:
        code:
          description: Telnyx error code
          example: '10015'
          type: string
        detail:
          description: Human-readable error detail
          example: User has already agreed to Terms of Service version v1.0.0
          type: string
        meta:
          properties:
            url:
              description: Link to error documentation
              format: uri
              type: string
          type: object
        source:
          description: Reference to the field that caused the error
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the field that caused the error
              example: /body/organization_type
              type: string
          type: object
        title:
          description: Short error title
          example: Bad Request
          type: string
      required:
      - code
      - title
      type: object
    ReputationPhoneNumberWithReputationData:
      allOf:
      - $ref: '#/components/schemas/ReputationPhoneNumberPublic'
      - properties:
          reputation_data:
            description: Reputation metrics (null if not yet fetched)
            oneOf:
            - $ref: '#/components/schemas/ReputationData'
            - nullable: true
              type: object
        type: object
    ReputationData:
      description: Reputation metrics
      properties:
        connection_score:
          description: Connection quality metric (0–100)
          maximum: 100
          minimum: 0
          nullable: true
          type: integer
        engagement_score:
          description: Engagement metric (0–100). Higher = more positive engagement
          maximum: 100
          minimum: 0
          nullable: true
          type: integer
        last_refreshed_at:
          description: Timestamp of the last reputation data refresh
          format: date-time
          nullable: true
          type: string
        maturity_score:
          description: Maturity metric (0–100). Higher = more established number
          maximum: 100
          minimum: 0
          nullable: true
          type: integer
        sentiment_score:
          description: Sentiment metric (0–100). Higher = more positive sentiment
          maximum: 100
          minimum: 0
          nullable: true
          type: integer
        spam_category:
          description: Spam category classification (e.g., Telemarketing, Debt Collector)
          nullable: true
          type: string
        spam_risk:
          description: Overall spam risk level
          enum:
          - low
          - medium
          - high
          nullable: true
          type: string
      type: object
  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