openapi: 3.2.0
info:
  title: Aperture REST Phone Validation API
  version: v2
servers:
- url: https://api.experianaperture.io/
tags:
- name: Phone Validation
paths:
  /phone/validate/v2:
    post:
      tags:
      - Phone Validation
      summary: Submits a phone number to the service to be validated and returns the result of…
      parameters:
      - name: Add-Metadata
        in: header
        description: Specify whether the response should return all fields and values, in addition to the main core information.
        schema:
          type: boolean
      - name: Reference-Id
        in: header
        description: Optional identifier that will be returned in the response to help you track the request.
        schema:
          maxLength: 256
          minLength: 0
          pattern: ^[\w\-\/\:\.\,\(\) ]+$
          type: string
      - name: Timeout-Seconds
        in: header
        description: 'Maximum time you are prepared to wait for a response, expressed in seconds. Acceptable values: 2-15. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned.'
        schema:
          maximum: 15
          minimum: 2
          type: integer
          format: int32
      requestBody:
        description: The request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneValidationV2Request'
            examples:
              Default Behavior, No Optional Fields:
                value:
                  number: '2016477962'
                  output_format: NATIONAL
                  cache_value_days: 0
                  country_iso: USA
                  get_ported_date: false
                  get_disposable_number: true
              PV Request with Optional Fields (ported_date & live_status) — Extra Clicks Apply:
                value:
                  number: '2016477962'
                  output_format: NATIONAL
                  cache_value_days: 0
                  country_iso: USA
                  get_ported_date: true
                  get_disposable_number: true
                  supplementary_live_status:
                    mobile:
                    - USA
                    landline:
                    - GBR
          application/xml:
            schema:
              $ref: '#/components/schemas/PhoneValidationV2Request'
            examples:
              Default Behavior, No Optional Fields:
                value: "<request xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">\n  <number>2016477962</number>\n  <output_format>NATIONAL</output_format>\n  <cache_value_days>0</cache_value_days>\n  <country_iso>USA</country_iso>\n  <get_ported_date>false</get_ported_date>\n  <get_disposable_number>true</get_disposable_number>\n</request>"
              PV Request with Optional Fields (ported_date & live_status) — Extra Clicks Apply:
                value: "<request xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">\n  <number>2016477962</number>\n  <output_format>NATIONAL</output_format>\n  <cache_value_days>0</cache_value_days>\n  <country_iso>USA</country_iso>\n  <get_ported_date>true</get_ported_date>\n  <get_disposable_number>true</get_disposable_number>\n  <supplementary_live_status>\n    <mobile>USA</mobile>\n    <landline>GBR</landline>\n  </supplementary_live_status>\n</request>"
          application/x-msgpack:
            schema:
              $ref: '#/components/schemas/PhoneValidationV2Request'
            examples:
              Default Behavior, No Optional Fields:
                value:
                  number: '2016477962'
                  output_format: NATIONAL
                  cache_value_days: 0
                  country_iso: USA
                  get_ported_date: false
                  get_disposable_number: true
              PV Request with Optional Fields (ported_date & live_status) — Extra Clicks Apply:
                value:
                  number: '2016477962'
                  output_format: NATIONAL
                  cache_value_days: 0
                  country_iso: USA
                  get_ported_date: true
                  get_disposable_number: true
                  supplementary_live_status:
                    mobile:
                    - USA
                    landline:
                    - GBR
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneValidationV2Response'
              examples:
                Default Behavior, No Optional Fields:
                  value:
                    result:
                      number: '17087694383'
                      validated_phone_number: '12016477962'
                      formatted_phone_number: (201) 647-7962
                      phone_type: Mobile
                      confidence: Verified
                      disposable_number: 'Yes'
                    metadata:
                      phone_detail:
                        original_operator_name: T-Mobile
                        original_network_status: Available
                        original_home_network_identity: '310200'
                        original_country_prefix: '1'
                        original_country_name: United States of America
                        original_country_iso: USA
                        operator_name: AT&T
                        network_status: Available
                        home_network_identity: '311480'
                        country_prefix: '1'
                        country_name: United States of America
                        country_iso: USA
                        is_ported: 'Yes'
                        cache_value_days: 0
                        date_cached: '2020-10-07'
                        email_to_sms_address: 2016477962@mms.att.net
                        email_to_mms_address: 2016477962@txt.att.net
                PV Request with Optional Fields (ported_date & live_status) — Extra Clicks Apply:
                  value:
                    result:
                      number: '17087694383'
                      validated_phone_number: '12016477962'
                      formatted_phone_number: (201) 647-7962
                      phone_type: Mobile
                      confidence: Verified
                      ported_date: '2019-08-21T00:00:00Z'
                      disposable_number: 'Yes'
                    metadata:
                      phone_detail:
                        original_operator_name: T-Mobile
                        original_network_status: Available
                        original_home_network_identity: '310200'
                        original_country_prefix: '1'
                        original_country_name: United States of America
                        original_country_iso: USA
                        operator_name: AT&T
                        network_status: Available
                        home_network_identity: '311480'
                        country_prefix: '1'
                        country_name: United States of America
                        country_iso: USA
                        is_ported: 'Yes'
                        cache_value_days: 0
                        date_cached: '2020-10-07'
                        email_to_sms_address: 2016477962@mms.att.net
                        email_to_mms_address: 2016477962@txt.att.net
            application/xml:
              schema:
                $ref: '#/components/schemas/PhoneValidationV2Response'
              examples:
                Default Behavior, No Optional Fields:
                  value: "<response xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">\n  <result>\n    <number>17087694383</number>\n    <validated_phone_number>12016477962</validated_phone_number>\n    <formatted_phone_number>(201) 647-7962</formatted_phone_number>\n    <phone_type>Mobile</phone_type>\n    <confidence>Verified</confidence>\n    <disposable_number>Yes</disposable_number>\n  </result>\n  <metadata>\n    <phone_detail>\n      <original_operator_name>T-Mobile</original_operator_name>\n      <original_network_status>Available</original_network_status>\n      <original_home_network_identity>310200</original_home_network_identity>\n      <original_country_prefix>1</original_country_prefix>\n      <original_country_name>United States of America</original_country_name>\n      <original_country_iso>USA</original_country_iso>\n      <operator_name>AT&amp;T</operator_name>\n      <network_status>Available</network_status>\n      <home_network_identity>311480</home_network_identity>\n      <country_prefix>1</country_prefix>\n      <country_name>United States of America</country_name>\n      <country_iso>USA</country_iso>\n      <is_ported>Yes</is_ported>\n      <cache_value_days>0</cache_value_days>\n      <date_cached>2020-10-07</date_cached>\n      <email_to_sms_address>2016477962@mms.att.net</email_to_sms_address>\n      <email_to_mms_address>2016477962@txt.att.net</email_to_mms_address>\n    </phone_detail>\n  </metadata>\n</response>"
                PV Request with Optional Fields (ported_date & live_status) — Extra Clicks Apply:
                  value: "<response xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">\n  <result>\n    <number>17087694383</number>\n    <validated_phone_number>12016477962</validated_phone_number>\n    <formatted_phone_number>(201) 647-7962</formatted_phone_number>\n    <phone_type>Mobile</phone_type>\n    <confidence>Verified</confidence>\n    <ported_date>2019-08-21T00:00:00Z</ported_date>\n    <disposable_number>Yes</disposable_number>\n  </result>\n  <metadata>\n    <phone_detail>\n      <original_operator_name>T-Mobile</original_operator_name>\n      <original_network_status>Available</original_network_status>\n      <original_home_network_identity>310200</original_home_network_identity>\n      <original_country_prefix>1</original_country_prefix>\n      <original_country_name>United States of America</original_country_name>\n      <original_country_iso>USA</original_country_iso>\n      <operator_name>AT&amp;T</operator_name>\n      <network_status>Available</network_status>\n      <home_network_identity>311480</home_network_identity>\n      <country_prefix>1</country_prefix>\n      <country_name>United States of America</country_name>\n      <country_iso>USA</country_iso>\n      <is_ported>Yes</is_ported>\n      <cache_value_days>0</cache_value_days>\n      <date_cached>2020-10-07</date_cached>\n      <email_to_sms_address>2016477962@mms.att.net</email_to_sms_address>\n      <email_to_mms_address>2016477962@txt.att.net</email_to_mms_address>\n    </phone_detail>\n  </metadata>\n</response>"
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/PhoneValidationV2Response'
              examples:
                Default Behavior, No Optional Fields:
                  value:
                    result:
                      number: '17087694383'
                      validated_phone_number: '12016477962'
                      formatted_phone_number: (201) 647-7962
                      phone_type: Mobile
                      confidence: Verified
                      disposable_number: 'Yes'
                    metadata:
                      phone_detail:
                        original_operator_name: T-Mobile
                        original_network_status: Available
                        original_home_network_identity: '310200'
                        original_country_prefix: '1'
                        original_country_name: United States of America
                        original_country_iso: USA
                        operator_name: AT&T
                        network_status: Available
                        home_network_identity: '311480'
                        country_prefix: '1'
                        country_name: United States of America
                        country_iso: USA
                        is_ported: 'Yes'
                        cache_value_days: 0
                        date_cached: '2020-10-07'
                        email_to_sms_address: 2016477962@mms.att.net
                        email_to_mms_address: 2016477962@txt.att.net
                PV Request with Optional Fields (ported_date & live_status) — Extra Clicks Apply:
                  value:
                    result:
                      number: '17087694383'
                      validated_phone_number: '12016477962'
                      formatted_phone_number: (201) 647-7962
                      phone_type: Mobile
                      confidence: Verified
                      ported_date: '2019-08-21T00:00:00Z'
                      disposable_number: 'Yes'
                    metadata:
                      phone_detail:
                        original_operator_name: T-Mobile
                        original_network_status: Available
                        original_home_network_identity: '310200'
                        original_country_prefix: '1'
                        original_country_name: United States of America
                        original_country_iso: USA
                        operator_name: AT&T
                        network_status: Available
                        home_network_identity: '311480'
                        country_prefix: '1'
                        country_name: United States of America
                        country_iso: USA
                        is_ported: 'Yes'
                        cache_value_days: 0
                        date_cached: '2020-10-07'
                        email_to_sms_address: 2016477962@mms.att.net
                        email_to_mms_address: 2016477962@txt.att.net
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '406':
          description: Not Acceptable
        '408':
          description: Request Timeout
        '415':
          description: Unsupported Media Type
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
        '503':
          description: Service Unavailable
      security:
      - OAuth2: []
      - Auth-Token: []
      operationId: postPhoneValidateV2
      x-operation-id-source: derived
components:
  schemas:
    PhoneValidationV2Metadata:
      type: object
      properties:
        code:
          type:
          - string
          - 'null'
          description: Ignore, currently not used.
        message:
          type:
          - string
          - 'null'
          description: Ignore, currently not used.
        phone_detail:
          $ref: '#/components/schemas/PhoneValidationV2PhoneDetail'
      additionalProperties: false
      description: The metadata model.
    PhoneValidationV2PhoneDetail:
      type: object
      properties:
        original_operator_name:
          type:
          - string
          - 'null'
          description: The name of the MSISDN operator where the phone number was originally registered.
          example: T-Mobile
        original_network_status:
          type:
          - string
          - 'null'
          description: The status of the network where the phone number was originally registered.
          example: Available
        original_home_network_identity:
          type:
          - string
          - 'null'
          description: The Mobile Country Code (MCC) and Mobile Network Code (MNC) where the phone number was originally registered.
          example: '310200'
        original_country_prefix:
          type:
          - string
          - 'null'
          description: The international calling code of the country where the phone number was originally registered.
          example: '1'
        original_country_name:
          type:
          - string
          - 'null'
          description: The name of the country where the phone number was originally registered.
          example: United States of America
        original_country_iso:
          type:
          - string
          - 'null'
          description: The 3-letter ISO code of the country where the phone number was originally registered.
          example: USA
        operator_name:
          type:
          - string
          - 'null'
          description: The name of the MSISDN operator where the phone number is currently registered.
          example: Verizon
        network_status:
          type:
          - string
          - 'null'
          description: The status of the network where the phone number is currently registered.
          example: Available
        home_network_identity:
          type:
          - string
          - 'null'
          description: The Mobile Country Code (MCC) and Mobile Network Code (MNC) where the phone number is currently registered.
          example: '311480'
        country_prefix:
          type:
          - string
          - 'null'
          description: The international calling code of the country where the phone number is currently registered.
          example: '1'
        country_name:
          type:
          - string
          - 'null'
          description: The name of the country where the phone number is currently registered.
          example: United States of America
        country_iso:
          type:
          - string
          - 'null'
          description: The 3-letter ISO code of the country where the phone number is currently registered.
          example: USA
        is_ported:
          type:
          - string
          - 'null'
          description: Indicates whether the phone number is ported or not.
          example: 'Yes'
        cache_value_days:
          type:
          - integer
          - 'null'
          description: The requested number of days to look back in the cache for this phone number.
          format: int32
          example: 0
        date_cached:
          type:
          - string
          - 'null'
          description: The last date this phone number was checked.
          example: '2020-04-22'
        email_to_sms_address:
          type:
          - string
          - 'null'
          description: Email address which can be used to send SMS messages to this phone number.
          example: 7087694383@vtext.com
        email_to_mms_address:
          type:
          - string
          - 'null'
          description: Email address which can be used to send MMS messages to this phone number.
          example: 7087694383@vzwpix.com
      additionalProperties: false
      description: Metadata fields and values that can be returned, in addition to the main core information.
    PhoneValidationV2SupplementaryLiveStatus:
      type: object
      properties:
        mobile:
          type:
          - array
          - 'null'
          items:
            type: string
          description: An indicator to attempt to get supplementary live status for Mobile Phone Number.
          example:
          - USA
        landline:
          type:
          - array
          - 'null'
          items:
            type: string
          description: An indicator to attempt to get supplementary live status for Landline Phone Number.
          example:
          - GBR
      additionalProperties: false
      description: The supplementary live status request model. Please note that this feature has additional charge if requested.
      xml:
        name: supplementarylivestatusrequest
    PhoneValidationV2Result:
      type: object
      properties:
        number:
          type:
          - string
          - 'null'
          description: The phone number that is the subject of the validation.
          example: '17087694383'
        validated_phone_number:
          type:
          - string
          - 'null'
          description: 'The validated phone number. Also includes the international country calling code. Note

            that this field is returned even if the phone number has a confidence status of "Invalid".'
          example: '17087694383'
        formatted_phone_number:
          type:
          - string
          - 'null'
          description: The phone number in the format you specified in "output_format".
          example: (708) 769-4383
        phone_type:
          type:
          - string
          - 'null'
          description: 'The type of phone number. Note: Landline is only supported in North America.'
          example: Mobile
        confidence:
          $ref: '#/components/schemas/PhoneValidationV2Confidence'
        ported_date:
          type:
          - string
          - 'null'
          description: "The date the phone number was last ported, returned only if the number has been moved to a different network. \nThis is an optional field and is included only when get_ported_date is set to true, which incurs an additional click."
          example: '2012-06-27T09:32:09Z'
        disposable_number:
          type:
          - string
          - 'null'
          description: 'Indicates whether the phone number is a disposable number based on lookup list of disposable numbers.

            If the number can be found in the lookup list, the value returned will be "Yes". Otherwise, the value returned

            will be "Unknown". This value would be returned if the get_disposable_number boolean is set to true.'
          example: 'Yes'
      additionalProperties: false
      description: Details about the result. Includes the validated data and its confidence level.
    PhoneValidationV2Response:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ResponseError'
        result:
          $ref: '#/components/schemas/PhoneValidationV2Result'
        metadata:
          $ref: '#/components/schemas/PhoneValidationV2Metadata'
      additionalProperties: false
      description: The response model.
      xml:
        name: response
    PhoneValidationV2Request:
      required:
      - number
      type: object
      properties:
        number:
          minLength: 1
          type: string
          description: The phone number that is the subject of the validation.
          example: '17087694383'
        output_format:
          maxLength: 10
          minLength: 0
          type:
          - string
          - 'null'
          description: 'The desired format of the phone number: E164, PLUS_E164, NATIONAL, any 3-letter ISO country code.

            If not specified, the default format, E164, will be used.'
          example: NATIONAL
        cache_value_days:
          maximum: 30
          minimum: 0
          type:
          - integer
          - 'null'
          description: 'The number of days to look back in cache for the validation result for this phone number.

            If the result is cached, the response will be returned faster. Acceptable values from 0 (no cache)

            to 30. If not specified, the default value, 7, will be used.'
          format: int32
          example: 0
        country_iso:
          maxLength: 3
          minLength: 0
          type:
          - string
          - 'null'
          description: You can indicate the 3-letter ISO country code if the phone number that is subject to validation doesn't contain a phone country code.
        get_ported_date:
          type: boolean
          description: 'The date the phone number was last ported, returned only if the number has been moved to a different network.

            This is an optional field and is included only when get_ported_date is set to true, which incurs an additional click.'
          example: true
        get_disposable_number:
          type:
          - boolean
          - 'null'
          description: 'A boolean indicator to attempt to verify if the number is known to be disposable.

            A disposable number is a shared mobile(or landline) that can be used to receive a text, or phone call.'
          example: true
        supplementary_live_status:
          $ref: '#/components/schemas/PhoneValidationV2SupplementaryLiveStatus'
      additionalProperties: false
      description: The request model.
      xml:
        name: request
    PhoneValidationV2Confidence:
      enum:
      - Verified
      - Absent
      - Teleservice not provisioned
      - Unverified
      - No coverage
      - Unknown
      - Dead
      type: string
      description: The outcome (confidence level) of the validation.
    ResponseError:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A link to documentation that provides more details about the error you’ve encountered.
        title:
          type:
          - string
          - 'null'
          description: The title of the error.
          example: Bad Request
        detail:
          type:
          - string
          - 'null'
          description: A description of the error.
          example: The request body was malformed.
        instance:
          type:
          - string
          - 'null'
          description: The endpoint that returned the error.
      additionalProperties: false
      description: Error model containing the error details.
  securitySchemes:
    OAuth2:
      type: http
      description: "Token URL: https://sso.experianaperture.io/oauth2/aust0wkxjeKyT3HRO4x7/v1/token \n\n Flow: clientCredentials"
      scheme: Bearer
      bearerFormat: JWT
    Auth-Token:
      type: apiKey
      description: Your unique key, called a token, that is required to submit an API request.
      name: Auth-Token
      in: header
    x-app-key:
      type: apiKey
      description: Alternative Auth Token header.
      name: x-app-key
      in: header