Personator Consumer:Request

From Melissa Data Wiki
Revision as of 22:23, 19 June 2017 by Admin (talk | contribs)
Jump to navigation Jump to search

← Personator Consumer

Personator Consumer Navigation
Introduction
Basics
Licensing
Input/Output
Request Fields
Response Fields
Examples
REST JSON
REST JSONP
REST XML
JSON
Batch JSON
XML
Batch XML
Result Codes
Result Code Use
Personator Consumer Result Codes
Sample Code



A request consists of a protocol to make a call to the service, detailing desired elements. The minimum required elements in a request are your License Key (Customer ID) and the fields listed as Required below.

Personator allows for inputting data using either discrete/individual columns, or with single string input using Free Form. The web service supports JSON, JSONP, REST, SOAP, and XML protocols.


Field Names

This is a list of the request field names and their protocol naming conventions.

Field Name REST JSON/XML
Transmission Reference t TransmissionReference
License Key id CustomerID
Actions act Actions
Columns cols Columns
Options opt Options
First Name first FirstName
Last Name last LastName
Full Name full FullName
Company Name comp CompanyName
Address Line 1 a1 AddressLine1
Address Line 2 a2 AddressLine2
City city City
State state State
Postal Code postal PostalCode
Country ctry Country
Last Line lastline LastLine
Email email Email
Phone phone Phone
Free Form ff Freeform
Format format Format


Request Elements

The following elements set the basic options for each request. These apply to the entire request, not the individual records.

Transmission Reference

Optional.
This is a string value that serves as a unique identifier for this set of records. It is returned as sent.
Protocol Syntax
JSON "TransmissionReference":"string"
REST ?t = string
SOAP/XML <TransmissionReference>string</TransmissionReference>


License Key

Required.
This is a string value containing the License Key issued to the customer by Melissa for the web service.
If this element is absent, the web service will return an error. To receive a License Key, please contact your Melissa sales representative at 1-800-MELISSA.
Protocol Syntax
JSON "CustomerID":"string"
REST &id = string
SOAP/XML <CustomerID>string</CustomerID>


Actions

Required.
Specifies the actions. See the actions below for more information.
Protocol Syntax
JSON "Actions":"string"
REST &act = string
SOAP/XML <Actions>string</Actions>


List actions in the following format, with multiple actions delimited with a "," or ";".
Syntax
Action,Action


Check

The Check action will validate the individual input data pieces for validity and correct them if possible. If the data is correctable, additional information will often be appended as well. US and Canada only.
Action Name Parameter
Check Check
Check(Address)

US and Canada only. Check (Address) will only be processed if the following is true: AddressLine1 is not empty Both City and State are not empty or PostalCode is not empty.

AddressLine1 and AddressLine2 Request AddressLine1 and AddressLine2 may each contain a full address. If both addresses are verified as valid, both are returned as inputted. If AddressLine1 has an invalid address and AddressLine2 has a valid address, the return order is switched. This returns the valid address previously in AddressLine2 into AddressLine1. Conversely, the invalid address in AddressLine1 will be returned in AddressLine2. Alternatively, AddressLine2 may contain a suite number for AddressLine1. The suite information will be cleared from AddressLine2 and placed under its own field in the output. For all of the possible return values for Check (Address) see \"Check (Address) Result Codes\" section.

Geocode If an address is verifiable, you can choose to geocode it. You will have the geocoding information appended (depending on your license). Geocoding is available for US and Canada.

To use Geocode, you must have the geocode columns on: GrpCensus or GrpGeocode.

Geodetic System

The GeoCoder Object uses WGS 84 standard, an Earth-centered, Earth-fixed terrestrial reference system and geodetic datum.

Geocode level

Your license will determine what geocode level you are allowed. If your license only has address checking enabled, you can geocode to 5 digits. If your license only has GeoCode enabled, you can geocode to 9 digits. If your license has GeoPoints enabled, you can geocode to 11 digits.

Geocode requires the results returned from the Web service.

Check (Phone)

US and Canada only. Check (Phone) will only be processed if the PhoneNumber input has a value.


Verify

The Verify action will return to you the relationships between your different input data pieces. It can show you if your name, address, email, and phone number are correlated (belonging to the same person) or not.
Action Name Parameter
Verify Verify


Move

The Move action will return the latest address for an individual or business if a previous address was entered. Move requires either a Last Name and Address, or a Business/Company Name and Address as inputs.
Move also returns results codes that help identify which addresses were updated with a move.
Action Name Parameter
Move Move


Append

The Append action will return elements based on the selected point of centricity which can either be the address, email or phone. For example, an address centric Append will return the name, company, phone and email associated with the given address.
Action Name Parameter
Append Append


Options

Optional.
Specifies the options. See the options below for more information.
Protocol Syntax
REST &opt = string


List options in the following format, with multiple options delimited with a ";".
Syntax
OptionName:Parameter;OptionName:Parameter


UsePreferredCity

Check(Address)
For every city in the United States, there is an official name that is preferred by the U.S. Postal Service. There may be one or more unofficial or “vanity” names in use. Normally, Personator allows you to verify addresses using known vanity names. If the usePreferredCity is set to on, Personator will substitute the preferred city name for all vanity names when it verifies an address.
Option Name Parameter Description
UsePreferredCity on Will substitute the preferred city name for all vanity names.
off Default. No substitution will occur.


Diacritics

Check(Address)
Determines whether or not French language characters are returned. If set to auto, those characters are only returned if they are in the input.
Option Name Parameter Description
Diacritics on Will return diacritics.
off No diacritics returned.
auto Default. Diacritics only returned if in the input.


Check(Address)
Option Name Parameter Description
' # [0 - #] Default set to 3. Sets the maximum number of emails to be returned.

Option Name Parameter Description
' # [0 - #] Default set to 3. Sets the maximum number of emails to be returned.

Option Name Parameter Description
' # [0 - #] Default set to 3. Sets the maximum number of emails to be returned.

Option Name Parameter Description
' # [0 - #] Default set to 3. Sets the maximum number of emails to be returned.







ReturnAllPages

Option Name Parameter Description
ReturnAllPages true Will return all records up to a limit of 500.
false Default. Will not return all records.


SearchConditions

Specifies the type of search conditions to use when returning records. Only the populated input fields will be compared. A strict search condition is used by default.
Option Name Parameter Description
SearchConditions strict Default. The input values should match the output values exactly.
loose No filtering will be done. Raw record results will be returned.


SearchType

This options allows you to specify the type of search to perform.
Option Name Parameter Description
SearchType Auto Default. Performs name, address, email, and phone searches until one or more matches are found.
NameSearch Uses name data as the primary pivot when verifying or appending information.
AddressSearch Uses address data as the primary pivot when verifying or appending information.
EmailSearch Uses email data as the primary pivot when verifying or appending information.
PhoneSearch Uses phone data as the primary pivot when verifying or appending information.


SortBy

Allows sorting records in a particular order.
If ascending or descending is not specified, the default order will be ascending.
Option Name Parameter Description
SortBy PostalCode-ascending
PostalCode-descending		 Sort by postal code. Plus4 is also included with the ordering.
CityState-ascending
CityState-descending		 Sort by state then city.
AddressLine1-ascending
AddressLine1-descending		 Sort by address line 1.
FullName-ascending
FullName-descending		 Sort by full name.
FirstName-ascending
FirstName-descending		 Sort by first name.
LastName-ascending
LastName-descending		 Sort by last name.
DateOfBirth-ascending
DateOfBirth-descending		 Sort by date of birth.
DateOfDeath-ascending
DateOfDeath-descending		 Sort by date of death.
MoveDate-ascending
MoveDate-descending		 Sort by move date.
MelissaAddressKey-ascending
MelissaAddressKey-descending		 Sort by Melissa Address Key.
MelissaAddressKeyBase-ascending
MelissaAddressKeyBase-descending		 Sort by Melissa Address Key Base.


Columns

Optional.
Specifies which column(s) to be output as a column delimited string.
Protocol Syntax
REST &cols = string


Entering the column name will return the column. Specifying a group name will return all columns in the group.
Field Name Default Group Groups GrpAll
FullName [DEFAULT]
Returned by default.		 N/A GrpAll
FirstName
LastName
AddressLine1 PreviousAddress
Suite
City
State
PostalCode
Plus4
MelissaAddressKey
MelissaAddressKeyBase
Phone N/A Phone
Email Email
MoveDate MoveDate
DateOfDeath DateOfDeath
DateOfBirth DateOfBirth


Free Form

Optional.
Accepts delimited or undelimited free form input. This will be parsed by the service.
Protocol Syntax
REST &ff = string


Full Name

Recommended.
The full name.
Protocol Syntax
REST &full = string


First Name

Optional.
The first name.
Protocol Syntax
REST &first = string


Last Name

Optional.
The last name.
Protocol Syntax
REST &last = string


Address Line 1

Optional.
The input field for the address. This should contain the delivery address information (house number, street, building, suite, etc.) but should not contain locality information (city, state, postal code, etc.) which have their own inputs.
Protocol Syntax
REST &a1 = string


City

Optional.
The city.
Protocol Syntax
REST &city = string


State

Optional.
The US state.
Protocol Syntax
REST &state = string


Postal Code

Optional.
The postal code.
Protocol Syntax
REST &postal = string


Phone Number

Optional.
The phone number.
Protocol Syntax
REST &phone = string


Email Address

Optional.
The email address.
Protocol Syntax
REST &email = string


Melissa Address Key (MAK)

Optional.
A propietary unique key identifier for an address.
Protocol Syntax
REST &mak = string



|- |JSON||"":"string" |- |REST||? = string |- |SOAP/XML||<>string</>

Retrieved from "http://wiki.melissadata.com/index.php?title=Personator_Consumer:Request&oldid=13067"