Data Quality user documentation
home/Phone validation/Experian Phone Validation/Bulk phone API reference/Get batch results

Get batch results

Headers

Name Type Description
Auth-Token string Input your unique token here. This is required to submit an API request.
Reference-Id
(Optional)		 string Identifier that will be returned to the response to help you track the request.
Add-Metadata
(Optional)		 boolean Specify whether the response should return all fields and values, in addition to the main core information.
The default value of this setting is false.

Path parameters

Name Type Description
batch_id string The batch ID.

Body fields

The response from the API returns the below fields within a result object. Should an error occur, an error object is returned instead.

Name Type Description
batch_id string The Batch ID.
credits_charged string The number of credits charged for this Batch.
status string The current status of the Batch.
statistics object The statistics of the phone numbers confidence level.
phones collection The phone numbers validation results.

Phone validation result fields

Name Type Description
number string The phone number that you are submitting for validation, either in the format local to your country or with phone country code.
validated_phone_number string 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 "unverified".
formatted_phone_number string The phone number in the format you specified in "output_format".
phone_type string The type of phone number:
  • mobile - A phone number assigned to a Mobile Telephone Operator / Cell Phone Operator.
  • landline - A wired telephone in a fixed location such as home or office.
  • mobile or landline - The telephone number could belong to either a mobile or landline type phone.
  • toll free - The number can be called from within the home country at no cost. There may be a charge to call this number from outside the home country. This is also called Freephone.
  • premium - There is a premium charge added to call this number, often there is a service provided on the number so the callee typically receives revenue from the call.
  • shared cost - This telephone number will charge both the caller and callee at the same time. There will be an additional charge to call this type of number.
  • VoIP - Assigned to a VoIP provider who delivers calls and text messages over the internet.
  • stage and screen - Reserved by a regulatory body specifically for use as fictitious numbers in films, stage and screen. No real end user will be assigned.
  • pager - Allocated to a device that receives and displays numeric or alphanumeric messages.
  • universal access number - Typically used by companies to route calls to multiple destinations depending on parameters such as time of day, where the caller currently resides (so not linked to any specific locality within the country), capacity and more.
  • personal number - Intended to be used by individuals which may route to multiple locations (home, office and cell). Some are charged at a premium number rate.
  • voicemail only - Access number for voicemail only.
  • bad format - The number you submitted could not be identified as a valid telephone number. Check that you added an international country code.
  • unknown - Valid number format but not verified with network lookup. Could try again at a later date.
confidence string The outcome of the validation:
  • verified - Number format validated and number verified.
  • absent - Number format validated and number verified via network lookup but not currently available (e.g. phone off, out of range).
  • teleservice not provisioned - Number is assigned to a SIM card which is not allowed to make or receive telephone calls. Typically a "data only SIM".
  • unverified - Invalid number format supplied.
  • unknown- Valid number format but not verified with network lookup.
  • no coverage - Unable to detect the live status for the telephone network.
  • dead - Number has been confirmed to be dead by the network and will not receive calls or text messages.
ported_date string The date that the phone number was last ported if the number has been ported to a different network other than the originally assigned network. This value would be returned if the get_ported_date boolean is set to true.
disposable_number string This field will return a yes if the number is known to be from a disposable network, or has been found on a website advertising disposable numbers, otherwise it will return an unknown.
metadata object The Metadata object contains additional information about the phone number. This object is only returned when the Add-Metadata header is set to True on the request.

Phone validation result metadata fields

Name Type Description
original_operator_name string The name of the MSISDN operator where the phone number was originally registered.
original_network_status string The status of the network where the phone number was originally registered.
original_home_network_identity string The Mobile Country Code (MCC) and Mobile Network Code (MNC) where the phone number was originally registered.
original_country_prefix string The international calling code of the country where the phone number was originally registered.
original_country_name string The name of the country where the phone number was originally registered.
original_country_iso string The 3-letter ISO code of the country where the phone number was originally registered.
operator_name string The name of the MSISDN operator where the phone number is currently registered.
network_status string The status of the network where the phone number is currently registered.
home_network_identity string The Mobile Country Code (MCC) and Mobile Network Code (MNC) where the phone number is currently registered.
country_prefix string The international calling code of the country where the phone number is currently registered.
country_name string The name of the country where the phone number is currently registered.
country_iso string The 3-letter ISO code of the country where the phone number is currently registered.
is_ported string Indicates whether the phone number is ported or not.
email_to_sms_address string Email address which can be used to send SMS messages to this phone number.
email_to_mms_address string Email address which can be used to send MMS messages to this phone number.

The following response codes can be returned by the API:

HTTP status code Title Scenario
200 Success You've submitted a successful request and a valid response was returned.
400 Bad Request You've submitted an invalid batch_id path parameter.
Your Batch has not been started.
Your Batch is older than 28 days.
You didn't provide an authentication token. Try submitting another request and make sure you specify your token, which you can find by signing in to the Self Service Portal.
You've submitted a malformed request body. Try sending another call and make sure the request body contains all required fields and that they are formatted correctly.
You've submitted an empty request body. Try sending another call and make sure the request body contains all required fields.
You've submitted an invalid Reference-ID header. Try submitting another request and make sure this header is formatted correctly.
You've submitted an invalid Add-Metadata header. Try submitting another request and make sure this header is formatted correctly.
401 Unauthorized The authentication token you've provided is incorrect. Sign in to the Self Service Portal to find the right token.
403 Forbidden The authentication token you've provided is valid, but it's associated with another product or you have insufficient credits. Sign in to the Self Service Portal to check if you are using the right token and if you have credits.
The authentication token you've provided is disabled. Sign in to the Self Service Portal to activate the token.
The domain you've sent the request from does not have access to your integration. Sign in to the Self Service Portal to whitelist the domain.
The IP address you've sent the request from does not have access to your integration. Sign in to the Self Service Portal to whitelist the IP address.
404 Not Found The resource you've requested could not be found. Try submitting another call and make sure you're using the correct endpoint URL. If the issue persists, contact us.
406 Not Acceptable You've specified an invalid Accept header. Try submitting another call and make sure you specify a valid Accept value. Check out Supported data formats for details.
415 Unsupported Media Type You've specified an invalid Content-Type header. Try submitting another call and make sure you specify a valid Content-Type value. Check out Supported data formats for details.
429 Too Many Requests You've submitted too many requests. To protect all customers, your account has been temporarily throttled. Check out Rate limiting for details.
500 Internal Server Error An unexpected server error was encountered. Try submitting another request. If the issue persists, contact us.
503 Service Unavailable The service is currently unavailable. You can check the API's uptime and downtime by going to our service status page.

Error response

Successful API request returns the response within a result object. However, should an error occur, an error object is returned instead with the below fields.

Name Type Description
type string A link to documentation that provides more details about the error you've encountered.
title string The title of the error.
detail string A description of the error.
instance string The endpoint that returned the error.

Request

GET https://api.experianaperture.io/phone/bulk/v1/batches/<batch_id>/results

Response

{
  "result": {
    "batch_id": "<batch_id>",
    "credits_charged": 0,
    "status": "processing",
    "statistics": [],
    "phones": []
  }
}

{
  "result": {
    "batch_id": "<batch_id>",
    "credits_charged": 1,
    "status": "completed",
    "statistics": [
      {
        "name": "verified",
        "value": 1
      }
    ],
    "phones": [
      {
        "number": "1234567890",
        "validated_phone_number": "1234567890",
        "formatted_phone_number": "1234567890",
        "phone_type": "mobile",
        "confidence": "verified",
        "ported_date": "not applicable",
        "disposable_number": "unknown",
        "metadata": {
          "original_operator_name": "Bell Mobility",
          "original_network_status": "available",
          "original_home_network_identity": "123456",
          "original_country_prefix": "1",
          "original_country_name": "Canada",
          "original_country_iso": "CAN",
          "operator_name": "Rogers Wireless",
          "network_status": "available",
          "home_network_identity": "123456",
          "country_prefix": "1",
          "country_name": "Canada",
          "country_iso": "CAN",
          "is_ported": "no",
          "email_to_sms_address": "1234567890@sms.rogers.com"
        }
      }
    ]
  }
}

{
  "result": {
    "batch_id": "<batch_id>",
    "credits_charged": 1,
    "status": "completed",
    "statistics": [
      {
        "name": "verified",
        "value": 1
      }
    ],
    "phones": [
      {
        "number": "1234567890",
        "validated_phone_number": "1234567890",
        "formatted_phone_number": "1234567890",
        "phone_type": "mobile",
        "confidence": "verified",
        "ported_date": "not applicable",
        "disposable_number": "unknown"
      }
    ]
  }
}
Experian Phone Validation

Bulk phone API reference