| 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. |
| Timeout-Seconds (Optional) |
integer | 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. The default value of this setting is 15. |
| 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 true. |
In the request body you can specify:
| Name | Type | Description | |
|---|---|---|---|
| components | object | Object defining the input components. | |
| first_name | collection | Collection containing the first name of the individual. | |
| middle_name (Optional) |
collection | Collection containing the middle name of the individual. | |
| last_name | collection | Collection containing the last name of the individual. | |
| address_line_1 | collection | Collection containing the address of the individual. | |
| town (Optional) |
collection | Collection containing the town, city or suburb. | |
| sub_region (Optional) |
collection | Collection containing the county. | |
| region (Optional) |
collection | Collection containing the state or province. | |
| postal_code (Optional) |
collection | Collection containing the post/zip code. | |
| options (Optional) |
collection | Collection of objects consisting of a name and a value property. The objects define the optional request parameters. See options for more detailed information.
| |
| name | string | The name of the optional request parameter, e.g. dnc_preference. | |
| value | string | The value of the optional request parameter, e.g. exclude. | attributes | collection | Collection containing the type of the request, e.g. phone. |
These are the optional request parameters available for the Phone Append API.
| Name | Value | Description |
|---|---|---|
| dnc_preference | flag | The API will return all available numbers with dnc flagged as either True or False. The default value of this setting is flag. |
| exclude | The API will only return numbers with dnc flagged as False. | |
| only | The API will only return numbers with dnc flagged as True. |
| Name | Type | Description |
|---|---|---|
| Reference-Id (Optional) |
string | Identifier that was supplied by you in the request header to help you track the request. |
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 |
|---|---|---|
| phones | string | The matched phone number(s) of the individual |
| Name | Type | Description | |
|---|---|---|---|
| phone_detail | collection | The phone detail metadata | |
| phone_type | string | The type of phone based on its classification of intended purpose, i.e. mobile, landline etc. | |
| number | string | The phone number of the individual | |
| dnc | boolean | A value of "true" indicates that the phone number appears on the Do Not Call list; otherwise the value is "false" | |
| dnc_date_revised | string | The last date the phone number appeared on the Do Not Call list | |
| rank | integer | The rank of the phone number most likely in use by the individual | |
The following response codes can be returned by the API:
| Status Code | Reason phrase | Description |
|---|---|---|
| 200 | Success | Request processed successfully. |
| 400 | Bad Request | Request failed due to malformed syntax. |
| 401 | Unauthorized | Auth-Token provided is incorrect. |
| 403 | Forbidden | Request is not authorized to use this service. |
| 404 | Not Found | Request is not found. |
| 406 | Not Acceptable | Request is not in an acceptable format. |
| 408 | Request Timeout | Response was not returned within the timeout allowance. |
| 415 | Unsupported Media Type | Request is not using a Media type that is recognized by the server. |
| 429 | Too many requests | Too many requests were sent. To protect all customers, your account has been temporarily throttled. Check our rate limiting for more details. |
| 500 | Internal Server Error | The server has encountered an error. |
| 503 | Service Unavailable | Service unavailable. Check service status for up-to-date information. |
{
"components": {
"first_name": [
"John"
],
"middle_name": [
"Abraham"
],
"last_name": [
"Smith"
],
"address_line_1": [
"1 Main Street"
],
"town": [
"Phoenix"
],
"region": [
"AZ"
],
"postal_code": [
"94133"
]
},
"options": [
{
"name": "dnc_preference",
"value": "flag"
}
],
"attributes": [
"phone"
]
}
{
"result": {
"phones": [
"829-432-9960",
"627-808-2662",
"429-785-9556",
"829-996-9087",
]
},
"metadata": {
"phone_detail": [
{
"phone_type": "mobile",
"number": "829-432-9960",
"dnc": false,
"dnc_date_revised": "2024-01-11",
"rank": 1
},
{
"phone_type": "mobile",
"number": "627-808-2662",
"dnc": true,
"dnc_date_revised": "2024-01-11",
"rank": 2
},
{
"phone_type": "mobile",
"number": "429-785-9556",
"dnc": false,
"dnc_date_revised": "2024-01-11",
"rank": 3
},
{
"phone_type": "landline",
"number": "829-996-9087",
"dnc": true,
"dnc_date_revised": "2024-01-11",
"rank": 4
}
]
}
}