Personator Consumer:Basics
| Personator Consumer Navigation | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
| ||||||||
| ||||||||
| ||||||||
| Sample Code |
Basic Procedures
Using Personator starts with creating a request. This request must include your customer ID, which serves as a key for accessing the service, and any action(s) you want Personator to execute. Optionally, you can include which options you want to use and what columns(fields) you want returned.
The main points in preparing a request for Personator are:
- Customer ID
- Actions (Check, Verify, Move, or Append)
- Options
- Result Fields
You then need to cycle through all the records you want to add to it. For each record, you place all the different values into the appropriate fields and then add the record to the request structure. Once the request is finished, you send it to the service and get back the response. The response structure is very similar to the request; it contains a list of records equivalent to the one sent in the request. Each record in the response contains the output for one record from the request.
Actions
The Actions field is what determines what action the service will perform on the input data. This is a required field.
Check
The Check action determines whether the data within a submitted record is valid, e.g. whether or not a given postal code contains the given city. It can also make limited corrections and appends to the data. Check looks at each data point separately, the inputs you put in for email don't affect what Check does with an address. Check returns results codes that describe which inputs were invalid, valid, or corrected. It also returns the input data after it has been corrected and added by the Web service. The Check action is available for US and Canadian addresses.
Verify
The Verify action allows you to select a centric data point and then determines whether the other data points are associated with it. For example, if you perform an address centric verify, it will tell you whether the name, phone, and email on that record coincide with that address in our database. Verify only returns the results column with results codes describing what it found. The Verify action is available only for US addresses.
Move
The Move action allows you to get the latest move information for an individual or business. It requires that you have at the very least, a person's last name and an address. The returned address information will contain the updated address if a move was detected. Move also returns result codes which help you identify which addresses have a move. The Move action is available for US addresses.
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. Append also returns result codes which help you identify which elements were appended. The Append action is available for US addresses.
Options
The Options field allows you to configure a number of options that change the way the service behaves. For instance, the UsePreferredCity option defaults to 'off.’ This means that by default the service does not transform the input city name to the USPS preferred city name in the output. However, by adding 'UsePreferredCity:on' to the Options field, the service will change all city names into their preferred incarnations.
Columns
Personator allows the user to select what data the service will output. The Columns input field allows you to select either individual columns or groups which will then be returned in the output. These selected columns are returned in addition to the default columns which are always returned. Columns are only relevant when performing a Check, Move, or Append action, Verify only ever returns the results column.
Results
Every record in the response has a column called Results. This column contains a series of results codes, which are short codes that convey a great deal of information from the service. Generally, the codes tell you whether the inputs are valid, invalid, or have been changed by the service in some way. For instance, an AS01 code in the results indicates a valid, deliverable address in that record.
Single Record vs. Batch
Single record and batch requests are both made to the same endpoint. In fact, there is really no difference between single record and batch processing in Personator; single record requests are essentially batches of one. Personator can handle batches of up to 100 and it is generally recommended that you use 100 records per request as the service performs much faster the more records you use in each request.