Personator Consumer:Request: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
No edit summary |
||
Line 781: | Line 781: | ||
|- | |- | ||
|<code>always</code>||Always returns information. | |<code>always</code>||Always returns information. | ||
|} | |} | ||
Revision as of 18:03, 11 September 2017
Personator Consumer Navigation | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
| ||||||||
| ||||||||
| ||||||||
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 |
Phone | phone | Phone |
Free Form | ff | Freeform |
Format | format | Format |
Melissa Address Key | mak | MAK |
Social Security Number | ss | SocialSecurity |
IP Address | ip | IPAddress |
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.
- 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.
Check (Email)
- US and Canada only. Check (Email) will only be processed if the EmailAddress input has a value.
Check (Name)
- US and Canada only. Check (FullName) will only be processed if the FullName or FirstName 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
Verify (Address, Phone, Email)
- The type of search performed is dependent upon your defined centric piece of information.
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
Append (Address, Phone, Email)
- The appended information is dependent upon your defined centric piece of information.
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
Columns
- Optional.
- Specifies which column(s) to be output.
Protocol Syntax JSON "Columns":"string"
REST &cols = string
SOAP/XML <Columns>string</Columns>
- Entering the column name will return the column. Specifying a group name will return all columns in the group.
Field Name Group AddressExtras [DEFAULT]
Returned by default.AddressKey AddressLine1 AddressLine2 City CompanyName EmailAddress MelissaAddressKey MelissaAddressKeyBase NameFull PhoneNumber PostalCode RecordID Results State MoveDate N/A Occupation OwnRent PhoneCountryCode PhoneCountryName Plus4 PrivateMailBox Suite AddressTypeCode GrpAddressDetails CarrierRoute CityAbbreviation CountryCode CountryName DeliveryIndicator DeliveryPointCheckDigit DeliveryPointCode StateName UrbanizationName UTC CBSACode GrpCensus CBSADivisionCode CBSADivisionLevel CBSADivisionTitle CBSALevel CBSATitle CensusBlock CensusTract CongressionalDistrict CountyFIPS CountyName PlaceCode PlaceName CensusKey GrpCensus2 CountySubdivisionCode CountySubdivisionName ElementarySchoolDistrictCode ElementarySchoolDistrictName SecondarySchoolDistrictCode SecondarySchoolDistrictName UnifiedSchoolDistrictCode UnifiedSchoolDistrictName StateDistrictUpper StateDistrictLower Latitude GrpGeocode Longitude ChildrenAgeRange GrpDemographicBasic CreditCardUser DateOfBirth DateOfDeath DemographicsGender DemographicsResults Education EthnicCode EthnicGroup HouseholdIncome HouseholdSize LengthOfResidence MaritalStatus PoliticalParty PresenceOfChildren PresenceOfSenior Gender GrpNameDetails Gender2 NameFirst NameFirst2 NameLast NameLast2 NameMiddle NameMiddle2 NamePrefix NamePrefix2 NameSuffix NameSuffix2 Salutation AddressDeliveryInstallation GrpParsedAddress AddressHouseNumber AddressLockBox AddressPostDirection AddressPreDirection AddressPrivateMailboxName AddressPrivateMailboxRange AddressRouteService AddressStreetName AddressStreetSuffix AddressSuiteName AddressSuiteNumber DomainName GrpParsedEmail MailboxName TopLevelDomain AreaCode GrpParsedPhone NewAreaCode PhoneExtension PhonePrefix PhoneSuffix
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.
AdvancedAddressCorrection
- Check(Address)
- Uses the name input to perform more advanced address corrections. This can correct or append house numbers, street names, cities, states, and ZIP codes.
Option Name Parameter Description AdvancedAddressCorrection on
Will use name input to perform advanced address corrections. off
Default. No advanced address corrections will occur.
LongAddressFormat
- Check(Address)
- This function controls how Personator handles the abbreviations of suffixes and directionals when standardizing a street address. Setting this option to on will spell out any suffix and directional abbreviations (Ave to Avenue). Setting this option to auto will preserve the suffix and directional as they were entered. In auto mode, if a spelled out “avenue” is entered, we will keep the suffix spelled out and vice versa.
Option Name Parameter Description LongAddressFormat on
Will spell out suffixes and directional abbreviations. off
Default. Will abbreviate suffixes and directionals. auto
Will preserve suffixes and directionals as entered.
CorrectSyntax
- Check(Email)
- If set to on, corrects the syntax of the Email field.
Option Name Parameter Description CorrectSyntax on
Default. Will correct the syntax of the Email field. off
No corrections will occur.
UpdateDomain
- Check(Email)
- If set to on, determines whether the domain name is out of date and updates it.
Option Name Parameter Description UpdateDomain on
Default. Will update the domain if it is out of date. off
No updates will occur.
DatabaseLookup
- Check(Email)
- If set to on, verification of domain names will be attempted using a database of valid domains.
Option Name Parameter Description DatabaseLookup on
Default. Will attempt to verify domain names. off
No verification will occur.
StandardizeCasing
- Check(Email)
- If set to on, changes all letters in the Email field to lower case before any checking occurs.
Option Name Parameter Description StandardizeCasing on
Default. Will standardize all letters to lower case. off
No case changes will occur.
CorrectFirstName
- Check(Name)
- If set to on, allows common spelling corrections for the FirstName field.
Option Name Parameter Description CorrectFirstName on
Default. Will perform spelling corrections on the FirstName field. off
No spelling corrections will occur.
StandardizeCompany
- Check(Name)
- If set to on, the CompanyName field will be returned with standard abbreviation, capitalization, and punctuation rules applied.
Option Name Parameter Description StandardizeCompany on
Default. Will perform standard abbreviation, capitalization, and punctuation on the CompanyName field. off
No changes will occur.
NameHint
- Check(Name)
- Sets the name hint for the input name.
Option Name Parameter Description NameHint varying
Default. If necessary, statistical logic will be employed to determine name order, with no bias toward either name order. definitelyfull
Name will always be treated as normal name order, regardless of formatting or punctuation. verylikelyfull
Name will be treated as normal name order unless inverse order is clearly indicated by formatting or punctuation. probablyfull
If necessary, statistical logic will be employed to determine name order, with a bias toward normal name order. probablyinverse
If necessary, statistical logic will be employed to determine name order, with a bias toward inverse name order. verylikelyinverse
Name will be treated as inverse name order unless normal order is clearly indicated by formatting or punctuation. definitelyinverse
Name will always be treated as inverse name order, regardless of formatting or punctuation. mixedfirstname
Name field is expected to only contain prefixes, first, and middle names. mixedlastname
Name field is expected to only contain last names and suffixes.
GenderPopulation
- Check(Name)
- Sets the gender balance of the source data, either predominantly male, female, or mixed (evenly split).
Option Name Parameter Description GenderPopulation mixed
Default. Sets source data gender balance to mixed. male
Sets source data gender balance to predominantly male. female
Sets source data gender balance to predominantly female.
GenderAggression
- Check(Name)
- Sets how aggressive genderization is for neutral first names.
Option Name Parameter Description GenderAggression neutral
Default. Gender agression is neutral. conservative
Gender aggression is conservative. aggressive
Gender aggression is aggressive.
MiddleNameLogic
- Check(Name)
- Determines the handling of middle names.
- ParseLogic: Middle names that are typically last names are considered to be part of a hyphenated last name.
- HypenatedLast: The middle word is assumed to be part of the last name.
- For Example: "Matthew Edward Jones" is treated as "Matthew Edward-Jones."
- MiddleName: The middle word is assumed to be a middle name.
- For example: "Matthew Svensson Jones." "Svensson" would be considered a middle name instead of part of the last name.
Option Name Parameter Description MiddleNameLogic parselogic
Default. Middle name typically a last name is assumed to be a hypenated last name. hyphenatedlast
Middle word assumed to be part of the last name. middlename
Middle word assumed to be a middle name.
SalutationFormat
- Check(Name)
- Sets the salutation format for the response.
- Formal: Dear Mr. Smith
- Informal: Dear John
- First/Last: Dear John Smith
Option Name Parameter Description SalutationFormat formal
Default. Sets the salutation format to formal. informal
Sets the salutation format to informal. firstlast
Sets the salutation format to first/last.
CentricHint
- Verify(Address, Phone, Email)
- When set to Auto, it first uses Address if available, followed by Phone if no Address is available, and lastly Email if neither Address nor Phone are available. Use this to tell the service which piece of information to use as the primary pivot when verifying information.
Option Name Parameter Description CentricHint auto
Default. Will use Address, Phone, then Email as a primary pivot. address
Will use Address as a primary pivot. phone
Will use Phone as a primary pivot. email
Will use Email as a primary pivot.
CentricHint
- Append(Address, Phone, Email)
- When set to Auto, it first uses Address if available, followed by Phone if no Address is available, and lastly Email if neither Address nor Phone are available. Use this to tell the service which piece of information to use as the primary point of reference when appending data.
Option Name Parameter Description CentricHint auto
Default. Will use Address, Phone, then Email as a primary pivot. address
Will use Address as a primary pivot. phone
Will use Phone as a primary pivot. email
Will use Email as a primary pivot.
Append
- Append(Address, Phone, Email)
- Setting this option to Blank will cause the service to return information only when the input address, phone, email, name or company is blank.
- Setting this option to CheckError will cause the service to return information when there are errors to either the address, phone, email, name or company. What an error entails are defined as follows:
- Address Error: If the input address was not found in the database, was not at the least partially verified, or could not be corrected. (does not contain AS01, AS02, or AS03).
- Phone Error: If the input phone number was not matched to either the 10 digit or 7 digit level at the least. (does not contain PS01 or PS02).
- Email Error: If the input email address was not found in the database, or if the email is unconfirmed. (does not contain ES01 or ES03).
- Name Error: If the input name did not parse successfully (does not contain NS01)
- Company Error: If the input company was blank.
- Setting the Append option to Always will cause the service to return information all the time, regardless of whether the input address, phone, email, name or company is blank or incorrect.
Option Name Parameter Description Append blank
Default. Returns information when the input field is blank. checkerror
Returns information when there are errors. always
Always returns information.
First Name
- Optional.
- The given (first) name.
Protocol Syntax JSON "FirstName":"string"
REST &first = string
SOAP/XML <FirstName>string</FirstName>
Last Name
- Optional.
- The family (last) name.
Protocol Syntax JSON "LastName":"string"
REST &last = string
SOAP/XML <LastName>string</LastName>
Full Name
- Recommended.
- This field can contain a full name. We will parse and check Names only if the First Name and Last Name fields are left blank.
Protocol Syntax JSON "FullName":"string"
REST &full = string
SOAP/XML <FullName>string</FullName>
Company Name
- Optional.
- The company name.
Protocol Syntax JSON "CompanyName":"string"
REST &comp = string
SOAP/XML <CompanyName>string</CompanyName>
Address Line 1
- Optional.
- The input field for the address line 1. 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 JSON "AddressLine1":"string"
REST &a1 = string
SOAP/XML <AddressLine1>string</AddressLine1>
Address Line 2
- Optional.
- The input field for the address line 2. This can be a continuation of AddressLine1 (ex: suite) or another address.
Protocol Syntax JSON "AddressLine2":"string"
REST &a2 = string
SOAP/XML <AddressLine2>string</AddressLine2>
City
- Optional.
- The city.
Protocol Syntax JSON "City":"string"
REST &city = string
SOAP/XML <City>string</City>
State
- Optional.
- The US state.
Protocol Syntax JSON "State":"string"
REST &state = string
SOAP/XML <State>string</State>
Postal Code
- Optional.
- The postal code.
Protocol Syntax JSON "PostalCode":"string"
REST &postal = string
SOAP/XML <PostalCode>string</PostalCode>
Country
- Optional.
- The country.
Protocol Syntax JSON "Country":"string"
REST &ctry = string
SOAP/XML <Country>string</Country>
Last Line
- Optional.
- The city, state, and ZIP.
Protocol Syntax JSON "LastLine":"string"
REST &lastline = string
SOAP/XML <LastLine>string</LastLine>
- Optional.
- The email address.
Protocol Syntax JSON "Email":"string"
REST &email = string
SOAP/XML <Email>string</Email>
Phone
- Optional.
- The phone number.
Protocol Syntax JSON "Phone":"string"
REST &phone = string
SOAP/XML <Phone>string</Phone>
Free Form
- Optional.
- Accepts delimited or undelimited free form input. This will be parsed by the service.
Protocol Syntax JSON "Freeform":"string"
REST &ff = string
SOAP/XML <FreeForm>string</Freeform>
Format
- Optional.
- Sets the format of the response.
Protocol Syntax JSON "Format":"string"
REST &format = string
SOAP/XML <Format>string</Format>
Melissa Address Key (MAK)
- Optional.
- A propietary unique key identifier for an address.
Protocol Syntax JSON "MAK":"string"
REST &mak = string
SOAP/XML <MAK>string</MAK>
Social Security Number
- Optional.
- Social Security Number for the record. Accepts the full Social Security Number or the Last 4 digits.
Protocol Syntax JSON "SocialSecurtiy":"string"
REST &ss = string
SOAP/XML <SocialSecurity>string</SocialSecurity>
IP Address
- Optional.
- An IP Address for the record.
Protocol Syntax JSON "IPAddress":"string"
REST &ip = string
SOAP/XML <IPAddress>string</IPAddress>