API Documentation

Residential Phone Append.

Start with a name and address, get back a landline phone number — with a confidence grade, the line type, and the carrier. You're only billed when there's a match.

Endpoint: https://rapid.peachtreedata.com/api/v1/residentialphoneappend
Methods: GET — one individual or household per request
Formats: JSON by default; append .xml for XML

Authentication

Every request carries your API key in the query string. The API is HTTPS-only, so the key is encrypted in transit. Query parameters can appear in any order, and responses are JSON by default — append .xml to the endpoint for XML.

https://rapid.peachtreedata.com/api/v1/residentialphoneappend?apikey={apikey}&…

Don't have a key? Sign up under plans & pricing below — keys work immediately.

Request

Parameter	Required	Description
apikey	Yes	Your unique API key.
firstName	—	First name of the individual. Required when matchType is I (individual).
lastName	Yes	Last name of the individual or household.
address1	Yes	Street address portion. Example: 111 Main St.
address2	—	Secondary address, usually the suite or apartment number.
city	—	City name. City + state or ZIP Code is required.
state	—	State name or abbreviation. City + state or ZIP Code is required.
zip	—	ZIP Code. City + state or ZIP Code is required.
matchType	—	I for individual matches; H (or omitted) for household matches.
requestId	—	Any identifier you choose; echoed back in the response.

Addresses must include city + state, or a ZIP Code. With matchType I, the first name is required too.

Examples

Lookup (GET)

curl "https://rapid.peachtreedata.com/api/v1/residentialphoneappend?apikey={apikey}\
&firstName=John&lastName=Doe\
&address1=111+Main+St&zip=30097\
&matchType=I&requestId=222"

Matched response — billable

{
  "confidence": "1",
  "category": "I",
  "phoneType": "L",
  "recType": "R",
  "telcoName": "",
  "phoneNumber": "6784730000",
  "status": "Match",
  "billable": true,
  "requestId": "222"
}

No-match response — not billed

{
  "status": "NoMatch",
  "billable": false,
  "requestId": "222"
}

Response reference

Field	Type	Description
phoneNumber	String(10)	Ten-digit phone number.
confidence	String(1)	How confident the match is. 1–3 — highly confident match 4 — possibility of a disconnect 5 — likely to be a disconnected number
category	String(2)	What the number was matched on. I — individual H — household A — address NZ — full name and ZIP LZ — last name and ZIP
phoneType	String(1)	Type of line. L — landline V — VoIP W — wireless O — other
recType	String(1)	Type of record. R — residential B — business P — payphone U — unknown
telcoName	String(60)	The telephone company the matched phone number belongs to.
status	String(7)	Match — number found. NoMatch — number not found. Error — a processing error occurred.
statusMessage	String(200)	When status is Error, the description.
billable	Boolean	Whether this request will be billed. Only requests with a matching append result are billed.
requestId	String(50)	Echo of the requestId you sent, unchanged.

HTTP response codes

Code	Description
200	Processed successfully.
400	Bad request — the API key format is invalid, the key is missing, or the input wasn't properly passed.
401	Unauthorized — the API key is inactive or invalid.
403	Forbidden — the request exceeds the max items allowed per call, or the account isn't set up for this service.
408	Request timeout — processing exceeded the max processing time.
500	Internal server error during processing.

Plans & pricing

$100/mo

4,000 matches per month

$0.025 per match above 4,000 in a month.

Only matches count against your quota — no-match lookups are free. Need higher volume or invoicing? Talk to us.

Appending phone numbers to your data?

Tell us what you're building and we'll get you moving — usually the same day.

Send Us a Note 678-987-4600