Twilio Phone Numbers API

openapi: 3.2.0
info:
  title: Twilio Phone Numbers API
  version: '2.0'
  contact:
    name: Twilio Support
    url: https://support.twilio.com
    email: support@twilio.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://www.twilio.com/legal/tos
  description: 'Operations tagged Phone Numbers across 2 of this provider''s published API definitions: twilio-lookup-openapi.yml, twilio-messaging-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://lookups.twilio.com/v2
  description: Twilio Lookup API v2
- url: https://api.twilio.com/2010-04-01
  description: Twilio REST API v1
- url: https://messaging.twilio.com/v1
  description: Twilio Messaging Service API
security:
- accountSid_authToken: []
tags:
- name: Phone Numbers
  description: Query phone number data and intelligence
paths:
  /PhoneNumbers/{PhoneNumber}:
    get:
      operationId: fetchPhoneNumber
      summary: Twilio Look up a Phone Number
      description: Query information about a phone number. Specify which data packages to include using the Fields parameter. Available packages include validation, line type intelligence, caller name, SIM swap, identity match, SMS pumping risk, and more.
      tags:
      - Phone Numbers
      parameters:
      - name: PhoneNumber
        in: path
        required: true
        description: Phone number to look up in E.164 format
        schema:
          type: string
      - name: Fields
        in: query
        required: false
        description: Comma-separated list of data packages to return. Available fields include validation, line_type_intelligence, caller_name, sim_swap, identity_match, sms_pumping_risk, phone_number_quality_score, reassigned_number, line_status
        schema:
          type: string
        examples:
          validation:
            value: validation
          multiple:
            value: line_type_intelligence,caller_name,sim_swap
      - name: CountryCode
        in: query
        description: ISO 3166-1 alpha-2 country code for national format numbers
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: FirstName
        in: query
        description: First name for identity match
        schema:
          type: string
      - name: LastName
        in: query
        description: Last name for identity match
        schema:
          type: string
      - name: AddressLine1
        in: query
        description: Address line 1 for identity match
        schema:
          type: string
      - name: AddressLine2
        in: query
        description: Address line 2 for identity match
        schema:
          type: string
      - name: City
        in: query
        description: City for identity match
        schema:
          type: string
      - name: State
        in: query
        description: State or province for identity match
        schema:
          type: string
      - name: PostalCode
        in: query
        description: Postal code for identity match
        schema:
          type: string
      - name: AddressCountryCode
        in: query
        description: ISO country code for identity match address
        schema:
          type: string
      - name: NationalId
        in: query
        description: National ID for identity match
        schema:
          type: string
      - name: DateOfBirth
        in: query
        description: Date of birth for identity match (YYYYMMDD)
        schema:
          type: string
      responses:
        '200':
          description: Phone number lookup results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberLookup'
        '400':
          description: Invalid phone number format
        '401':
          description: Unauthorized
        '404':
          description: Phone number not found
        '429':
          description: Rate limit exceeded
    servers:
    - url: https://lookups.twilio.com/v2
      description: Twilio Lookup API v2
  /Services/{ServiceSid}/PhoneNumbers:
    get:
      operationId: listPhoneNumbers
      summary: Twilio List Phone Numbers in a Messaging Service
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/ServiceSid'
      responses:
        '200':
          description: List of phone numbers
          content:
            application/json:
              schema:
                type: object
                properties:
                  phone_numbers:
                    type: array
                    items:
                      $ref: '#/components/schemas/PhoneNumberResource'
    post:
      operationId: addPhoneNumber
      summary: Twilio Add a Phone Number to a Messaging Service
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/ServiceSid'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - PhoneNumberSid
              properties:
                PhoneNumberSid:
                  type: string
                  description: SID of the phone number to add
                  pattern: ^PN[0-9a-fA-F]{32}$
      responses:
        '201':
          description: Phone number added
        '400':
          description: Invalid request
    servers:
    - url: https://api.twilio.com/2010-04-01
      description: Twilio REST API v1
    - url: https://messaging.twilio.com/v1
      description: Twilio Messaging Service API
  /v2/PhoneNumbers/{PhoneNumber}:
    servers:
    - url: https://routes.twilio.com
    description: 'TODO: Resource-level docs'
    x-twilio:
      defaultOutputProperties:
      - sid
      - friendly_name
      - date_created
      pathType: instance
    post:
      description: Assign an Inbound Processing Region to a phone number.
      tags:
      - Phone Numbers
      parameters:
      - name: PhoneNumber
        in: path
        description: The phone number in E.164 format
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/routes.v2.phone_number'
          description: OK
      security:
      - accountSid_authToken: []
      operationId: UpdatePhoneNumber
      x-maturity:
      - GA
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdatePhoneNumberRequest'
      summary: Update phone number
      x-summary-source: derived
    get:
      description: Fetch the Inbound Processing Region assigned to a phone number.
      tags:
      - Phone Numbers
      parameters:
      - name: PhoneNumber
        in: path
        description: The phone number in E.164 format
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/routes.v2.phone_number'
          description: OK
      security:
      - accountSid_authToken: []
      operationId: FetchPhoneNumber
      x-maturity:
      - GA
      summary: Fetch phone number
      x-summary-source: derived
components:
  schemas:
    PhoneNumberLookup:
      type: object
      properties:
        phone_number:
          type: string
          description: Phone number in E.164 format
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code
        national_format:
          type: string
          description: Phone number in national format
        calling_country_code:
          type: string
          description: International dialing country code
        valid:
          type: boolean
          description: Whether the phone number is valid
        validation_errors:
          type: array
          items:
            type: string
            enum:
            - TOO_SHORT
            - TOO_LONG
            - INVALID_BUT_POSSIBLE
            - INVALID_COUNTRY_CODE
            - INVALID_LENGTH
            - NOT_A_NUMBER
          description: Validation error codes if the number is invalid
        caller_name:
          type: object
          description: Caller name (CNAM) information
          properties:
            caller_name:
              type: string
              description: Registered caller name
            caller_type:
              type: string
              enum:
              - CONSUMER
              - BUSINESS
              description: Type of caller
            error_code:
              type: integer
        line_type_intelligence:
          type: object
          description: Line type and carrier information
          properties:
            type:
              type: string
              enum:
              - landline
              - mobile
              - fixedVoip
              - nonFixedVoip
              - personal
              - tollFree
              - premium
              - sharedCost
              - uan
              - voicemail
              - pager
              - unknown
              description: Type of phone line
            carrier_name:
              type: string
              description: Name of the carrier
            mobile_country_code:
              type: string
              description: Mobile country code (MCC)
            mobile_network_code:
              type: string
              description: Mobile network code (MNC)
            error_code:
              type: integer
        sim_swap:
          type: object
          description: SIM swap detection results
          properties:
            last_sim_swap:
              type: object
              properties:
                last_sim_swap_date:
                  type: string
                  format: date-time
                  description: Date of the last SIM swap
                swapped_period:
                  type: string
                  description: Time period classification of the swap
                swapped_in_period:
                  type: boolean
                  description: Whether a swap occurred in the check period
            carrier_name:
              type: string
            mobile_country_code:
              type: string
            mobile_network_code:
              type: string
            error_code:
              type: integer
        identity_match:
          type: object
          description: Identity match verification results
          properties:
            first_name_match:
              type: string
              enum:
              - exact_match
              - high_partial_match
              - partial_match
              - no_match
              - no_data_available
              description: How well the first name matches
            last_name_match:
              type: string
              enum:
              - exact_match
              - high_partial_match
              - partial_match
              - no_match
              - no_data_available
            address_lines_match:
              type: string
              enum:
              - exact_match
              - high_partial_match
              - partial_match
              - no_match
              - no_data_available
            city_match:
              type: string
            state_match:
              type: string
            postal_code_match:
              type: string
            country_code_match:
              type: string
            national_id_match:
              type: string
            date_of_birth_match:
              type: string
            summary_score:
              type: integer
              description: Overall identity match score (0-100)
            error_code:
              type: integer
        sms_pumping_risk:
          type: object
          description: SMS pumping fraud risk assessment
          properties:
            carrier_risk_category:
              type: string
              enum:
              - low
              - medium
              - high
              description: Risk category based on carrier
            carrier_risk_score:
              type: integer
              description: Numeric risk score (0-100)
            number_blocked:
              type: boolean
              description: Whether the number is blocked
            number_blocked_date:
              type: string
              format: date-time
            sms_pumping_risk_score:
              type: integer
              description: Overall SMS pumping risk score (0-100)
            error_code:
              type: integer
        phone_number_quality_score:
          type: object
          description: Phone number quality assessment
          properties:
            quality_score:
              type: integer
              description: Quality score (0-100)
            error_code:
              type: integer
        reassigned_number:
          type: object
          description: Number reassignment detection
          properties:
            last_verified_date:
              type: string
              format: date
            is_reassigned:
              type: string
              enum:
              - 'yes'
              - 'no'
              - cannot_determine
              - no_data_available
            error_code:
              type: integer
        line_status:
          type: object
          description: Current line status
          properties:
            status:
              type: string
              enum:
              - active
              - inactive
              - no_data_available
            error_code:
              type: integer
        url:
          type: string
          format: uri
          description: URL of this resource
    PhoneNumberResource:
      type: object
      properties:
        sid:
          type: string
          pattern: ^PN[0-9a-fA-F]{32}$
        phone_number:
          type: string
          description: Phone number in E.164 format
        country_code:
          type: string
        capabilities:
          type: array
          items:
            type: string
        date_created:
          type: string
          format: date-time
    routes.v2.phone_number:
      type: object
      properties:
        phone_number:
          type:
          - string
          - 'null'
          description: The phone number in E.164 format
        url:
          type:
          - string
          - 'null'
          format: uri
          description: The absolute URL of the resource.
        sid:
          type:
          - string
          - 'null'
          minLength: 34
          maxLength: 34
          pattern: ^QQ[0-9a-fA-F]{32}$
          description: A 34 character string that uniquely identifies the Inbound Processing Region assignments for this phone number.
        account_sid:
          type:
          - string
          - 'null'
          minLength: 34
          maxLength: 34
          pattern: ^AC[0-9a-fA-F]{32}$
          description: The unique SID identifier of the Account.
        friendly_name:
          type:
          - string
          - 'null'
          description: A human readable description of the Inbound Processing Region assignments for this phone number, up to 64 characters.
        voice_region:
          type:
          - string
          - 'null'
          description: The Inbound Processing Region used for this phone number for voice.
        date_created:
          type:
          - string
          - 'null'
          format: date-time
          description: The date that this phone number was assigned an Inbound Processing Region, given in ISO 8601 format.
        date_updated:
          type:
          - string
          - 'null'
          format: date-time
          description: The date that the Inbound Processing Region was updated for this phone number, given in ISO 8601 format.
    UpdatePhoneNumberRequest:
      type: object
      properties:
        VoiceRegion:
          type: string
          description: The Inbound Processing Region used for this phone number for voice
        FriendlyName:
          type: string
          description: A human readable description of this resource, up to 64 characters.
  parameters:
    ServiceSid:
      name: ServiceSid
      in: path
      required: true
      description: The unique identifier of the messaging service
      schema:
        type: string
        pattern: ^MG[0-9a-fA-F]{32}$
  securitySchemes:
    accountSid_authToken:
      type: http
      scheme: basic
      description: Use your Twilio Account SID as the username and Auth Token as the password for HTTP Basic authentication.
x-refined-from:
- twilio-lookup-openapi.yml
- twilio-messaging-openapi.yml
x-maturity:
- name: GA
  description: This product is Generally Available.
- name: Beta
  description: PLEASE NOTE that this is a Beta product that is subject to change. Use it with caution.