How do I access the Personator Consumer Web Service?#

The endpoint for the service is:


Your License Key is your key to the service. As long as you put this ID in each request you will have access to all of the features you qualify for. The request structure for each format has a License Key field and all you need to do is fill that field with your License Key.

Personator Consumer has several packages that you can purchase, these packages grant you access to different features. The basic Personator Consumer service lets you use the Check action. In addition to check you could upgrade to access the Verify action, and/or Geocode functionality. If you have access to Geocode you may also want to upgrade further to get access to Geopoint.


Personator Consumer has multiple actions that it can perform. If multiple actions are selected they are delimited by commas or semicolons.


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 t o the data. Check looks at each data separately, the inputs you put in for email don’t affect what Check does with an address. Check returns result codes that describe which inputs were invalid, valid, or corrected. It also returns the input data after it has been corrected and added to by the web service.


The Verify action allows you to select a centric datapoint and then determines whether the other datapoints 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 result codes describing what it found.


The Move action allows you to get the latest move information for an individual or business. It requres 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 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 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.


Personator Consumer gives you the ability to select what data you get back from the service. In the columns input field you can select which columns are returned (in addition to the default columns which are always returned). The columns input is delimited by a comma and you may select groups (using the group name) or select each column individually. Columns are only returned after a Check action is performed, the Verify action only returns result codes.


Each record in the response has a results field that contains a series of result codes that carry a tremendous amount of information about the output. The result codes are delimited by commas. One way we recommend using result codes is as a filter between good and bad records. Determine which codes indicate a good record for your purposes and then filter out all the records that are returned without those codes. A good simple example would be if good records are those that return an AS01, AS02, or AS03 code (these codes generally indicate a valid address record). When you process a number of records through the service you can then parse the output and filter out all of the records that do not return one of those codes in the results field.

See Personator Consumer Result Codes for more information.

Combining Actions#

Personator Consumer allows you to select multiple actions and can perform each of them on a given input. When you combine actions the service combines their respective outputs, the way in which it does this varies depending on which actions you select.

  • Verify + append and/or check: Verify just returns result codes by itself so when combined with other actions it merely appends its result codes to the result codes returned by the other actions. It is worth noting that Verify looks at the data with whatever additions or corrections that check and/or append make.

  • Check + append: When these actions are combined the service first passes the data through check and then has append add whatever data it is going to add, potentially overwriting data that was altered or added by check.