API Documentation

US Address Cleanse.

Validate and standardize a US address in real time. The response tells you whether the address is deliverable, standardizes it to USPS format, and parses it into individual fields — ZIP+4, county, carrier route, delivery point, and location.

Endpoint: https://rapid.peachtreedata.com/api/v1/addresscleanse
Methods: GET for a single address · POST for a batch
Formats: JSON by default; append .xml to the endpoint for XML
Try it: Run a live lookup in the demo — no key needed

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/addresscleanse?apikey={apikey}&…

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

Request

Pass the address in one of two shapes — never both in the same request. Use the standard format when your data is already split into fields; use the multiline format when addresses arrive free-form and you don't know which line holds what.

Standard US format

Parameter	Required	Description
apikey	Yes	Your unique API key.
companyname	—	If this is a business address, the name of the company at the address. Powers SuiteLink — see the example below.
address1	—	Street address portion. Example: 111 Main St.
address2	—	Secondary address, usually the suite or apartment number. Example: Suite 200.
city	—	City name. Don't combine with lastline.
state	—	State name or abbreviation. Don't combine with lastline.
zipcode	—	ZIP Code. Don't combine with lastline.
lastline	—	Use when city, state, and ZIP arrive as one line. Example: Atlanta, Georgia 30301.
requestId	—	Any identifier you choose; echoed back in the response.

Addresses must include city + state, city + state + ZIP, ZIP alone, or a last line.

Multiline format

Parameter	Required	Description
apikey	Yes	Your unique API key.
line1 … line8	—	The address exactly as you have it, one field per line, up to eight lines. The cleanse works out which line is which — company names, street, suite, city/state, and ZIP can arrive in any layout.

Multiline requests need at least two address lines.

Examples

Single address (GET)

curl "https://rapid.peachtreedata.com/api/v1/addresscleanse?apikey={apikey}\
&companyname=Peachtree+Data\
&address1=2905+Premiere+Pkwy\
&city=Duluth&state=GA"

Response — note SuiteLink restoring “Ste 200” from the company name; the request didn't include a suite

{
  "status": "Confirmed",
  "statusMessage": "",
  "requestId": "",
  "fullAddress": "2905 Premiere Pkwy Ste 200",
  "primaryAddress": "2905 Premiere Pkwy",
  "secondaryAddress": "Ste 200",
  "lastLine": "Duluth, GA 30097-5275",
  "components": {
    "primaryNumber": "2905",
    "primaryName": "Premiere",
    "primaryType": "Pkwy",
    "secondaryUnitDescription": "Ste",
    "secondaryUnitNumber": "200",
    "city": "Duluth",
    "city13": "Duluth",
    "state": "GA",
    "zip10": "30097-5275",
    "zip5": "30097",
    "zip4": "5275"
  },
  "metadata": {
    "addressType": "HighRise",
    "isDefault": false,
    "countyCode": "135",
    "countyName": "Gwinnett",
    "dpvStatus": "Y",
    "dpvFootnote": "AABB",
    "isDpvNoStat": false,
    "isVacant": false,
    "rawDetailCode": "S90100",
    "deliveryPointBarCode": "50",
    "deliveryPointBarCodeCheckDigit": "7",
    "lineOfTravel": "0104",
    "lineOfTravelOrder": "D",
    "carrierRoute": "R058",
    "suiteLinkResult": "Match",
    "rdi": "Commercial"
  },
  "geoCode": {
    "assignmentLevel": "PRE",
    "censusTractBlock": "0502312009",
    "latitude": 34.005798,
    "longitude": -84.093159,
    "metroStatAreaCode": "0520"
  }
}

Batch (POST) — one JSON array, same fields per address

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

[
  {
    "companyname": "Peachtree Data",
    "address1": "2905 Premiere Pkwy",
    "address2": "Suite 200",
    "city": "Duluth",
    "state": "GA",
    "zipcode": "30097"
  },
  { "...": "up to your plan's max addresses per request" }
]

Multiline (GET) — lines in any layout

curl "https://rapid.peachtreedata.com/api/v1/addresscleanse?apikey={apikey}\
&line1=Peachtree+Data\
&line2=2905+Premiere+Pkwy\
&line3=Suite+200\
&line4=Duluth+GA&line5=30097"

A POST response wraps the per-address results in a small envelope:

Field	Type	Description
totalRequests		Addresses in the request.
totalProcessed		Addresses processed.
totalInvalidRequests		Addresses rejected as invalid requests.
totalError		Addresses that errored during processing.
responses		One response object per address, each with the same shape as a GET response.

Response reference

Root fields

Field	Type	Description
status	String(36)	Result of the cleanse. See status values.
statusMessage	String	When status is Invalid or NotAttempted, the descriptive message.
requestId	String(50)	Echo of the requestId you sent, unchanged.
fullAddress	String(60)	Single-line address containing the primary and secondary address.
primaryAddress	String(60)	Primary address line — street address or PO Box, without secondary information such as the apartment.
secondaryAddress	String(60)	Building name, floor, and room number in one field.
lastLine	String(60)	City, state, and ZIP+4 as one line.
components		Parsed address pieces — see the components table.
metadata		Delivery intelligence — see the metadata table.
geoCode		Location data — see the geoCode table.

components

The address, parsed into its individual pieces.

Field	Type	Description
city	String(28)	City preferred by the postal authority.
city13	String(13)	Abbreviated city preferred by the postal authority.
primaryNumber	String(10)	The premise number.
primaryPrefix	String(2)	Abbreviated directional (N, S, NW, SE…) before the street name.
primaryName	String(28)	Street name.
primaryType	String(4)	Abbreviated street type — St, Ave, Pl.
primaryPostfix	String(2)	Abbreviated directional (N, S, NW, SE…) after the street name.
secondaryUnitDescription	String(8)	Unit description — #, Apartment, Flat.
secondaryUnitNumber	String(8)	Unit number — the 100 in “APT 100”.
state	String(2)	State abbreviation.
zip5	String(5)	Five-digit ZIP Code, without the ZIP+4.
zip4	String(4)	Four-digit ZIP+4 add-on.
zip10	String(10)	Five-digit ZIP Code with the ZIP+4 — 11111-2222.
nonPostalSecondaryAddress	String(20)	Complete non-postal secondary address, such as “PMB 10” — mail delivered through a private mailbox company rather than USPS.
primaryAddressRemainder	String(40)	Extraneous data on the address line that isn't address data or doesn't belong in the standardized line — may include invalid secondary information.
secondaryAddressExtraneous	String(28)	Extraneous data from the secondary address, possibly including invalid secondary data.
extraLine1	String(60)	Non-address data found above or below the address. Multiline input only.
extraLine2	String(60)	Non-address data found above or below the address. Multiline input only.

metadata

Everything USPS knows about deliverability at this address.

Field	Type	Description
addressType	String(15)	Type of address. Street — standard street address HighRise — multi-unit building Firm — business with its own record PoBox — post office box RuralRoute — rural route CMRA — commercial mail-receiving agency (Mailbox Etc.) GeneralDelivery — general delivery Military — military address Unique — unique ZIP Code NoMatch — no match found
dpvStatus	String(1)	Delivery Point Validation result for this record. Y — confirmed delivery point — primary and secondary (if present) are valid D — primary confirmed, but the secondary was missing from the input S — primary confirmed, but the parsed secondary isn't valid in the DPV directory N — not a valid delivery point L — the address triggered DPV locking blank — the address couldn't be assigned
dpvFootnote	String(12)	Up to six two-character DPV footnotes, always in the same order. AA — input matches the ZIP+4 file A1 — input doesn't match the ZIP+4 file BB — all input fields match DPV CC — primary matches, secondary present but invalid C1 — primary matches, secondary required but missing N1 — high-rise missing a secondary number M1 — primary number missing M3 — primary number invalid P1 — missing rural route or highway contract box number P3 — invalid PO, rural route, or highway contract number PB — matches PBSA (PO Box as street address) RR — matches a CMRA R1 — matches a CMRA, secondary not present R7 — matches a phantom route F1 — matches a military address G1 — matches a general delivery address U1 — matches a unique ZIP Code IA — identified as an informed address NL — an NCOALink move address can't be DPV confirmed TA — primary matched by dropping the trailing alpha
isDpvNoStat	String(5)	No-stat indicator: the address is vacant, receives mail as part of a drop, or doesn't have an established delivery yet. True, False, or null when not looked up.
isVacant	String(5)	Vacancy indicator. True, False, or null when not looked up.
isDefault	String(5)	True when this matched a building default record — a finer assignment would be possible with more input (usually a unit number).
suiteLinkResult	String(7)	SuiteLink lookup result. Match — secondary information was found via the company name and assigned to this record NoMatch — attempted, no matching record empty — not attempted
lacsLinkReturnCode	String(2)	LACSLink match status (rural-style addresses converted to city-style). A — match — converted address provided in the address fields 00 — no match, no converted address 09 — matched to a high-rise default old address; no new address provided 14 — record found but couldn't convert to a deliverable address 92 — matched after dropping the input secondary number blank — not attempted
countyName	String(25)	Fully-spelled county name.
countyCode	String(3)	FIPS three-digit county code; unique within a state.
carrierRoute	String(4)	Four-digit carrier route.
deliveryPointBarCode	String(2)	Two-digit delivery point.
deliveryPointBarCodeCheckDigit	String(1)	Check digit for the delivery-point barcode (or the five-digit barcode when a full ZIP+4 couldn't be assigned).
lineOfTravel	String(4)	Line-of-travel number.
lineOfTravelOrder	String(1)	Line-of-travel sortation: A ascending, D descending.
rdi	String(11)	Residential Delivery Indicator: Commercial, Residential, or Unknown.
rawDetailCode	String(6)	Raw processing code holding either the status code or error code — positional, one character per aspect of the cleanse. See detail codes.

geoCode

Where the address is, and how precisely it could be placed.

Field	Type	Description
assignmentLevel	String(3)	Level to which the location was matched. PRE — Primary Range Exact — the exact location of the address PRI — Primary Range Interpolated — the address range L1–L4 — locality level — city, town, or suburb P1 — Postcode1 level P2P — full Postcode1 plus partial Postcode2 PF — full postcode when available
latitude	String(17)	Latitude at the best assigned level, in the format 45.32861.
longitude	String(17)	Longitude at the best assigned level, in the format 123.45833.
censusTractBlock	String(11)	Census tract and block — small, relatively permanent statistical subdivisions of a county.
metroStatAreaCode	String(4)	Metropolitan Statistical Area (MSA) code.

Status values

The top-level status field is the one to branch on.

Status	Description
Confirmed	USPS confirms every part of the address. It's real and deliverable.
ConfirmedPrimaryUnavailableSecondary	The street address is confirmed, but USPS couldn't verify the unit or suite.
ConfirmedPrimaryInvalidSecondary	The street address is confirmed, but the unit or suite doesn't match USPS records.
Invalid	No USPS match as entered — statusMessage explains why, and the error code appears in rawDetailCode.
NotAttempted	The address couldn't be checked against USPS records.

Detail codes

rawDetailCode is a six-character positional code describing exactly what the cleanse changed. In S90100, the S means nothing was truncated, the 9 means a different ZIP Code and ZIP+4 were assigned, and the 1 means a different unit description was assigned. When the status is Invalid, this field carries an error code instead.

1st character — Truncation

S — no truncation occurred
A — truncated the address line to fit your field
C — truncated the city to fit your field
B — truncated both the address line and the city

2nd character — City, state, ZIP Code, ZIP+4

0 — no significant difference
1 — assigned a different ZIP Code
2 — assigned a different city
3 — assigned a different city and ZIP Code
4 — assigned a different state
5 — assigned a different state and ZIP Code
6 — assigned a different city and state
7 — assigned a different city, state, and ZIP Code
8 — assigned a different ZIP+4
9 — assigned a different ZIP Code and ZIP+4
A — assigned a different city and ZIP+4
B — assigned a different city, ZIP Code, and ZIP+4
C — assigned a different state and ZIP+4
D — assigned a different state, ZIP Code, and ZIP+4
E — assigned a different city, state, and ZIP+4
F — assigned a different city, state, ZIP Code, and ZIP+4

3rd character — Street name, prefix/postfix, street type

0 — no significant difference
1 — assigned a different street type
2 — assigned a different prefix
3 — assigned a different prefix and street type
4 — assigned a different postfix
5 — assigned a different street type and postfix
6 — assigned a different prefix and postfix
7 — assigned a different prefix, street type, and postfix
8 — assigned a different street name
9 — assigned a different street name and street type
A — assigned a different prefix and street name
B — assigned a different prefix, street name, and street type
C — assigned a different street name and postfix
D — assigned a different street name, street type, and postfix
E — assigned a different prefix, street name, and postfix
F — assigned a different prefix, street name, postfix, and street type

4th character — County, sort code route, delivery point, unit description

0 — no significant difference
1 — assigned a different unit description
2 — assigned a different delivery point
3 — assigned a different delivery point and unit description
4 — assigned a different sort code route
5 — assigned a different sort code route and unit description
6 — assigned a different sort code route and delivery point
7 — assigned a different sort code route, delivery point, and unit description
8 — assigned a different county number
9 — assigned a different county number and unit description
A — assigned a different county number and delivery point
B — assigned a different county number, delivery point, and unit description
C — assigned a different county number and sort code route
D — assigned a different county number, sort code route, and unit description
E — assigned a different county number, sort code route, and delivery point
F — assigned a different county number, sort code route, delivery point, and unit description

5th character — Line of travel

0 — no significant difference
1 — assigned a different LOT
2 — assigned a different LOT order
3 — assigned a different LOT and LOT order

6th character — Reserved

0 — always zero

Error codes

When an address can't be cleansed, the error code lands in rawDetailCode and the plain-English version in statusMessage.

Code	Description
E101	Last line is bad or missing.
E212	No locality and bad postal code.
E213	Bad locality, valid region, and no postal code.
E214	Bad locality and bad postal code.
E216	Bad postal code and can't determine which locality match to select.
E302	No primary address line parsed.
E412	Primary name not found in directory.
E413	Possible primary name matches are too close to choose one.
E420	Primary range is missing.
E421	Primary range is invalid for the street, route, or building.
E422	Primary prefix needed; input is wrong or missing.
E423	Primary type needed; input is wrong or missing.
E425	Primary type and directional needed; input is wrong or missing.
E427	Primary postfix needed; input is wrong or missing.
E428	Bad postal code; can't select an address match.
E429	Bad locality; can't select an address match.
E430	Possible address-line matches too close to choose one.
E431	Locality2 needed; input is wrong or missing.
E439	Exact match made in the EWS (early warning) directory.
E500	Other error.
E501	Foreign address.
E502	Input record entirely blank.
E503	Postal code not in the area covered by the partial USPS directory.
E504	Overlapping ranges in the USPS directory.
E505	Address does not exist in the USPS directories. Undeliverable address.
E600	Marked by USPS as unsuitable for delivery of mail.
E601	The primary address number did not DPV confirm, and the ZIP+4 was removed.

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

Every plan includes the full response you see above — and one subscription covers all three address services: Canadian Address Cleanse and ZIP Code Information share the same API key and monthly pool of lookups. Sign up takes a couple of minutes and keys work immediately — start free, move up when your volume does.

Free

250 lookups per month

Hard limit of 250 lookups per month — perfect for evaluating.

$30/mo

1,000 lookups per month

$0.03 per lookup above 1,000 in a month.

$100/mo

10,000 lookups per month

$0.01 per lookup above 10,000 in a month.

$400/mo

50,000 lookups per month

$0.008 per lookup above 50,000 in a month.

$600/mo

100,000 lookups per month

$0.006 per lookup above 100,000 in a month.

$1,250/mo

250,000 lookups per month

$0.005 per lookup above 250,000 in a month.

Above 250,000 lookups a month, or if you'd rather be invoiced, talk to us — we'll set up a plan that fits. Sign-up and key management currently live on our developer portal; your key comes by email right after you register.

Integrating address validation?

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

Send Us a Note 678-987-4600