jQuery Plugin

Our jQuery RAPID plugin offers the same services that our RAPID API offers, Address Cleanse, GeoCode Location, Canadian Address Cleanse and ZIP Code Information. With just a couple of minutes and a few lines javascript, you can start validating your address forms.

Setup

Create an account and get your API Key
Include a link to jQuery 1.10.2 or newer and JSONP
Include a link to the RAPID Plug-in
Call the Rapid plug-in from your Javascript.

Address Validation

When submitting your form, call the RAPID Address Validation plugin from your Javascript. Validation is asynchronous, when processing is complete, one of 3 callback functions (ValidAddressCallback, InvalidAddressCallback, ErrorCallback) is called. The callback functions allows your application to determine how submission should be handled based upon the specific callback.

When Address Validation is called, it will look for address fields with commonly used names. If your form is using these commonly used field names, all you need to pass in to plugin is the API Key and the callback functions. The validation will confirm the address and update the address form if needed.

Usage

1. Include jQuery, JSONP and Rapid jQuery plug-in

<script type="text/javascript" src="scripts/jquery-1.10.2.min.js"></script>
<script type="text/javascript" src="scripts/jquery.jsonp.js"></script>
<script type="text/javascript" src="scripts/jquery.peachtree-data.rapid.js"></script>

2. Setup form to call validation on submit.

<form>
... form fields ...
<input type="submit" onclick="validateAddress()">
</form>
...
<script>
// addressCleanseResponse will be one of two response types..
//
// Canadian Address Response (details)
// US Address Response (details)
//
   function validAddress(addressCleanseResponse) {
      // Submit form, or allow user to verify changes
   }
   function invalidAddress(addressCleanseResponse) {
      // Submit form, or alert the user that the address is invalid
   }
	
   function onError() {
      // Handle error.
   }
	
   
   function validateAddress() {
      // if standard address form, use this method...
      $().rapidAddressValidation(
            { apikey: '11111111111111111' },  // Options (see all options below)
            validAddress,                     // Valid Address Callback
            invalidAddress,                   // Invalid Address Callback
            onError);                         // Error Callback
      // if non-standard address form (multiple lines of free form text), use this method
      $().rapidMultiLineAddressValidation(
            { apikey: '11111111111111111',      // Options (see all options below)
              isCanadianAddress: false },
              validAddress,                     // Valid Address Callback
              invalidAddress,                   // Invalid Address Callback
              onError);                         // Error Callback
   }
</script>

RapidAddressValidation Options

Option	Required	Default	Description
apikey	Yes	null	API Key for your account.
companyName	No	See List	ID of the form field that contains the Company Name.
address1	No	See List	ID of the form field that contains the primary address.
address2	No	See List	ID of the form field that contains the secondary address.
city	No	See List	ID of the form field that contains the city.
state	No	See List	ID of the form field that contains the state/province.
zipCode	No	See List	ID of the form field that contains the ZIP/Postal code.
lastLine	No	See List	ID of the form field that contains the city/state/zip fields.
country	No	See List	ID of the form field that contains the country. If the country field is not available in the form, the address is assumed to be a US address.
autoCorrectAddress	No	True	Update the address form with changes from the validation response.
debug	No	False	If set, debug information is writting to the console. Intended for developers to debug issues.

RapidAddressValidation Default Field List

The RAPID plug-in will use a list of common IDs to locate address fields when custom IDs are not passed in with the option collection. Below is the list of IDs that are used for each field. If a field is not found, then that address component is considered not there and is not included as part of address processing and can't be corrected.

Field	ID List
companyName	company-name, companyName, businessName, name
address1	street, address, addr, address1, address-1, address_1, addr1, primary, primary-address, primary_address, addressLine1, address-line1, address_line1, primary
address2	suite, secondary, apartment, secondaryAddress, secondary-address, seconday_address, address2, addressLine2
city	city, town, cityname, city-name, city_name, village
state	state, province, region, territory
zipCode	zip, zipcode, zip-code, zip_code, postal, postalcode, postal-code, postal_code, postcode, post-code, post_code
lastLine	lastLine, last-line, last_line, citystatezip, city-state-zip, city_state_zip
country	country, nation

RapidMultiLineAddressValidation Options

Option	Required	Default	Description
apikey	Yes	null	API Key for your account.
line1	No	See List	ID of the form field that contains the address line1.
line2	No	See List	ID of the form field that contains the address line2.
line3	No	See List	ID of the form field that contains the address line3.
line4	No	See List	ID of the form field that contains the address line4.
line5	No	See List	ID of the form field that contains the address line5.
line6	No	See List	ID of the form field that contains the address line6.
line7	No	See List	ID of the form field that contains the address line7.
line8	No	See List	ID of the form field that contains the address line8.
isCanadianAddress	No	False	Process address as Canadian, otherwise process as US.
debug	No	False	If set, debug information is writting to the console. Intended for developers to debug issues.

RapidMultiLineAddressValidation Default Field List

Field	ID List
line1	address1, address-1, address_1, addr1, addr-1, addr_1, line1, line-1, line_1
line2	address2, address-2, address_2, addr2, addr-2, addr_2, line2, line-2, line_2
line3	address3, address-3, address_3, addr3, addr-3, addr_3, line3, line-3, line_3
line4	address4, address-4, address_4, addr4, addr-4, addr_4, line4, line-4, line_4
line5	address5, address-5, address_5, addr5, addr-5, addr_5, line5, line-5, line_5
line6	address6, address-6, address_6, addr6, addr-6, addr_6, line6, line-6, line_6
line7	address7, address-7, address_7, addr7, addr-7, addr_7, line7, line-7, line_7
line8	address8, address-8, address_8, addr8, addr-8, addr_8, line8, line-8, line_8

ZIP Code Auto-Complete

ZIP Code Auto-Complete is a plug-in that binds to a ZIP Code form field. As the ZIP Code is typed in, the plug-in will lookup the city and state, along with other information, when a valid 5 digit ZIP code is entered. After processing the ZIP code, the city and state are automatically updated. If you need access to other fields, supply a callback function to get access to fields such as Latitude and Longitude.

Usage

1. Include jQuery, JSONP and Rapid jQuery plug-in

<script type="text/javascript" src="scripts/jquery-1.10.2.min.js"></script>
<script type="text/javascript" src="scripts/jquery.jsonp.js"></script>
<script type="text/javascript" src="scripts/jquery.peachtree-data.rapid.js"></script>

2. Setup plug-in. This will bind the lookup to the ZIP Code field's onKeyPress event.

<form>
<label id="message"></label>
... form fields with city, state and ZIP Code ...
</form>
...
<script>
 
   $(document).ready(function () {
      // Use this if you want to update city/state.
      $().rapidZipCodeAutoComplete({ apikey: '11111111111', errorMsg: 'message'});

      // Use this if you want to update city/state and need the raw response
      $().rapidZipCodeAutoComplete({ apikey: '11111111111', errorMsg: 'message'}, validZipCodeCallback);
   }

   // Only needed if you need access to the response.
   function validZipCodeCallback(zipCodeInformationResponse) {
      ... process response...    
   }
</script>

RapidZipCodeAutoComplete Options

Option	Required	Default	Description
apikey	Yes	null	API Key for your account.
city	No	See List	ID of the form field that contains the city.
state	No	See List	ID of the form field that contains the state
zipCode	No	See List	ID of the form field that contains the ZIP Code
errorMsg	No	null	ID of the form field to use to display an error. If not set, error messages are not displayed.
debug	No	False	If set, debug information is writting to the console. Intended for developers to debug issues.

RapidZipCodeAutoComplete Default Field List

Field	ID List
zipCode	zip, zipcode, zip-code, zip_code, postal, postalcode, postal-code, postal_code, postcode, post-code, post_code
city	city, town, cityname, city-name, city_name, village
state	state, province, region, territory

RAPID API

Overview

The RAPID API is a REST based web service and is available only over SSL to protect your data. Service Endpoints (SE) are how you access each service RAPID provides. Each service may have one or more Serice Endpoints, depending on the parameter options needed for that service. All API SE's can be reached by Https://Rapid.PeachtreeData.com/Api/V1/. In this documentation SE's are listed without the base URL. So the AddressCleanse service endpoint would be reached by Https://Rapid.PeachtreeData.com/Api/V1/AddressCleanse plus the SE's specific parameters.

Services

US Address Cleanse - Validates the address and returns basic postal information about the address.
US Address Cleanse w/ GeoCode - In addition to returning the information of an Address Cleanse, GeoCode information is returned, such as Latitude and Longitude.
Canadian Address Cleanse - Validates the address and returns basic postal information about the address.
Zip Code Information - Look up the perferred City, State and GeoLocation of a ZIP Code

Required Parameters

Every RAPID request must contain an API Key. These parameters are always required in the query string of the URL. It's important to note that parameters can be in any order, it's generally easier to read when they are in this format.

Syntax:

Https://Rapid.PeachtreeData.com/Api/V1/{ServiceEndPoint}?&ApiKey={ApiKey}

Response Formats

The format of the RAPID response is controlled by the request. RAPID supports both JSON and XML responses. If a format is not specified, RAPID will default to JSON. Each service syntax has an option .{format} to select what format the response should be in. Every service has the following endpoint format: {ServiceEndpoint}[.{Format}] The [] indicates the format is an optional paramenter. Using the example from above, the following will show the usage of the format option.

    No format specified, response will be JSON
    Https://Rapid.PeachtreeData.com/Api/V1/AddressCleanse?ApiKey=123456ABCDEF

    Ajax & JSONP
    Https://Rapid.PeachtreeData.com/Api/V1/AddressCleanse?ApiKey=123456ABCDEF&Callback=?
  
    JSON requested (case insensitive)
    Https://Rapid.PeachtreeData.com/Api/V1/AddressCleanse.JSON?ApiKey=123456ABCDEF

    XML requested (case insensitive)
    Https://Rapid.PeachtreeData.com/Api/V1/AddressCleanse.XML?ApiKey=123456ABCDEF

Address Cleanse

Address Cleanse can validate and standardize a US address. The response will indicate if the address is deliverable and which fields were corrected. In addition, the address is standardized, parsing the address into individual fields such as ZIP+4, county name, and address type.

https://rapid.peachtreedata.com/api/v1/addresscleanse?{Address Fields}

Address Fields

When calling the service, you can pass either a standard formatted US address or a multiline address. Requests with both standard formatted address and a multiline address will not process. Use standard formatted US Address when your address is already broken in to standard fields (ie address, city, state...). When an address is more free form and address components are not known, use the multiline format. See below for specifics of each format.

Standard US Format

Parameters	Required	Description
apikey	X	Your unique apikey.
companyname		If this is a business address, the name of the company at the address. (example: Peachtree Data)
address1		Street address portion of the address. (example: 111 Main St.)
address2		Secondary address, usually containing the suite or apartment number. (example: Suite 200)
city		The city name, do not used when LastLine is used. (example: Atlanta)
state		The state name, do not used when LastLine is used. (example: Georgia)
zipcode		The ZIP Code, do not used when LastLine is used. (example: 30301)
lastline		Use this when the city, state and zip are on one line. (example: Atlanta, Georgia 30301)
requestId		An identifier used by the caller that is passed back in the response.

NOTE: Addresses must contain City/State, City/State/ZIP Code, ZIP Code or Last Line.

Multiline Format

Parameters	Required	Description
apiKey	X	Your unique apikey.
line1		First line of address
line2		Second line of address
line3		Third line of address
line4		Fourth line of address
line5		Fifth line of address
line6		Sixth line of address
line7		Seventh line of address
line8		Eigth line of address

NOTE: Multiline addresses must have at least 2 address lines.

Examples

Standard US Format Syntax (GET)

https://rapid.peachtreedata.com/api/v1/addresscleanse?apikey={apikey}&companyname=Peachtree+Data&address1=2905+Premiere&address2=Suite+200&city=Duluth&state=GA&zipcode=30097

AddressCleanse Endpoint Syntax (POST)

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

Body:

[
	{
		"companyname": "Peachtree Data",        
		"address1": "2905 Premiere",
		"address2": "Suite 200",
		"city": "Duluth",
		"state": "GA",
		"zipcode": "30097"
	},
	{
		... another address...
	}
]

Multiline Address Syntax (GET)

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

AddressCleanseMultiLine Endpoint Syntax (POST)

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

Body:

[
	{
		"line1": "Peachtree Data",
		"line2": "2905 Premiere",
		"line3": "Suite 200",
		"line4": "Duluth GA",	
		"line5" : "30097"
	},
	{
		... another address...
	}
]

Response

The response format is dependent on the request type. A GET request processes a single address and returns a single address cleanse response object. While a POST request can process multiple addresses so additional information is returned, such as Total Requests, Total Processed and Total Invalid for example. Below is an example of GET and POST responses.

Response Structure (GET Response)

{
    "status" : "",
    "statusMessage" : "",
    "requestId" : "",
    "fullAddress" : "",
    "primaryAddress" : "",
    "secondaryAddress" : "",
    "lastLine" : "",
    "components" : {                        
                      ... Component Fields ...
                   },
    "metadata" : {
                    ... Metadata Fields ...
                 },
    "geoCode" : {
                    ... GeoCode Fields ...
                }
}

POST Response

[
  {
    "totalRequests" : "2",
    "totalInvalidRequests" : "0",
    "totalError" : "0",
    "totalProcessed" : "2",
    "responses" : [
                    {
                        ...Root Level Fields...
                              ... Component Fields ...
                              ... Metadata Fields ...
                              ... GeoCode Fields ...
                    
                    },
                    {
                        ...Root Level Fields...
                              ... Component Fields ...
                              ... Metadata Fields ...
                              ... GeoCode Fields ...
                    }
                  ]
  }	
]

Root Level Fields

Field	Type	Description
addressId	String(50)	This is value is the AddressId from the request, and is unchanged by RAPID
components		See the Components table for available fields.
fullAddress	String(60)	This is a single line address, containing the primary and secondary address.
metadata		See the Metadata table for available fields.
primaryAddress	String(60)	Primary address line, such as the street address or post office box. Does not include secondary address information such as apartment.
secondaryAddress	String(60)	The building name, floor, and room number in one field.
status	String(36)	Result of the cleanse. Confirmed ConfirmedPrimaryUnavailableSecondary ConfirmedPrimaryInvalidSecondary Invalid NotAttempted
statusMessage	String	If the status is Invalid or NotAttempted, this holds the descriptive message.

Component Fields

Field	Type	Description
city	String(28)	City preferred by the postal authority.
city13	String(13)	Abbreviated city preferred by the postal authority.
extraLine1	String(60)	Any non-address data found above or below the address data in the address. Available only if the input data is presented through multiline fields.
extraLine2	String(60)	Any non-address data found above or below the address data in the address. Available only if the input data is presented through multiline fields.
nonPostalSecondaryAddress	String(20)	The complete non-postal secondary address (for example, "PMB 10" or "#10"). Non-postal means that the mail is delivered through a private mailbox company rather than the USPS.
primaryAddressRemainder	String(40)	Extraneous data found on the address line that cannot be identified as address data or does not belong in the standardized address line. This may include invalid secondary address information.
primaryNumber	String(10)	The premise number.
primaryPrefix	String(2)	An abbreviated directional (such as N, S, NW, or SE) that precedes a street name.
primaryName	String(28)	Street name description
primaryType	String(4)	Abbreviated street type (for example, St, Ave, or Pl).
primaryPostfix	String(2)	An abbreviated directional (such as N, S, NW, or SE) that follows a street name.
secondaryAddressExtraneous	String(28)	Consists of the extraneous data from the secondary address. This may include invalid secondary address data.
secondaryUnitDescription	String(8)	Unit description (for example, #, Apartment, or Flat).
secondaryUnitNumber	String(8)	Unit number (for example, 100 in "APT 100").
state	String(2)	State abbreviation
zip10	String(10)	The five-digit ZIP Code with the ZIP + 4 (for example 11111-2222)
zip5	String(5)	The five-digit ZIP Code. Does not include the ZIP + 4.
zip4	String(4)	Four digit ZIP + 4.

Metadata Fields

Field	Type	Description
addressType	String(15)	Type of address: Firm GeneralDelivery HighRise Military PoBox CMRA - Commercial Mailing Receiving Agency (for example Mailbox Etc) RuralRoute Street Unique NoMatch
carrierRoute	String(4)	The four-digit carrier route.
countyCode	String(3)	Federal Information Processing Standard (FIPS) three-digit county code. Numbers are unique within states.
countyName	String(25)	The fully-spelled county name.
deliveryPointBarCode	String(2)	The two-digit delivery point barcode
deliveryPointBarCodeCheckDigit	String(1)	Check digit for the delivery-point bar code, or for a five-digit bar code if a full postal code (ZIP+4) could not be assigned.
dpvFootnote	String(12)	Delivery Point Validation (DPV) footnotes, up to 6 footnotes. DPV Footnotes are always in the same order, but not always 12 characters in length AA - The input address matches to the ZIP+4 file. A1 - The input address does not match to the ZIP+4 file. BB - All input address field values match to DPV. CC - The input address primary number matches to DPV, but the secondary number does not match (the secondary is present but invalid). C1 - The input address primary number matches DPV file but secondary number required. F1 - The input address matches to a military address. G1 - The input address matches a general delivery address. IA - The input address identified as an informed address. M1 - The input address primary number is missing. M3 - The input address primary number is invalid. N1 - The input address primary number matches to DPV but the address is missing the secondary number. NL - An NCOALink move address cannot be DPV confirmed. PB - The input address matches PBSA (PO Box as standard address). P1 - The input address is missing the rural route or highway contract box number. P3 - The input address is an invalid post office, rural route, or highway contract number. RR - The input address matches to CMRA. R1 - The input address matches to CMRA, but the secondary number is not present. R7 - The input address matches phantom route. TA - The input address primary number matched by dropping the trailing alpha. U1 - The input address matches a unique address.
dpvStatus	String(1)	The DPV status component that is generated for this record. D - The primary range is a confirmed delivery point, but the secondary range is not available on input. L - The address triggered DPV locking. N - The address is not a valid delivery point. S - The primary range is a valid delivery point, but the parsed secondary range is not valid in the DPV directory. Y - The address is a confirmed delivery point. The primary range and secondary range (if present) are valid. blank - A blank output value indicates that Enable_DPV_Validation is set to No, DPV processing is currently locked, or the transform cannot assign the input address.
isDpvNoStat	String(5)	No Stat indicator. No Stat means that the address is a vacant property, it receives mail as a part of a drop, or it does not have an established delivery yet. True - The address is flagged as No Stat in DPV data. False - The address is not No Stat. null - The address was not looked up.
isDefault	String(5)	True - default address, and that a finer level of address assignment would be possible if further input information were available. False - Not a default address
isVacant	String(5)	Vacant address indicator True - The address is vacant. False - The address is not vacant. null - The address was not looked up.
lacsLinkReturnCode	String(2)	Returns the match status for LACSLink processing A - LACSLink record match. A converted address is provided in the address data fields. 00 - No match and no converted address. 09 - LACSLink matched an input address to an old address, which is a "high-rise default" address; no new address is provided. 14 - Found a LACSLink record, but couldn't convert the data to a deliverable address. 92 - LACSLink record matched after dropping the secondary number from input address. Blank - Not attempted.
lineOfTravel	String(4)	Line-of-travel number.
lineOfTravelOrder	String(1)	Line-of-travel sortation. A - Ascending. D - Descending.
rawDetailCode	String(6)	This is the Raw processing code, containing either the Status Code or Error Code.
rdi	String(11)	Residential Delivery Indicator (RDI), determine if address is residential. Possible Values Commercial Residential Unknown
suiteLinkResult	String(7)	SuiteLink lookup result Match - Secondary information exists and was assigned to this record as a result of SuiteLink processing. NoMatch - Lookup was attempted but no matching record was found. empty - Not attempted.

GeoCode Fields

Field	Type	Description
assignmentLevel	String(3)	Level to which the processing matches the address. PRE - Primary Range Exact assigns to the exact location of the address. PRI - Primary Range Interpolated assigns to the level of the address range L1–4 - Locality1–4 assigns to the level of city, town, or suburb. P1 - Postcode1 assigns to the level of Postcode1. P2P - Postcode2 Partial assigns the full Postcode1 and the first few characters of Postcode2. PF - Postcode Full assigns to the level of Postcode1 and Postcode2, when available.
censusTractBlock	String(11)	The census tract code as defined by the government for reporting census information. Census tracts are small, relatively permanent statistical subdivisions of a county.
latitude	String(17)	The latitude at the best assigned level (0–90 degrees north or south of the equator) in the format 45.32861.
longitude	String(17)	The longitude at the best assigned level (0–180 degrees east or west of Greenwich meridian) in the format 123.45833.
metroStatAreaCode	String(4)	The metropolitan statistical area. For example, in the USA, the 0000 code indicates the address does not lie in a metropolitan statistical area; usually a rural area. A metropolitan statistical area has a large population that has a high degree of social and economic integration with the core of the area. The area is defined by the government for reporting census information.

US Address Cleanse Demo

Company Name

Address

City

State

ZIPCode

Response Details

Canadian Address Cleanse

Address Cleanse can validate and standardize a Canadian address. The response will indicate if the address is deliverable and which fields were corrected. In addition, the address is standardized, parsing the address into individual fields such as FSA portion of the postal code.

https://rapid.peachtreedata.com/api/v1/canadianaddresscleanse?{Address Fields}

Address Fields

When calling the service, you can pass either a standard formatted Canadian address or a multiline address. Requests with both standard formatted address and a multiline address will not process. Use standard formatted address when your address is already broken in to standard fields (ie address, city, province...). When an address is more free form and address components are not known, use the multiline format. See below for specifics of each format.

Standard Canadian Format

Parameter	Required	Description
apikey	X	Your API Key.
address1		Street address portion of the address. (example: 111 Main St.)
address2		Secondary address, usually containing the suite or apartment number. (example: Suite 200)
city		The city name, do not use when LastLine is used. (example: Port Hope)
province		The province, do not use when LastLine is used. (example: ON)
postalcode		The postal code, do not use when LastLine is used. (example: L1A 3G3)
lastline		Used when City, Province and Postal Code are not seperate fields. (example: Port Hope, ON L1A 3G3)

Multiline Format

Parameters	Required	Description
apikey	X	Your unique apikey.
line1		First line of address
line2		Second line of address
line3		Third line of address
line4		Fourth line of address
line5		Fifth line of address
line6		Sixth line of address
line7		Seventh line of address
line8		Eigth line of address

Examples

Standard Canadian Format Syntax (GET)

https://rapid.peachtreedata.com/api/v1/canadianaddresscleanse?apikey={ApiKey}&address1=111+Main+St&city=Port+Hope&province=ON&postalcode=L1A+3G3

Standard Canadian Format Syntax (POST)

https://rapid.peachtreedata.com/api/v1/canadianaddresscleanse?apikey={ApiKey}
Content-type: application/json

Body:

[
	{
		"address1": "111 Main St",
		"city": "Port Hope",
		"province": "ON",
		"postalCode": "L1A 3G3"
	},
	{
		... another address...
	}
]

Multiline Address Syntax (GET)

https://rapid.peachtreedata.com/api/v1/canadianaddresscleanse?apikey={ApiKey}&line1=111+Main+St&line2=Port+Hope%2C+ON+L1A+3G3

Multiline Address Syntax (POST)

https://rapid.peachtreedata.com/api/v1/canadianaddresscleanse?apikey={ApiKey}
Content-type: application/json

Body:

[
	{
		"line1": "111 Main St",
		"line2": "Port Hope, ON L1A 3G3"
	},
	{
		... another address...
	}
]

Response

The response format is dependent on the request type. A GET request processes a single address and returns a single Canadian address cleanse response object. While a POST request can process multiple addresses so additional information is returned, such as Total Requests, Total Processed and Total Invalid for example. Below is an example of GET and POST responses.

Response Structure (GET Response)

 {
   "status" : "",
   "statusMessage" : "",
   "rawDetailCode" : "",
   "requestId" : "",
   "fullAddress" : "",
   "primaryAddress" : "",
   "secondaryAddress" : "",
   "lastLine" : "",
   "components" : {
                     ... Component Fields ...
                  },
   "metadata" : {
                   ... Metadata Fields ...
                }
}

POST Response

[
  {
    "totalRequests" : "2",
    "totalInvalidRequests" : "0",
    "totalError" : "0",
    "totalProcessed" : "2",
    "responses" : [
                    { 
                       ... Root level Fields ...
                          ... Component Fields ...
                          ... Metadata Fields ... 
                    },
                    {
                        ... Root level Fields ...
                          ... Component Fields ...
                          ... Metadata Fields ... 
                    }
                  ]
  }	
]

Canadian Address Cleanse Root Fields

Field	Type	Description
fullAddress	String(256)	This is a single line address, containing the primary and secondary address.
lastLine	String(176)	City, Province and Postal Code
requestId	String(50)	This is value is the RequestId from the request, and is unchanged by RAPID.
primaryAddress	String(256)	Primary address line, such as the street address or post office box. Does not include secondary address information such as apartment.
secondaryAddress	String(64)	The building name, floor, and room number in one field.
status	String(36)	Result of the cleanse. Valid Invalid
statusMessage	String	If the status is Invalid, this holds the descriptive message.

Component Fields

Field	Type	Description
city	String(128)	City preferred by the postal authority.
city13	String(13)	Abbreviated city preferred by the postal authority.
extraLine1	String(128)	Any non-address data found above or below the address data in the address. Available only if the input data is presented through multiline fields.
extraLine2	String(128)	Any non-address data found above or below the address data in the address. Available only if the input data is presented through multiline fields.
postalCode	String(20)	Full postal code, containing the LDU and FSA
postalCodeFsa	String(10)	The FSA portion of the postal code.
postalCodeLdu	String(5)	The LDU portion of the postal code.
primaryName	String(128)	Street name description
primaryNumber	String(64)	The premise number.
primaryPrefix	String(40)	An abbreviated directional (such as N, S, NW, or SE) that precedes a street name.
primaryPostfix	String(40)	An abbreviated directional (such as N, S, NW, or SE) that follows a street name.
primaryType	String(40)	Abbreviated street type (for example, St, Ave, or Pl).
province	String(128)	Province abbreviation
remainderFull	String(256)	Contains all remainder information in one field.
secondaryUnitDescription	String(20)	Unit description (for example, #, Apartment, or Flat).
secondaryUnitNumber	String(12)	Unit number (for example, 100 in "APT 100").

Metadata Fields

Field	Type	Description
addressType	String(25)	Type of address: BuildingName Firm GeneralDelivery HighRise Military Rural Postal Street StreetServedByRoute Unknown
deliveryInstallationName	String(30)	The delivery installation city name, which is usually the same as the city name and (if it is the same) omitted from the address line. If the delivery installation name is different than the locality name, the delivery installation name is output to the secondary address fields.
deliveryInstallationType	String(30)	The delivery installation type: PostOffice RetailPostOutlet Station LetterCarrierDepot CommunityMailCenter CommercialDealershipOutlet
qualityCode	String(2)	Displays a two-character code that provides additional information about the quality of the address. Q1 - Perfect address on input. All address components were validated without corrections. Q2 - Corrected address. All address components were validated after corrections were made. Q3 - Not all components of the address could be fully validated. There was insufficient information to make a final correction. However, the assessment of the record leads to the assumption that there is a "high" likelihood that this address is deliverable. Q4 - Not all components of the address could be fully validated. There was insufficient information to make a final correction. However, the assessment of the record leads to the assumption that there is a "fair" likelihood that this address is deliverable. Q5 - Not all components of the address could be fully validated. There was insufficient information to make a final correction. However, the assessment of the record leads to the assumption that there is a "small" likelihood that this address is deliverable. Q6 - Not all components of the address could be fully validated. There was insufficient information to make a final correction. However, the assessment of the record leads to the assumption that it is "highly unlikely" that this address is deliverable.

Canadian Address Cleanse Demo

Address

City

Province

Postal Code

Response Details

Zip Code Information

The ZIP Code information service provides a way get get basic information about a ZIP Code. This service is useful in populating City and State. Additionally, you can get the Latitude and Longitude for a ZIP Code.

Service Endpoint	Purpose
ZipCodeInformation	Used for single ZIP Code

Parameters

Parameters	Required	Description
ApiKey	X	Your unique apikey.
ZipCode	X	The ZIP Code to lookup. (example: 30097)

Examples

Syntax (GET)

https://Rapid.PeachtreeData.com/Api/V1/ZipCodeInformation?ApiKey={ApiKey}&ZipCod=30097

Response

Field	Type	Description
Status	String(8)	Result of lookup: Found NotFound
ZipCode	String(5)	5 Digit ZipCode
City	String(28)	Preferred city for the ZIP Code
City13	String(13)	13 Character short name for the city.
State	String(2)	2 Letter abbreviation for the state / US territory
Latitude	String(9)	Latitude for the geographic center of the ZIP Code, ex: 34.020208
Longitude	String(10)	Longitude for the geographic center of the ZIP Code, ex: -84.144343

ZIPCode Information Demo

Enter a Zip Code and the City/State are automatically filled.

ZIPCode

City

State

Available Fields

Do Not Call

The Do Not Call Service provides a way to determine if a phone number is listed on the Federal, State or Direct Marketing do not call lists.

Service Endpoint	Purpose
DoNotCall	Used for single or batch processing of phone numbers.

Parameters

Parameters	Required	Description
ApiKey	X	Your unique apikey.
PhoneNumber	X	Phone to look up (example: 678-987-4600)
RequestId		An ID passed in the request to associate the original phone number string to the corresponding response.

A phone number can be alphanumeric. When we process the phone number string, we will take the first 10 digits and process that as the phone number. This allows for multiple phone number formats plus accomidates for extensions in a phone number string. If 10 digits are not present, it will be considered invalid and not process or billed. To determine what number was processed in the request, check out the phone number field in the response.

Examples

Do Not Call (GET)

https://rapid.peachtreedata.com/api/v1/donotcall?apikey={apikey}&phonenumber=(678)+987-4600
https://rapid.peachtreedata.com/api/v1/donotcall?apikey={apikey}&phonenumber=555.555.4600+Ext+200

Do Not Call (POST)

https://rapid.peachtreedata.com/api/v1/donotcall?apikey={apikey}
Content-type: application/json

Body:

[
	{
		"phoneNumber": "(687) 987-4600",
		"requestId": "00001",
	},
	{
		... another request...
	}
]

Response

The response format is dependent on the request type. A GET request processes a single phone number and returns a single DNC Response object. While a POST request can process multiple phone numbers so additional information is returned, such as Total Requests, Total Processed and Total Invalid for example. Below is an example of GET and POST responses.

GET Response

                        
{
  "status" : "Success",
  "phoneNumber" : "6789874600",
  "requestId" : "0001",
  "dmaDnc" : "False",
  "stateDnc" : "GA",
  "federalDnc" : "False",
  "dncMatch" : "True",
  "dmaDnc" : "False"                         
}

POST Response

[
  {
    "totalRequests" : "2",
    "totalInvalidRequests" : "0",
    "totalError" : "0",
    "totalProcessed" : "2",
    "responses" : [
                    {
                      "status" : "Success",
                      "phoneNumber" : "6789874600",
                      "requestId" : "0001",
                      "dmaDnc" : "False",
                      "stateDnc" : "GA",
                      "federalDnc" : "False",
                      "dncMatch" : "True"
                    },
                    { ... another DNC Response ... }
                  ]
	
]

Do Not Call Response

Field	Type	Description
dmaDnc	Boolean	True if the phone number is on the Direct Mailing Association's Do Not Call list.
dncMatch	Boolean	True if the phone number is on any Do Not Call list.
federalDnc	Boolean	True if the phone numer is on the Federal Do Not Call list.
phoneNumber	String(10)	10 Digit phone number used in DNC lookup. The first 10 digits in the phone number string are used. If the phone number string contains less than digits, the phone number field will also be less than 10 digits.
requestID	String(50)	Request ID supplied in request to allow the result to be matched to the request. This is important when POST'ing several phone numbers, since response order is not guaranteed to be in the same order of the request.
stateDnc	String(2)	2 Letter abbreviation for the state where the phone number is listed on the state Do Not Call list. If the phone number is not on a state Do Not Call list, then this value will be empty.
status	String(7)	Result of lookup: Success - Phone number DNC lookup completed. Invalid - Phone number is not 10 digits. Error - Error processing phone number.

Reverse Phone Append

The Reverse Phone Append Service provides a way to determine an address from a phone number.

Service Endpoint	Purpose
ReversePhoneAppend	Used for single or batch processing of phone numbers.

Parameters

Parameters	Required	Description
ApiKey	X	Your unique apikey.
PhoneNumber	X	Phone to look up (example: 678-987-4600)
RequestId		An ID passed in the request to associate the original phone number string to the corresponding response.

Examples

Reverse Phone Append (GET)

https://rapid.peachtreedata.com/api/v1/reversephoneappend?apikey={apikey}&phonenumber=(678)+987-4600

Reverse Phone Append (POST)

https://rapid.peachtreedata.com/api/v1/reversephoneappend?apikey={apikey}
Content-type: application/json

Body:

[
	{
		"phoneNumber": "(687) 987-4600",
		"requestId": "00001",
	},
	{
		... another request...
	}
]

Response

The response format is dependent on the request type. A GET request processes a single phone number and returns a single Reverse Phone Append Response object. While a POST request can process multiple phone numbers so additional information is returned, such as Total Requests, Total Processed and Total Invalid for example. Below is an example of GET and POST responses.

GET Response

                        
{
  "firstName" : "",
  "middleName" : "",
  "lastName" : "",
  "businessName" : "PEACHTREE DATA"
  "address1" : "2905 PREMIERE PKWY STE 200",
  "address2" : "",
  "city" : "DULUTH",
  "state" : "GA",
  "zipCode" : "30097-5275",
  "phoneNumber" : "6789874600",
  "status" : "Match",
  "statusMessage" : null,
  "requestId" : "0001",
}

POST Response

[
  {
    "totalRequests" : "2",
    "totalInvalidRequests" : "0",
    "totalError" : "0",
    "totalProcessed" : "2",
    "responses" : [
                    {
			"firstName" : "",
			"middleName" : "",
			"lastName" : "",
			"businessName" : "PEACHTREE DATA"
			"address1" : "2905 PREMIERE PKWY STE 200",
			"address2" : "",
			"city" : "DULUTH",
			"state" : "GA",
			"zipCode" : "30097-5275",
			"phoneNumber" : "6789874600",
			"status" : "Match",
			"statusMessage" : null,
			"requestId" : "0001",
		    },
                    { ... another Reverse Phone Append response ... }
                  ]
	
]

Reverse Phone Append Response

Field	Type	Description
address1	String(60)	Primary address associated with the phone number.
address2	String(60)	Secondary address associated with the phone number.
city	String(28)	City associated with the phone number.
state	String(2)	State abbreviation associated with the phone number.
zipCode	String(10)	10 digit ZIPCode (ex. 12345-1234) associated with the phone number.
firstName	String(60)	First name of the person associated with the phone number.
middleName	String(60)	Middle name of the person associated with the phone number.
lastName	String(60)	Last name of the person associated with the phone number.
businessName	String(60)	Name of the business associated with the phone number.
phoneNumber	String(10)	10 digit phone number actually processed.
status	String(7)	Result of lookup: Match - Phone number found. NoMatch - Phone number not found. Error - Error processing phone number.
statusMessage	String(2)	If status is Error, this will hold the description.
requestId	String(2)	Request ID supplied in request to allow the result to be matched to the request. This is important when POST'ing several phone numbers, since response order is not guaranteed to be in the same order of the request.

Phone Append

The Residential Phone Append service provides a way to determine a landline phone number based on first name, last name, and address.

Phone Append Fields

Parameter	Required	Description
apikey	X	Your unique apikey.
firstName¹		The first name of the individual to query.
lastName	X	The last name of the individual or household to query.
address1	X	Street address portion of the address. (example: 111 Main St.)
address2		Secondary address, usually containing the suite or apartment number. (example: Suite 200)
city²	X	The city name. (example: Atlanta)
state²	X	The state name or abbreviation. (example: Georgia or GA)
zip²	X	The ZIP Code. (example: 30301)
requestId		An identifier used by the caller that is passed back in the response.
matchType		I for (I)ndividual matches and H, or omitted, for (H)ousehold matches.

¹ First name is required if the individual option is used for matchType.
² Addresses must contain City and State or ZIP Code.

Example

Residential Phone Append

http://rapid.peachtreedata.com/api/v1/ResidentialPhoneAppend?apikey={ApiKey}&firstName=John&lastName=Doe&address1=111 Main St&address2=&city=&state=&zip=30097&requestId=222&matchType=i

Response

Matched Response

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

Non-Matched Response

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

Error Response

                        
{
    "status": "Error",
    "statusMessage": "Some description of the error.",
    "billable": false,
    "requestId": "222"
}

Phone Append Response

Field	Type	Description
confidence	String(1)	1,2, or 3 - Highly confident match. 4 - Possibility of a disconnect. 5 - Likely to be a disconnected number.
category	String(2)	I - Individual H - Household A - Address NZ - Full name and zip LZ - Last name and zip
phoneType	String(1)	L - Land line V - VoIP W - Wireless O - Other
recType	String(1)	R - Residential B - Business P - Payphone U - Unknown
telcoName	String(60)	The telephone company to which the matched phone number belongs.
phoneNumber	String(10)	10 digit phone number.
status	String(7)	Result of lookup: Match - Phone number found. NoMatch - Phone number not found. Error - Error processing request.
statusMessage	String(200)	If status is Error, this will contain the description.
billable	boolean	Whether the requested result will be a billed request. Only requests that have a matching append result are billed to the user.
requestId	String(50)	Request ID supplied in request to allow the result to be matched to the request.

Cell Phone Append

The Cell Phone Append service provides a way to determine a phone number based on first name, last name, and address.

Cell Phone Append Fields

Parameter	Required	Description
apikey	X	Your unique apikey.
firstName		The first name of the individual to query.
lastName	X	The last name of the individual or household to query.
address1	X	Street address portion of the address. (example: 111 Main St.)
address2		Secondary address, usually containing the suite or apartment number. (example: Suite 200)
city¹	X	The city name. (example: Atlanta)
state¹	X	The state name or abbreviation. (example: Georgia or GA)
zip¹	X	The ZIP Code. (example: 30301)
requestId		An identifier used by the caller that is passed back in the response.

¹ Addresses must contain City and State or ZIP Code.

Example

Cell Phone Append

http://rapid.peachtreedata.com/api/v1/CellPhoneAppend?apikey={ApiKey}&firstName=John&lastName=Doe&address1=111 Main St&address2=&city=&state=&zip=30097&requestId=222

Response

Matched Response

                        
{
    "telcoName": "",
    "phoneNumber": "6784730000",
    "status": "Match",
    "billable": true,
    "requestId": "222"
}

Non-Matched Response

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

Error Response

                        
{
    "status": "Error",
    "statusMessage": "Some description of the error.",
    "billable": false,
    "requestId": "222"
}

Cell Phone Append Response

Field	Type	Description
telcoName	String(60)	The telephone company to which the matched cell phone number belongs.
phoneNumber	String(10)	10 digit phone number.
status	String(7)	Result of lookup: Match - Phone number found. NoMatch - Phone number not found. Error - Error processing request.
statusMessage	String(200)	If status is Error, this will contain the description.
billable	boolean	Whether the requested result will be a billed request. Only requests that have a matching append result are billed to the user.
requestId	String(50)	Request ID supplied in request to allow the result to be matched to the request.

Email Validation

The Email Vaildation Service provides a way to validate email addresses, getting information on the domain and may also include suggested corrections.

Service Endpoint	Purpose
emailvalidation	Used for processing an email address.

Parameters

Parameters	Required	Description
ApiKey	X	Your unique apikey.
Email	X	Email address to validate (example: someone@acompany.com)
RequestId		An ID passed in the request to associate the original phone number string to the corresponding response.

Examples

Email Validation (GET)

https://rapid.peachtreedata.com/api/v1/emailvalidation?apikey={apikey}&email=someone@acompany.com

Response

GET Response

                        
{
  "valid": True,
  "emailAddress": "someone@acompany.com",
  "role": False,
  "status": "S45",
  "statusMessage": "Domain does not support validation (accepts all mailboxes)"
}

GET Response with Correction

                        
{
  "valid": False,
  "emailAddress": "someone@acompany.cm",
  "role": False,
  "correction": "someone@acompany.com",
  "status": "S310",
  "statusMessage": "Domain does not exist"
}

Email Validation Response

Field	Type	Description
valid	boolean	True if the e-mail address can not be confirmed as invalid, False otherwise.
emailAddress	string	Email address processed.
role	boolean	A true/false flag indicating whether the email address is a role-based account, such as sales@ or info@
correction	string	For an incorrect email address, a possible correct email address, if a correction could be made.
status	string	S5 - Timeout S10 - Syntax OK S20 - Syntax OK and domain valid according to the domain database S30 - Syntax OK and domain exists S40 - Syntax OK, domain exists, and domain can receive email S45 - Domain does not support validation (accepts all mailboxes) S50 - Syntax OK, domain exists, and mailbox does not reject mail S110 - General syntax error S110 - Invalid character in address S115 - Invalid domain syntax S120 - Invalid username syntax S125 - Invalid username syntax for that domain S130 - Address is too long S135 - Address has unbalanced parentheses, brackers, or quotes S140 - Address does not have a username S145 - Address does not have a domain S150 - Address does not have an @ sign S155 - Address has more than one @ sign S200 - Invalid top level domain (TLD) in database S210 - Comments are not allowed in email address S215 - Unquoted spaces are not allowed in email address S310 - Domain does not exist S315 - Domain does not have a valid IP address S325 - Domain cannot receive email S400 - The mailbox is invalid or the username does not exist at the domain S410 - Mailbox is full and can not receive email at this time S420 - Mail is not accepted for this domain S500 - Addresses with that username are not allowed S505 - Addresses with that domain are not allowed S510 - Address is a bot or ther suppression S512 - Address is a role-based account S520 - Address is a know bouncer S525 - Address is a spamtrap, a known complainer or is suppressed. S530 - Address has opted out from commercial email S999 - Internal error
statusMessage	string	Description of the status listed above.
requestID	string	Request ID supplied in request to allow the result to be matched to the request.

Reverse Email Append

The Reverse E-mail Append Service is used for retrieving name and address information about an individual that is known to own an e-mail address.

Service Endpoint	Purpose
reverseemailappend	Used for filling in address and name information based on an e-mail address.

Parameters

Parameters	Required	Description
ApiKey	X	Your unique apikey.
EmailAddress	X^*	The e-mail address to use in the lookup.
MD5EmailAddress	X^*	An MD5 hashed e-mail address to use in the lookup. Ensure that the MD5 hashed value was generated using a lower cased e-mail address that had all leading and trailing spaces removed.
FirstName		A known first name of the person associated with the e-mail address. Adding a known first and/or last name to the e-mail append request can help improve the match accuracy.
LastName		A known last name of the person associated with the e-mail address. Adding a known first and/or last name to the e-mail append request can help improve the match accuracy.
RequestId		An ID passed in the request to associate the original phone number string to the corresponding response.

^* Either EmailAddress or MD5EmailAddress are required but not both.

Response

Root Level Fields

Field	Type	Description
totalRequests	int	The number of e-mail addresses received in the request to be appended.
totalProcessed	int	The number of valid e-mail addresses that were processed by the append service.
totalInvalidRequests	int	The number of invalid request values that were received and not processed through the append service.
totalBillableCount	int	The number of valid appended e-mail addresses received in the request. Only valid and appended results are billed to the user.

Responses

Field	Type	Description
emailAddress	string	Email address processed.
firstName	string	Matched first name.
lastName	string	Matched last name.
address	string	Matched address.
city	string	Matched city.
state	string	Matched state.
zipCode	string	Matched zip code.
status	string	Can be one of 3 values: Valid, Invalid, or NonMatch. Only a result with a Valid status will be a charged request, all others will be ignored.
billable	bool	Whether the requested result will be a billed request. Only requests that have a matching append result are billed to the user.
requestID	string	Request ID supplied in request to allow the result to be matched to the request.

Examples

Reverse Email Append (POST)

https://rapid.peachtreedata.com/api/v1/reverseemailappend?apikey={apikey}

POST Request Body

[
	{"emailAddress":"someone1@acompany.com"},
	{"emailAddress":"someone2@acompany.com"},
	{"emailAddress":"someone3@acompany.com"},
	{"mD5EmailAddress":"754b16549d9c059ec982395f93095cfe"}
]

POST Response

{
    "totalRequests": 4,
    "totalProcessed": 4,
    "totalInvalidRequests": 0,
    "totalBillableCount": 3,
    "responses": [
        {
            "emailAddress": "someone1@acompany.com",
            "firstName": "someone1",
            "lastName": "smith",
            "address": "123 somewhere dr",
            "city": "somecity",
            "state": "ST",
            "zipCode": "12345-1234",
            "status": "Valid",
            "billable": true
        },
        {
            "emailAddress": "someone2@acompany.com",
            "status": "NonMatch",
            "billable": false
        },
        {
            "emailAddress": "someone3@acompany.com",
            "firstName": "someone3",
            "lastName": "smith",
            "address": "123 somewhere dr",
            "city": "somecity",
            "state": "ST",
            "zipCode": "12345-1234",
            "status": "Valid",
            "billable": true
        },
        {
            "emailAddress": "someone4@acompany.com",
            "firstName": "someone4",
            "lastName": "smith",
            "address": "123 somewhere dr",
            "city": "somecity",
            "state": "ST",
            "zipCode": "12345-1234",
            "status": "Valid",
            "billable": true
        }
    ]
}

Reverse Email Append (GET)

https://rapid.peachtreedata.com/api/v1/reverseemailappend?apikey={apikey}&email=someone@acompany.com

GET Response

                        
        {
            "emailAddress": "someone@acompany.com",
            "firstName": "someone",
            "lastName": "smith",
            "address": "123 somewhere dr",
            "city": "somecity",
            "state": "ST",
            "zipCode": "12345-1234",
            "status": "Valid",
            "billable": true
        }

GET NonMatch Response

                        
        {
            "emailAddress": "someone@acompany.com",
            "status": "NonMatch",
            "billable": false
        }

Demographics Append

The Demographics Append service provides for the ability to retrieve demographics about an individual based on e-mail address, name and address.

Service Endpoint	Purpose
demographicsappend	Used for retrieving demographics about an individual.

Parameters

Parameters	Required	Description
ApiKey	X	Your unique apikey.
Fields	X	The list of fields you wish to retrieve. The billing is based on the number of found fields returned in the call. This value can be one or more of the following separated by a comma. All (Use this value to return all available demographics for the individual) MaritalStatus NetWorth Occupation Education HomeMarketValue Gender LengthOfResidence HouseholdIncome HomeOwnerStatus Age PresenceOfChildren City State ZipCode
EmailAddress		A known e-mail address for the individual. If this is used in the query it may be provided on its own without any other of the individuals' information but the more parameters used in the request the more accurate the result will be. Only one of EmailAddress, EmailAddressSHA1, or EmailAddressMD5 can be provided. If more than one of these values is supplied the request will error as invalid.
EmailAddressSHA1		A known SHA-1 e-mail address for the individual. If this is used in the query it may be provided on its own without any other of the individuals' information but the more parameters used in the request the more accurate the result will be. Only one of EmailAddress, EmailAddressSHA1, or EmailAddressMD5 can be provided. If more than one of these values is supplied the request will error as invalid.
EmailAddressMD5		A known MD-5 e-mail address for the individual. If this is used in the query it may be provided on its own without any other of the individuals' information but the more parameters used in the request the more accurate the result will be. Only one of EmailAddress, EmailAddressSHA1, or EmailAddressMD5 can be provided. If more than one of these values is supplied the request will error as invalid.
FirstName		The first name of the individual. If any part of the name is provided then one or all of e-mail address, address, city, state or zip must be provided.
LastName		The last name of the individual. If any part of the name is provided then one or all of e-mail address, address, city, state or zip must be provided.
Address		The address of the individual. If the address is provided then one or all of e-mail address, first name or last name must be provided.
City		The city of the individual. If city is provided then one or all of e-mail address, first name or last name must be provided.
State		The state of the individual. If state is provided then one or all of e-mail address, first name or last name must be provided.
Zip		The zip code of the individual. If zip is provided then one or all of e-mail address, first name or last name must be provided.
RequestId		A string identifier passed in on the request that is returned unchanged in the response. Please Note: It is highly recommended to provide a value for this field for batch POST requests to ensure you can correlate the object in the response array to the correct object in the request array.

Demographics Append Response

Root Level Fields

Field	Type	Description
totalRequests	int	Total number of requests in a POST body.
totalProcessed	int	Total number of requests that were successfully processed.
totalInvalidRequests	int	Total number of requests that were invalid and not processed.
totalBillableFieldCount	int	A sum of the countOfFieldsReturned for each object in the response. This value is used for the billing when a POST request is made.

Responses

Field	Type	Description
countOfFieldsRequested	int	The number of fields listed in the requests fields property. If all is specified for fields then this value will be the max number of fields, 14.
countOfFieldsReturned	int	The number of fields found for the individual in the request or json object.
age	string	Can be one of the following values: 18-20, 21-24, 25-34, 35-44, 45-54, 55-64, 65+
gender	string	Can be one of the following values: Male, Female
education	string	Can be one of the following values: Completed High School, Attended College, Completed College, Completed Graduate School, Attended Vocational/Technical School
occupation	string	Can be one of the following values: 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	Can be one of the following values: 0-5k, 5k-10k, 10k-25k, 25k-50k, 50k-100k, 100k-250k, 250k-500k, 500k-1mm, 1mm+
householdIncome	string	Can be one of the following values: 0-15k, 15k-25k, 25k-35k, 35k-50k, 50k-75k, 75k-100k, 100k-150k, 150k-175k, 175k-200k, 200k-250k, 250k+
presenceOfChildren	string	Can be one of the following values: Yes, No
maritalStatus	string	Can be one of the following values: Single, Married
homeOwnerStatus	string	Can be one of the following values: Rent, Own
lengthOfResidence	string	Can be one of the following values: Less than 1 year, 1 Year, 2 Years, 3 Years, 4 Years, 5 Years, 6 Years, 7 Years, 8 Years, 9 Years, 10 Years, 11-15 years, 16-19 years, 20+ years
homeMarketValue	string	Can be one of the following values: 1k-25k, 25k-50k, 50k-75k, 75k-100k, 100k-150k, 150k-200k, 200k-250k, 250k-300k, 300k-350k, 350k-500k, 500k-1mm, 1mm+
city	string	The city for the individual found for this request.
state	string	The state for the individual found for this request.
zipCode	string	The zip code for the individual found for this request.
status	string	Can be one of 3 values: Valid, InvalidRequest, or Error. Only a result with a Valid status may contain charges based on the number of fields returned.
statusMessage	string	A description of the status if anythng other than valid.
requestId	string	Request ID supplied in request to allow the result to be matched to the request.

Examples

GET Request

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

Response

GET Response

                        
{
    "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"
}

Examples

Demographics Append (POST)

https://rapid.peachtreedata.com/api/v1/demographicsappend?apikey={apikey}&fields=all

POST Request Body

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

POST Response

{
    "totalRequests": 5,
    "totalProcessed": 4,
    "totalInvalidRequests": 1,
    "totalBillableFieldCount": 24,
    "responses": [
        {
            "countOfFieldsRequested": 14,
            "countOfFieldsReturned": 5,
            "age": "45-54",
            "gender": "Male",
            "education": "Completed College",
            "occupation": "Professional",
            "netWorth": "100k-250k",
            "zipCode": "12345",
            "status": "Valid",
            "requestId": "1"
        },
        {
            "countOfFieldsRequested": 14,
            "countOfFieldsReturned": 5,
            "age": "45-54",
            "gender": "Male",
            "education": "Completed College",
            "occupation": "Professional",
            "netWorth": "100k-250k",
            "zipCode": "12345",
            "status": "Valid",
            "requestId": "2"
        },
        {
            "countOfFieldsRequested": 14,
            "countOfFieldsReturned": 1,
            "gender": "Female",
            "status": "Valid",
            "requestId": "3"
        },
        {
            "countOfFieldsRequested": 14,
            "countOfFieldsReturned": 14,
            "age": "55-64",
            "gender": "Female",
            "education": "Completed Graduate School",
            "presenceOfChildren": "No",
            "householdIncome": "250k+",
            "maritalStatus": "Single",
            "homeOwnerStatus": "Own",
            "occupation": "White Collar Worker",
            "lengthOfResidence": "16-19 years",
            "homeMarketValue": "300k-350k",
            "netWorth": "100k-250k",
            "city": "Duluth",
            "state": "GA",
            "zipCode": "12345",
            "status": "Valid",
            "requestId": "4"
        },
        {
            "countOfFieldsRequested": 14,
            "countOfFieldsReturned": 0,
            "status": "InvalidRequest",
            "statusMessage": "The request was not valid. Check the parameters to ensure they are correct and try again.",
            "requestId": "5"
        }
    ]
}

GET Request (Using specific fields)

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

GET Response

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

Appendix

HTTP Response Codes

HTTP Response codes are the way to determine if processing succeeded or not. If processing succeeded, the service will return a HTTP 200 (OK). If the result was processing was not successful, the response message will provide more details to resolve the issue.

Code	Description
200	Processed Successfully.
400	Bad Request. One of the following caused the problem: ApiKey format is invalid. Address is missing or not properly passed ApiKey is missing.
401	Unauthorized. Either the ApiKey is not activeor invalid.
403	Forbidden. Either the number of addresses exceed max allowed per request, or the account is not setup for the service.
408	Request Timeout. Processing time exceeded max processing time.
500	Internal Server Error. An error occurred during the processing of the request.

US Address Cleanse Status Codes

Digit	Description
1st	A: Truncated the address line to make it fit your field. B: Truncated both the address line and the city. C: Truncated the city to make it fit your field. S: No truncation occurred.
2nd	0: Regarding the city, state, ZIP Code, and Zip + 4, there is 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	0: Regarding the primary name, primary prefix/postfix, and primary type, there is no significant difference. 1: Assigned a different primary type. 2: Assigned a different primary prefix. 3: Assigned a different primary prefix and primary type. 4: Assigned a different primary postfix. 5: Assigned a different primary type and primary postfix. 6: Assigned a different primary prefix and primary postfix. 7: Assigned a different primary prefix, primary type, and primary postfix. 8: Assigned a different primary name. 9: Assigned a different primary name and primary type. A: Assigned a different primary prefix and primary name. B: Assigned a different primary prefix, primary name, and primary type. C: Assigned a different primary name and primary postfix. D: Assigned a different primary name, primary type, and primary postfix. E: Assigned a different primary prefix, primary name, and primary postfix. F: Assigned a different primary prefix, primary name, primary postfix, and primary type.
4th	0: Regarding the county number, sort code route, delivery point, and unit description, there is 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	0: Regarding the Line of Travel (LOT), LOT Order, there is no significant difference. 1: Assigned a different LOT. 2: Assigned a different LOT_Order. 3: Assigned a different LOT and LOT_Order.
6th	Always outputs a zero(0)

US Address Cleanse Error Codes

Error 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/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 EWS directory.
E500	Other error.
E501	Foreign address.
E502	Input record entirely blank.
E503	Postal code not in area covered by partial USPS directory.
E504	Overlapping ranges in 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.

Canadian Address Cleanse Status Codes

Character	Description
1st	S: Always S (for Status).
2nd	0: No significant difference between the input data and the corrected data. 1: Corrected country. 2: Corrected postal code. 3: Corrected country and postal code. 4: Corrected province 5: Corrected country and province. 6: Corrected postal code and province. 7: Corrected country, postal code, and province. 8: Corrected locality. 9: Corrected country and locality. A: Corrected postal code and locality. B: Corrected country, postal code, and locality. C: Corrected province and locality. D: Corrected country, province, and locality. E: Corrected postal code, province, and locality. F: Corrected country, postal code, province, and locality.
3rd	0: No significant difference between the input data and the corrected data. 1: Corrected pre/post directional 2: Corrected primary type. 3: Corrected pre/post directional and primary type. 4: Corrected primary name. 5: Corrected pre/post directional and primary name. 6: Corrected pre/post directional and primary name. 7: Corrected pre/post directional, primary type, and primary name. 8: Corrected primary range. 9: Corrected pre/post directional and primary range. A: Corrected primary type and primary range. B: Corrected pre/post directional, primary type, and primary range. C: Corrected primary name and primary range. D: Corrected pre/post directional, primary name, and primary range. E: Corrected primary type, primary name, and primary range. F: Corrected pre/post directional, primary type, primary name, and primary range.
4th	0: No significant difference between the input data and the corrected data. 1: Corrected one or more secondary address component (unit description, floor description, stairwell description, or wing description). 2: Corrected one or more secondary address component (unit number, floor number, stairwell name, or wing name). 3: Corrected one or more secondary address component (unit description, unit number, floor description, floor number, stairwell description, stairwell name, wing description, or wing name). 4: Corrected building name. 5: Corrected one or more secondary address component (unit description, floor description, stairwell description, or wing description), and building name. 6: Corrected the one or more secondary address component (unit number, floor number, stairwell name, or wing name), and building name. 7: Corrected one or more secondary address component (unit description, unit number, floor description, floor number, stairwell description, stairwell name, wing description, or wing name), and building name. 8: Corrected firm. 9: Corrected one or more secondary address component (unit description, floor description, stairwell description, or wing description), and firm. A: Corrected one or more secondary address component (unit number, floor number, stairwell name, or wing name), and firm. B: Corrected one or more secondary address component (unit description, unit number, floor description, floor number, stairwell description, stairwell name, wing description, or wing name), and firm. C: Corrected building name and firm. D: Corrected one or more secondary address component (unit description, floor description, stairwell description, or wing description), building name, and firm. E: Corrected one or more secondary address component (unit number, floor number, stairwell name, or wing name), building name, and firm. F: Corrected one or more secondary address component (unit description, unit number, floor description, floor number, stairwell description, stairwell name, wing description, or wing name), building name, and firm.
5th	0: No significant change between the input data and the corrected data. 1: Changed the Other Primary Address components. 2: Changed the Other Secondary Address components. 3: Changed the Other Primary Address and Other Secondary Address components. 4: Changed the point of reference. 5: Changed the Other Primary Address components and the point of reference. 6: Changed the Other Secondary Address components and the point of reference. 7: Changed the Other Primary Address, Other Secondary Address components, and the point of reference.

Canadian Address Cleanse Error Codes

Error Code	Description
1020	Address validated in multiple countries.
1030	No country found by Country ID or no country set for the record.
1040	Address contains at least one character that is not part of the character set supported by the engine.
2000	Unable to identify city, province, and/or postcode information on input.
2010	Unable to identify city and invalid postcode found.
2020	Unable to identify postcode. Invalid city is preventing a possible address correction.
2030	Invalid city and postcode are preventing a possible address correction.
3000	City, province, and postcode are valid. Unable to identify the primary address line.
3010	City, province, and postcode are valid. Unable to match primary name to directory.
3020	Possible primary name matches are too close to choose one.
3030	Primary range is missing on input or not in the directory.
3050	An invalid or missing primary type is preventing a possible address match.
3070	An invalid or missing prefix/postfix (directional) is preventing a possible address match.
3080	An invalid or missing postcode is preventing a possible address match.
3100	Possible address-line matches are too close to choose one.
3110	Address conflicts with postcode and the same primary name has a different postcode.
4000	The secondary information is missing on input or not in the directory.
4010	Possible secondary address line matches are too close to choose one.
5010	The address does not reside in the specified country.
6000	Unclassified error.

© Copyright 1994-2013 Peachtree Data, Inc. All rights reserved.
Peachtree Data is a non-exclusive Full Service Provider Licensee of the United States Postal Service®.
The following trademarks and registrations are owned by the United States Postal Service:
CASS, First-Class, DSF2, LACSLink, NCOALink, SuiteLink, USPS, U.S. Postal Service, United States Postal Service, United States Post Office, ZIP, ZIP + 4, ZIP Code. Ad #4.09