openapi: 3.2.0
info:
  version: 1.0.0
  title: Legacy Phone ID Phone ID Contact API
  description: This spec contains details about the deprecated Telesign Phone ID API. This API is no longer fully supported, but has not reached end of life.
  contact:
    name: Telesign Customer Support Team
    email: support@telesign.com
servers:
- url: https://rest-ww.telesign.com/v1
security:
- Basic: []
tags:
- name: Phone ID Contact
paths:
  /phoneid/contact/{complete_phone_number}:
    parameters:
    - name: complete_phone_number
      in: path
      required: true
      schema:
        type: string
    get:
      description: 'Enter a phone number to receive detailed contact information related to the subscriber''s phone number to provide another set of indicators for established risk engines. NOTE: If you try this API out using the API Explorer, you will be billed for the transaction as you normally would.


        ## General requirements

        * **Authentication:** Basic (easiest to implement) or Digest

        * **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.

        * **Accepts:** `application/x-www-form-urlencoded`

        * **Responds with:** `application/json`

        * **Required headers:** `Content-Type - application/x-www-form-urlencoded`'
      parameters:
      - in: path
        name: complete_phone_number
        required: true
        description: 'The phone number you want to collect information about. Provide the entire phone number, including the country code, with no spaces or special characters.

          '
        schema:
          type: string
      - in: query
        name: ucid
        description: 'One of the use case codes. | Use Case | Description ||----------|-------------|| ATCK | For use in a 2FA situation like updating an account, or trying to log in. || BACF | For creating an account on somebody''s service in a situation where the service may be vulnerable to bulk attacks or individual fraudsters. || BACS | For creating an account on somebody''s service in a situation where the service may be vulnerable to bulk attacks or individual spammers. || CHBK | For use in a situation such as someone trying to buy something expensive or unusual on your platform, and you want to verify that it is really them. || CLDR | Calendar Event | | LEAD | For use in a situation where you require a person to enter their personal information in order to obtain information about something like a loan or realty or a school, and you want to check if the person is bogus or not. || OTHR | Other - if you have a situation not addressed by the other tags. || PWRT | For use in a situation where a password reset is required. || RESV | For use in a situation where you have end users making reservations and not showing up, and you want to be able to include some kind of phone verification in that loop. || RXPF | For use in situations where you are trying to prevent prescription fraud. || SHIP | For use in situations where you are sending a shipping notification. | | THEF | For use in situations where you are trying to prevent an end user from deactivating or redirecting a phone number in order to take over someone else''s identity. || TRVF | For use in situations where you are transferring money, and you want to check to see if it is approved by sending a text message or phone call to your end user. This is similar to CHBK, but is specifically for a money transaction. | | UNKN | This is the same as OTHR. | '
        schema:
          type: string
      responses:
        '200':
          description: "Your request was fulfilled and resulted in a new resource being created. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response. \n           \n| Status code | Associated text string | Description                                      |\n|-------------|------------------------|--------------------------------------------------|\n| 300         | Transaction successfully completed            | The system was able to obtain all of the requested data for Phone ID.                      |\n| 301         | Transaction partially completed | The system was able to obtain some of the data for Phone ID, but not all of it.                  |\n\n| Error | Description |\n|-------|-------------|\n| -60001 | Phone ID Contact data not found |\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPhoneIdResponse'
        '400':
          description: "Bad request, the request could not be understood by the server due to malformed syntax. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response. Error codes are listed in the `error` parameter in the response. \n\n| Error Code | Description |\n|------------|-------------|\n| -10001 | Not Allowed Host (indicates that the IP address you are connecting from is not authorized to access the service) -or- Unsupported product name | \n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPhoneIdResponse'
        '401':
          description: "Unauthorized, the request requires user authentication. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response. Error codes are listed in the `error` parameter in the response. \n\n  | Error Codes | Description |\n  |-------------|-------------|   \n  | -10009 | Invalid source IP address |\n  | -20002 | This product is not enabled for this customer ID |\n  | -20003 | This feature is not enabled for this CustomerID  |\n  | -30002 | CustomerID Account Not Activated | \n  | -30003 | CustomerID New Account Limit Reached |\n  | -40002 | Not Authorized | \n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPhoneIdResponse'
        '402':
          description: "Payment Required. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response. Error codes are listed in the `error` parameter in the response. \n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPhoneIdResponse'
        '404':
          description: "Not Found, the server has not found anything matching the Request-URI. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response. Error codes are listed in the `error` parameter in the response. \n\n  | Error Codes | Description |\n  |-------------|-------------|\n  | -40001 | Status unavailable |\n  | -40004 | Resource not found | \n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPhoneIdResponse'
        '405':
          description: '| Error Codes | Description |

            |-------------|-------------|

            | -40005 | Method not allowed |

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPhoneIdResponse'
        '429':
          description: "Too Many Requests, the user sent too many requests in a given amount of time. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response. Error codes are listed in the `error` parameter in the response. \n\n| Error Code | Description |\n|------------|-------------|\n| 500 | Transaction not attempted. | \n| -40007 | Rate limit exceeded | \n| -40008 | [Product method] exceed transaction hard cap; Request denied |\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPhoneIdResponse'
        '500':
          description: "Invalid Transaction, transaction not attempted. Error codes are listed in the `error` parameter in the response. \n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPhoneIdResponse'
        '503':
          description: "Service Unavailable, system unavailable, try again. Error codes are listed in the `error` parameter in the response. \n\n| Error Code | Description |\n|------------|-------------|\n| -90001 | System unavailable; please try again later |\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPhoneIdResponse'
      deprecated: true
      tags:
      - Phone ID Contact
      summary: Get contact details
      operationId: getContactDetailsForPhoneNumber
components:
  schemas:
    Numbering:
      title: Numbering
      type: object
      description: Contains properties related to the numbering attributes of the specified phone number.
      properties:
        original:
          type: object
          description: Contains details about the original phone number included in the request.
          properties:
            phone_number:
              type: string
              description: The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
              example: '7833012348'
            complete_phone_number:
              type: string
              description: The base phone number prefixed with the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
              example: '17833012348'
            country_code:
              type: string
              description: The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for the United Kingdom is `44`.
              example: '1'
        cleansing:
          type: object
          description: Contains details about how the phone number was cleansed. Phone cleansing corrects common formatting issues in submitted phone numbers.
          properties:
            call:
              type: object
              description: Contains cleansing details for the phone number if it is enabled to receive voice calls.
              properties:
                cleansed_code:
                  type: integer
                  description: One of the [phone number cleansing codes](/enterprise/docs/codes-languages-and-time-zones#phone-number-cleansing-codes) specifying the cleansing operation performed on the phone number.
                  example: 100
                country_code:
                  type: string
                  description: The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`.
                  example: '1'
                max_length:
                  type: integer
                  description: The maximum number of digits allowed for phone numbers with this country dialing code.
                  example: 10
                min_length:
                  type: integer
                  description: The minimum number of digits allowed for phone numbers with this country dialing code.
                  example: 10
                phone_number:
                  type: string
                  description: The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
                  example: '7833012348'
            sms:
              type: object
              description: Contains cleansing details for the phone number if it is enabled to receive SMS.
              properties:
                cleansed_code:
                  type: integer
                  description: One of the [phone number cleansing codes](/enterprise/docs/codes-languages-and-time-zones#phone-number-cleansing-codes) specifying the cleansing operation performed on the phone number.
                  example: 100
                country_code:
                  type: string
                  description: The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`.
                  example: '1'
                max_length:
                  type: integer
                  description: The maximum number of digits allowed for phone numbers with this country dialing code.
                  example: 10
                min_length:
                  type: integer
                  description: The minimum number of digits allowed for phone numbers with this country dialing code.
                  example: 10
                phone_number:
                  type: string
                  description: The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
                  example: '7833012348'
    getPhoneIdResponse:
      type: object
      description: ''
      properties:
        reference_id:
          type: string
          description: A unique, randomly generated hex value that identifies your web service request.
        sub_resource:
          type: string
          description: The subresource accessed by your request. It is set to `contact`.
          example: contact
          enum:
          - contact
        errors:
          type: array
          description: Contains an object for each error that resulted from the request.
          items:
            type: object
            description: Contains properties describing this error.
            properties:
              code:
                type: integer
                description: A numeric code indicating the processing status for this transaction.
              description:
                type: string
                description: Text describing the type of error that occurred.
        phone_type:
          type: object
          description: 'Contains details about the phone type. '
          properties:
            code:
              type: string
              description: One of the [phone type codes](/enterprise/docs/codes-languages-and-time-zones#phone-type-codes).
            description:
              type: string
              description: 'Text describing the phone type. '
        status:
          type: object
          description: Contains details about the status of your request.
          properties:
            code:
              type: string
              description: A numeric code indicating the processing status of the transaction.
            description:
              type: string
              description: Text describing the transaction status.
            updated_on:
              type: string
              description: 'An <a href="http://www.ietf.org/rfc/rfc3339.txt">RFC 3339</a> timestamp indicating when the transaction status was updated. '
        numbering:
          $ref: '#/components/schemas/Numbering'
        location:
          type: object
          description: 'Contains geographical location information associated with the phone number. '
          properties:
            city:
              type: string
              description: The city associated with the phone number.
            county:
              type: string
              description: The [county](https://www.census.gov/geo/reference/county-adjacency.html) (or parish) associated with the phone number (U.S. only).
            state:
              type: string
              description: 'The two-letter [state abbreviation code](http://pe.usps.com/text/pub28/28apb.htm) of the state (province, district, or territory) associated with the phone number (North America only).

                '
            zip:
              type: string
              description: The five-digit United States Postal Service [ZIP Code](https://www.usps.com/nationalpremieraccounts/findzipcodes.htm) associated with the phone number (U.S. only).
            country:
              type: object
              description: 'Contains details about the country associated with the phone number. '
              properties:
                iso2:
                  type: string
                  description: 'The ISO 3166-1 two-letter [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes) associated with the phone number. '
                iso3:
                  type: string
                  description: 'The ISO 3166-1 three-letter country code associated with the phone number. '
                name:
                  type: string
                  description: The [country name](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes) associated with the phone number.
            time_zone:
              type: object
              description: 'Contains details about the [time zone](/enterprise/docs/codes-languages-and-time-zones#time-zones) associated with the phone number. For maximum and minimum UTC offsets, they are specified in units of hours, and range from -12 to +14. For positive numbers, the plus sign (+) may not be returned. Additional offsets due to Daylight Savings Time or Summer Time are not considered. For example, Russia, which spans 11 time zones, has a minimum UTC offset of +2, and a maximum of +12. '
              properties:
                name:
                  type: string
                  description: The [time zone](/enterprise/docs/codes-languages-and-time-zones#time-zones) associated with the phone number (U.S. only).
                  example: America/Los_Angeles
                utc_offset_max:
                  type: string
                  description: For international phone numbers, this parameter returns the maximum UTC offset for the country associated with the phone number. For U.S. domestic phone numbers, this parameter returns the same result as utc_offset_min.
                utc_offset_min:
                  type: string
                  description: For U.S. domestic phone numbers, this parameter returns the UTC offset associated with the phone number. For international phone numbers, this parameter returns the minimum UTC offset for the country associated with the phone number.
            coordinates:
              type: object
              description: Contains details about the geographical coordinates of the location where the phone number is registered.
              properties:
                latitude:
                  description: 'Latitude specifies the North-South position of a point on the Earth’s surface. It is an angular measurement that ranges from 0° at the Equator, to 90° at the North Pole (and -90° at the South Pole). It is returned here as a value indicating the number of degrees of latitude of the location associated with the phone number, expressed in seven decimal digits, with five decimal places. '
                  example: '34.18264'
                longitude:
                  description: Longitude specifies the East-West position of a point on the Earth’s surface. It is an angle measured East or West from the <a href="https://en.wikipedia.org/wiki/Prime_meridian>Prime Meridian</a>—ranging from 0° at the Prime Meridian, to +180° Eastward and -180° Westward. It is returned here as a value indicating the number of degrees of longitude of the location associated with the phone number, expressed in eight decimal digits, with five decimal places.
                  example: '-118.30840'
            metro_code:
              type: string
              description: A four-digit code indicating the <a href="http://www.census.gov/population/estimates/metro-city/99mfips.txt">Primary Metropolitan Statistical Area (PMSA)</a> code for the location associated with the phone number (U.S. only). PMSA Codes are governed by the []US Census Bureau](http://www.census.gov/). This information is useful for large metropolitan areas that comprise several smaller cities. For example, the PMSA for Long Beach, California is Los Angeles County, which gives Long Beach the PMSA Code 4480.
        carrier:
          type: object
          description: Contains information about the company that provides telecommunications services for the phone number.
          properties:
            name:
              type: string
              description: The name of the carrier.
              example: Verizon
        contact:
          type: object
          description: Contact information for the end user associated with the phone number.
          properties:
            firstname:
              type: string
              description: The end user's first name or given name. If the result is a business name, the full business name goes in this field. Depending on the data provider, it might not be possible to distinguish business names from personal names.
            lastname:
              type: string
              description: The end user's last name or family name. If they are a business, this value is null.
            address1:
              type: string
              description: The first line of the end user’s street address.
            address2:
              type: string
              description: The second line of the end user’s street address.
            address3:
              type: string
              description: The third line of the end user's street address.
            address4:
              type: string
              description: The fourth line of the end user's street address.
            city:
              type: string
              description: The city in which the end user is located.
            state_province:
              type: string
              description: The state, province, or region in which the end user is located.
            country:
              type: string
              description: The country in which the end user is located.
            zip_postal_code:
              type: string
              description: The United States Postal Service ZIP Code in which the end user is located (US addresses only).
  securitySchemes:
    Basic:
      type: http
      scheme: basic
x-stoplight:
  docs:
    showModels: false
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true