{"_id":"55cba6d637edd823001a85e8","editedParams":true,"version":{"_id":"55cba6d237edd823001a85d7","project":"55c80e130300460d00c91c1d","__v":3,"createdAt":"2015-08-12T20:04:34.776Z","releaseDate":"2015-08-12T20:04:34.776Z","categories":["55cba6d337edd823001a85d8","55cba6d337edd823001a85d9","55cba6d337edd823001a85da","55cba6d337edd823001a85db","55cbd8e84cf2180d00bb1c15","561312bc41a9ec0d00a3fdfc"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2"},"__v":0,"parentDoc":null,"editedParams2":true,"project":"55c80e130300460d00c91c1d","user":"55c80d9f0300460d00c91c1a","category":{"_id":"55cba6d337edd823001a85d9","pages":["55cba6d637edd823001a85e7","55cba6d637edd823001a85e8","55cba6d637edd823001a85e9","55cba6d637edd823001a85ea","55cbbab850046e3700d91055","55cc983d791e5b1900e81d5b","55cc9871791e5b1900e81d5c","55cc9885791e5b1900e81d5f","55df34f6ddfb40170061cf79","55f2ca3571c6462100e0fd95","55f2ccd8fb7aad2300bf17fa","55f2e12dfb7aad2300bf1826","564bb14202c94e0d00a7e88a"],"project":"55c80e130300460d00c91c1d","version":"55cba6d237edd823001a85d7","__v":10,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-08-10T02:48:35.940Z","from_sync":false,"order":1,"slug":"data-append-end-api","title":"DATA APPEND END API"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-08-11T23:13:06.181Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"name":"PHP","code":"<?php\n\n$licensekey = \"YOURKEYHERE\";\n\n//       https://api.accurateappend.com/Services/V2/AppendPhone/Residential/\n$url =  \"https://api.accurateappend.com/Services/V2/AppendPhone/Residential/\" . $licensekey . \"/?\";\n$querystring = \"firstname=john\" .\n               \"&lastname=smith\" .\n               \"&address=\" . urlencode(\"123 main st\") .\n               \"&city=seattle\" .\n               \"&state=wa\" .\n               \"&postalcode=98101\" .\n               \"&source=C;D\" .\n               \"&matchlevel=E1;E2;N1;N2\";\n\n$url .= $querystring;\n//echo \"request url: \" . $url . \"<br>\\n<br>\\n\";\n\nif(strtoupper(substr(PHP_OS, 0, 3)) === 'WIN')\n{\n    // windows operating system as the requesting server\n    $cacert_path_file = dirname(__FILE__) . \"\\cacert.pem\";\n}\nelse\n{\n    // other os\n    $cacert_path_file = \"cacert.pem\";\n}\n\n$ch = curl_init();\ncurl_setopt($ch, CURLOPT_URL, $url);\ncurl_setopt($ch, CURLOPT_HTTPGET, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));\ncurl_setopt($ch, CURLOPT_SSLVERSION, 'CURL_SSLVERSION_DEFAULT');  // on a windows server the single quotes are required on 3rd parameter\ncurl_setopt($ch, CURLOPT_CAINFO, $cacert_path_file);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_VERBOSE, true);\n\n$json_string = curl_exec($ch);\n$curl_err = curl_error($ch);\n\nif($curl_err)\n{\n    echo \"curl error: $curl_err\";\n}\nelse\n{\n    curl_close($ch);\n\n    // decode json\n    $parsed_json = json_decode($json_string);\n\n    // instantiate an associative array\n    $response = array();\n    // load json data into associative array\n    $response = json_to_associative($parsed_json);\n\n    // print the associative array to the screen\n    foreach ($response as $key => $value)\n    {\n        echo $key . \" = \" . $value . \"<br>\\n\";\n    }\n}\n\n\necho \"<br>\\n\";\necho \"<br>\\n\";\necho \"<br>\\n\";\necho \"<br>\\n\";\necho \"<br>\\n\";\necho \"<br>\\n\";\necho \"<br>\\n\";\n\n\n\n// --------------------------------------------------------- //\n//\n// --------------------------------------------------------- //\nfunction json_to_associative($parsed_json)\n{\n    $response = array();\n\n    // load the associative array with all response key/value pairs\n    $response['Host'] = $parsed_json->{'Criteria'}->Host;\n    $response['RequestDate'] = $parsed_json->{'Criteria'}->RequestDate;\n    $response['RequestIP'] = $parsed_json->{'Criteria'}->RequestIP;\n    $response['TransactionId'] = $parsed_json->{'Criteria'}->TransactionId;\n    $response['Address'] = $parsed_json->{'Criteria'}->Address;\n    $response['City'] = $parsed_json->{'Criteria'}->City;\n    $response['FirstName'] = $parsed_json->{'Criteria'}->FirstName;\n    $response['LastName'] = $parsed_json->{'Criteria'}->LastName;\n    $response['PostalCode'] = $parsed_json->{'Criteria'}->PostalCode;\n    $response['State'] = $parsed_json->{'Criteria'}->State;\n    $response['MatchLevels'] = $parsed_json->{'Criteria'}->MatchLevels;\n    $response['Sources'] = $parsed_json->{'Criteria'}->Sources;\n\n\n\n    // typecast the stdClass to array\n    $obj_arr = (array)$parsed_json->{'Phones'};\n\n    if(!empty($obj_arr))\n    {\n        // iteration required for mulitple Phones response\n        for($i = 0; $i < count($parsed_json->{'Phones'}); $i++)\n        {\n            $keynum = $i + 1;\n\n            $response['AreaCode_' . $keynum] = $parsed_json->{'Phones'}[$i]->AreaCode;\n            $response['LineType_' . $keynum] = $parsed_json->{'Phones'}[$i]->LineType;\n            $response['MatchLevel_' . $keynum] = $parsed_json->{'Phones'}[$i]->MatchLevel;\n            $response['MaxValidationLevel_' . $keynum] = $parsed_json->{'Phones'}[$i]->MaxValidationLevel;\n            $response['PhoneNumber_' . $keynum] = $parsed_json->{'Phones'}[$i]->PhoneNumber;\n            $response['Source_' . $keynum] = $parsed_json->{'Phones'}[$i]->Source;\n        }\n    }\n    return $response;\n}\n/*\nCopyright (c) 2015, AccurateAppend Corp\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted \nprovided that the following conditions are met:\n\n1. Redistributions of source code must retain the above copyright notice, this list of conditions \n   and the following disclaimer.\n\n2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions \n   and the following disclaimer in the documentation and/or other materials provided with the distribution.\n\n3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse \n   or promote products derived from this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR \nIMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND \nFITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS \nBE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, \nBUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS \nINTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR \nTORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF \nADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n*/\n?>","language":"php"},{"code":"using System;\nusing System.Collections.Generic;\nusing System.Net;\nusing RestSharp;\n\nnamespace Samples\n{\n    // This example uses the RestSharp NuGet package (https://www.nuget.org/packages/RestSharp)\n  \n    public static class Program\n    {\n        private const String Key = \"YOURKEYHERE\";\n        private const String RootUri = :::at:::\"http://api.accurateappend.com/Services/V2\";\n\n        public static void Main(String[] args)\n        {\n            ResidentialPhoneAppend();\n        }\n\n        #region Phone Append\n\n        private static void ResidentialPhoneAppend()\n        {\n            const String Resource =\n                \"/AppendPhone/Residential/\" + Key +\n                \"/?firstname=john&lastname=smith&address=123 main st&city=seattle&state=wa&postalcode=98101&source=C;D&matchlevel=E1;E2;N1;N2\";\n\n            var request = new RestRequest(Resource) { Method = Method.GET };\n\n            var client = new RestClient(RootUri);\n            var response = client.Execute<PhoneResult>(request);\n            if (response.StatusCode != HttpStatusCode.OK)\n            {\n                // Error Handling Omitted For Brevity\n            }\n            var data = response.Data;\n            foreach (var item in data.Phones)\n            {\n                Console.WriteLine(\"Phone:{0}-{1}\", item.AreaCode, item.PhoneNumber);\n            }\n        }\n\n        public class PhoneResult\n        {\n            public List<PhoneItem> Phones { get; set; }\n        }\n\n        public class PhoneItem\n        {\n            public String AreaCode { get; set; }\n\n            public String LineType { get; set; }\n\n            public String MatchLevel { get; set; }\n\n            public String MaxValidationLevel { get; set; }\n\n            public String PhoneNumber { get; set; }\n\n            public String Source { get; set; }\n        }\n\n\n        #endregion\n    }\n}\n\n/*\nCopyright (c) 2015, AccurateAppend Corp\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted \nprovided that the following conditions are met:\n\n1. Redistributions of source code must retain the above copyright notice, this list of conditions \n   and the following disclaimer.\n\n2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions \n   and the following disclaimer in the documentation and/or other materials provided with the distribution.\n\n3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse \n   or promote products derived from this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR \nIMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND \nFITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS \nBE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, \nBUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS \nINTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR \nTORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF \nADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n*/","language":"csharp"}]},"method":"get","results":{"codes":[{"language":"json","code":"{\n     \"Criteria\": {\n          \"Host\": \"XXXX\",\n           \"RequestDate\": \"2015-08-12T18:37:54.1713974Z\",\n           \"RequestIP\": \"192:168:1:1\",\n           \"TransactionId\": \"6f9f2599-c5b7-49dd-95ba-4753c26a1ce3\",\n           \"Address\": \"123 main st\",\n           \"City\": \"seattle\",\n           \"FirstName\": \"john\",\n           \"LastName\": \"smith\",\n           \"MatchLevels\": \"E1;E2;N1;N2\",\n           \"PostalCode\": \"98101\",\n           \"Sources\": \"C;D\",\n           \"State\": \"wa\" }\n,\n      \"Phones\": [\n          {\n               \"AreaCode\": \"555\",\n                \"LineType\": \"LandLine\",\n                \"MatchLevel\": \"E2\",\n                \"MaxValidationLevel\": \"E1\",\n                \"PhoneNumber\": \"2221111\",\n                \"Source\": \"C\" }\n     ,\n           {\n               \"AreaCode\": \"555\",\n                \"LineType\": \"LandLine\",\n                \"MatchLevel\": \"N2\",\n                \"MaxValidationLevel\": \"E1\",\n                \"PhoneNumber\": \"1112222\",\n                \"Source\": \"D\" }\n      ]\n}","name":"","status":200}]},"settings":"","auth":"required","params":[{"_id":"55cb92c04153080d0044681a","ref":"","in":"path","required":true,"desc":"License key issued by customer support.","default":"","type":"string","name":"licensekey"},{"_id":"55cb92c04153080d00446819","ref":"","in":"query","required":false,"desc":"Search subject's first name.  Optional if lastname is passed in the request.","default":"","type":"string","name":"firstname"},{"_id":"55cb92c04153080d00446818","ref":"","in":"query","required":true,"desc":"Search subject's last name.","default":"","type":"string","name":"lastname"},{"_id":"55cb92c04153080d00446817","ref":"","in":"query","required":false,"desc":"Search subject's address. Currently only US postal addresses are accepted.","default":"","type":"string","name":"address"},{"_id":"55cb92c04153080d00446816","ref":"","in":"query","required":false,"desc":"City associated with search subject's address. Optional, if postal code is passed in the request.","default":"","type":"string","name":"city"},{"_id":"55cb92c04153080d00446815","ref":"","in":"query","required":false,"desc":"State associated with search subject's address. Optional, if postal code is passed in the request.","default":"","type":"string","name":"state"},{"_id":"55cb92c04153080d00446814","ref":"","in":"query","required":false,"desc":"Postal code associated with search subject's address. Optional, if city and state are passed in the request.","default":"","type":"string","name":"postalcode"},{"_id":"55cb92c04153080d00446813","ref":"","in":"query","required":true,"desc":"String delimited list of target Sources to search. At least one Source must be requested.","default":"","type":"string","name":"source"},{"_id":"55cb92c04153080d00446812","ref":"","in":"query","required":false,"desc":"String delimited list of MatchLevels used to filter response. If omitted, the match levels \"E1\",\"E2\",\"N1\",\"N2\" will. be assumed.","default":"","type":"string","name":"matchlevel"}],"url":"/AppendPhone/Residential/:licensekey/?"},"isReference":false,"order":2,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"HTTP Headers\",\n  \"body\": \"When making a call to this API, the HTTP header \\\"content-type\\\" MUST be supplied with a value of \\\"application/json\\\". Failure to include this header will result in an HTTP 400 Bad Request response. Your choice of client library may automatically include this header. Please consult your documentation.\"\n}\n[/block]\n## Making a request\nThe Accurate Append Phone Append Web API closely mimics the logic and data sources used in our batch append service except it allows the user to programmatically make single calls using an API. The service is accessible via secure HTTP through a RESTful API. With an Accurate Append account use contact information such as first name, last name, city, state and physical address to look-up the phone numbers of your customer.\n\n## Phone Element\nA single response may include one Phone element for each Source requested.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"Areacode\",\n    \"0-1\": \"string\",\n    \"0-2\": \"3 digit US area code\",\n    \"1-0\": \"PhoneNumber\",\n    \"1-1\": \"string\",\n    \"1-2\": \"7 digit US phone number\",\n    \"2-0\": \"LineType\",\n    \"2-1\": \"enum\",\n    \"2-2\": \"Indicates the LineType\",\n    \"3-0\": \"MatchLevel\",\n    \"3-1\": \"enum\",\n    \"3-2\": \"Indicates the MatchLevel under which the match was found.\",\n    \"4-0\": \"MaxValidationLevel\",\n    \"4-1\": \"enum\",\n    \"4-2\": \"Indicates the maximum validation level achieved by the input criteria. Measured as MatchLevel.\",\n    \"5-0\": \"Source\",\n    \"5-1\": \"enum\",\n    \"5-2\": \"Indicates in which Source the match was found\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\n## Source\nThe returning source element will indicate if the phone number matched a specific database and may determine if the device used is a mobile phone or a landline phone. For a list of codes and descriptions click [here](http://docs.accurateappend.com/docs/phone-source).\n\n## MatchLevel\nThe MatchLevel response field indicates how well the request fields sent to the API match the response fields. For example, a MatchLevel returned of E1 might be considered an exact match whereas a return of E2 reveals that the first name of the individual does not necessarily match the request fields.  For a list of MatchLevel codes and descriptions click [here](http://docs.accurateappend.com/matchlevel).\n\n## LineType\nFor a list of codes and descriptions click [here](http://docs.accurateappend.com/docs/phone-linetype).\n\n## Error Messages\nFor a list of codes and descriptions click [here](http://docs.accurateappend.com/docs/error-messages).","excerpt":"Reliably add or verify the phone numbers of your clients using other contact information such as first name, last name or address information. Our databases hold both US and Canadian landlines and U.S. mobile telephone numbers. \n\nAccurate Append maintains the most definitive, authoritative source of telephone numbers available in the phone append industry. Our phone databases are comprised of over 600 million landline and mobile phone numbers; helping you stay connected to your customers, prospects, voters, donors, and more.","slug":"appendphone","type":"endpoint","title":"Consumer Phone Append"}

getConsumer Phone Append

Reliably add or verify the phone numbers of your clients using other contact information such as first name, last name or address information. Our databases hold both US and Canadian landlines and U.S. mobile telephone numbers. Accurate Append maintains the most definitive, authoritative source of telephone numbers available in the phone append industry. Our phone databases are comprised of over 600 million landline and mobile phone numbers; helping you stay connected to your customers, prospects, voters, donors, and more.

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

licensekey:
required
string
License key issued by customer support.

Query Params

firstname:
string
Search subject's first name. Optional if lastname is passed in the request.
lastname:
required
string
Search subject's last name.
address:
string
Search subject's address. Currently only US postal addresses are accepted.
city:
string
City associated with search subject's address. Optional, if postal code is passed in the request.
state:
string
State associated with search subject's address. Optional, if postal code is passed in the request.
postalcode:
string
Postal code associated with search subject's address. Optional, if city and state are passed in the request.
source:
required
string
String delimited list of target Sources to search. At least one Source must be requested.
matchlevel:
string
String delimited list of MatchLevels used to filter response. If omitted, the match levels "E1","E2","N1","N2" will. be assumed.

Examples


Result Format


Documentation

[block:callout] { "type": "warning", "title": "HTTP Headers", "body": "When making a call to this API, the HTTP header \"content-type\" MUST be supplied with a value of \"application/json\". Failure to include this header will result in an HTTP 400 Bad Request response. Your choice of client library may automatically include this header. Please consult your documentation." } [/block] ## Making a request The Accurate Append Phone Append Web API closely mimics the logic and data sources used in our batch append service except it allows the user to programmatically make single calls using an API. The service is accessible via secure HTTP through a RESTful API. With an Accurate Append account use contact information such as first name, last name, city, state and physical address to look-up the phone numbers of your customer. ## Phone Element A single response may include one Phone element for each Source requested. [block:parameters] { "data": { "h-0": "Field name", "h-1": "Type", "h-2": "Description", "0-0": "Areacode", "0-1": "string", "0-2": "3 digit US area code", "1-0": "PhoneNumber", "1-1": "string", "1-2": "7 digit US phone number", "2-0": "LineType", "2-1": "enum", "2-2": "Indicates the LineType", "3-0": "MatchLevel", "3-1": "enum", "3-2": "Indicates the MatchLevel under which the match was found.", "4-0": "MaxValidationLevel", "4-1": "enum", "4-2": "Indicates the maximum validation level achieved by the input criteria. Measured as MatchLevel.", "5-0": "Source", "5-1": "enum", "5-2": "Indicates in which Source the match was found" }, "cols": 3, "rows": 6 } [/block] ## Source The returning source element will indicate if the phone number matched a specific database and may determine if the device used is a mobile phone or a landline phone. For a list of codes and descriptions click [here](http://docs.accurateappend.com/docs/phone-source). ## MatchLevel The MatchLevel response field indicates how well the request fields sent to the API match the response fields. For example, a MatchLevel returned of E1 might be considered an exact match whereas a return of E2 reveals that the first name of the individual does not necessarily match the request fields. For a list of MatchLevel codes and descriptions click [here](http://docs.accurateappend.com/matchlevel). ## LineType For a list of codes and descriptions click [here](http://docs.accurateappend.com/docs/phone-linetype). ## Error Messages For a list of codes and descriptions click [here](http://docs.accurateappend.com/docs/error-messages).

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}