API Documentation

Demographics Append.

Start with an email address — or a name and address — and get back demographics: age range, household income, education, occupation, home ownership, and more. You pick the fields; billing counts only the ones actually found.

Endpoint: https://rapid.peachtreedata.com/api/v1/demographicsappend
Methods: GET for a single individual · POST for a batch
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/demographicsappend?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.
fields	Yes	Comma-separated list of the fields you want back, or All for everything. Billing is based on the number of found fields returned. Available: MaritalStatus, NetWorth, Occupation, Education, HomeMarketValue, Gender, LengthOfResidence, HouseholdIncome, HomeOwnerStatus, Age, PresenceOfChildren, City, State, ZipCode.
emailAddress	—	A known email address for the individual. Can stand alone, but the more parameters you provide, the more accurate the result. Only one of emailAddress, emailAddressSHA1, or emailAddressMD5 may be provided.
emailAddressSHA1	—	A SHA-1-hashed email address — same rules as emailAddress.
emailAddressMD5	—	An MD5-hashed email address — same rules as emailAddress.
firstName	—	First name. If any part of the name is provided, also provide an email address, or address/city/state/zip.
lastName	—	Last name. If any part of the name is provided, also provide an email address, or address/city/state/zip.
address	—	Street address. If provided, also provide an email address or a name.
city	—	City. If provided, also provide an email address or a name.
state	—	State. If provided, also provide an email address or a name.
zip	—	ZIP Code. If provided, also provide an email address or a name.
requestId	—	Any identifier you choose; echoed back unchanged. Strongly recommended for batch POSTs so you can correlate responses to requests.

Examples

All fields for an email address (GET)

curl "https://rapid.peachtreedata.com/api/v1/demographicsappend?apikey={apikey}\
&fields=all&email=someone@acompany.com"

Response — 5 of 14 fields found; billing counts 5

{
  "countOfFieldsRequested": 14,
  "countOfFieldsReturned": 5,
  "age": "45-54",
  "gender": "Male",
  "education": "Completed College",
  "occupation": "Professional",
  "netWorth": "100k-250k",
  "city": "Duluth",
  "state": "GA",
  "zipCode": "30097",
  "status": "Valid"
}

Specific fields only

curl "https://rapid.peachtreedata.com/api/v1/demographicsappend?apikey={apikey}\
&email=someone@acompany.com&fields=gender,age,netWorth"

{
  "countOfFieldsRequested": 3,
  "countOfFieldsReturned": 3,
  "age": "45-54",
  "gender": "Male",
  "netWorth": "100k-250k",
  "status": "Valid",
  "requestId": "1234"
}

Batch (POST) — envelope totals what you're billed

POST https://rapid.peachtreedata.com/api/v1/demographicsappend?apikey={apikey}&fields=all
Content-Type: application/json

[
  { "emailAddress": "someone1@acompany.com", "requestId": "1" },
  { "emailAddress": "someone2@acompany.com", "requestId": "2" },
  { "email": "NOT_AN_EMAIL_ADDRESS", "requestId": "3" }
]

// Response envelope:
{
  "totalRequests": 3,
  "totalProcessed": 2,
  "totalInvalidRequests": 1,
  "totalBillableFieldCount": 10,
  "responses": [ { "…": "one response per request, as in the GET example" } ]
}

Response reference

Batch envelope (POST only)

Field	Type	Description
totalRequests	int	Requests in the POST body.
totalProcessed	int	Requests successfully processed.
totalInvalidRequests	int	Requests that were invalid and not processed.
totalBillableFieldCount	int	Sum of countOfFieldsReturned across the responses — this is what a POST request bills on.

Per-individual response

Field	Type	Description
countOfFieldsRequested	int	Fields listed in the request. With fields=all, this is 14 — the maximum.
countOfFieldsReturned	int	Fields actually found for the individual.
age	String	18-20, 21-24, 25-34, 35-44, 45-54, 55-64, or 65+.
gender	String	Male or Female.
education	String	Completed High School, Attended College, Completed College, Completed Graduate School, or Attended Vocational/Technical School.
occupation	String	One of: Blue Collar Worker, Business Owner, Civil Service, Executive/Upper Management, Health Services, Homemaker, Middle Management, Military Personnel, Nurse, Part Time, Professional, Retired, Secretary, Student, Teacher, Technology, White Collar Worker.
netWorth	String	0-5k, 5k-10k, 10k-25k, 25k-50k, 50k-100k, 100k-250k, 250k-500k, 500k-1mm, or 1mm+.
householdIncome	String	0-15k, 15k-25k, 25k-35k, 35k-50k, 50k-75k, 75k-100k, 100k-150k, 150k-175k, 175k-200k, 200k-250k, or 250k+.
presenceOfChildren	String	Yes or No.
maritalStatus	String	Single or Married.
homeOwnerStatus	String	Rent or Own.
lengthOfResidence	String	Less than 1 year, 1–10 Years (by year), 11-15 years, 16-19 years, or 20+ years.
homeMarketValue	String	1k-25k, 25k-50k, 50k-75k, 75k-100k, 100k-150k, 150k-200k, 200k-250k, 250k-300k, 300k-350k, 350k-500k, 500k-1mm, or 1mm+.
city	String	City found for the individual.
state	String	State found for the individual.
zipCode	String	ZIP Code found for the individual.
status	String	Valid, InvalidRequest, or Error. Only Valid results carry charges, based on the number of fields returned.
statusMessage	String	Description of the status when it isn't Valid.
requestId	String	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

$250/mo

25,000 matches per month

$0.01 per match above 25,000 in a month.

Billing counts the fields actually returned — a request that finds nothing costs nothing. Need higher volume or invoicing? Talk to us.

Enriching your customer data?

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

Send Us a Note 678-987-4600