One of the functions of Verato’s software is to serve as a reflection of the identity data that exists in your own applications and data systems. When you add a new identity record to one of your source systems, you want that same identity record added to your Verato intsance; when you merge two records in one of our source systems, you want those same records merged in your Verato instance; when you delete a record in one of your source systems, you want the same record deleted in your Verato instance.
Verato’s APIs are the most common method through which you synchronize changes in your source systems to your Verato instance. They allow you to perform all the appropriate adds, updates, deletes, merges and more, to ensure that the overall records and data attribute values are reflected in Verato.
There are a few specific types of metadata that can also be important to account for, and it’s possible to either preserve or lose some of that metadata depending on how you use Verato’s APIs. This guide will educate you about how to handle those few specific types of metadata:
User information - which user in your source application actually performed an add or update action?
Timing information - when did an activity take place in your data source (which might not be the same as when you notified Verato about that activity)?
Source lineage - what was the data source for the information, and how is the identity record uniquely identified in that data source?
Verato manages your data using an approach where the combination of a source code (Source) and an unique local ID within that source (Native ID) will uniquely identify each identity record from your data sources. This combination is important in that it allows Verato to determine when a Post Identity API request represents an add (a Source + Native ID combination that you have never sent to Verato before) or an update (a Source + Native ID combination that you have previously sent to Verato). It is also important because the combination of Source + Native ID is used during merges, deletes, and more to identify which specific identity record you want to act on.
Planning out the use of Source and Native ID at the beginning of your Verato implementation is an important step.
In most cases, the data value you use to represent each Source in your Verato instance is obvious, and those sources have an obvious unique local ID for each identity record within that source. As an example, one of your sources might be an electronic health record (EHR) application, and each unique person record in that source is assigned a medical record number (MRN). In this example, you can define a source in your Verato instance named ‘ehr’, and you can map the MRN value from that source into the Native ID field for all Verato API calls.
In some cases, the choice for defining the Source and Native ID is less obvious. Examples of where the mapping is not obvious include:
You have a single application from which you want to synchronize two distinct types of identity objects/records, and you’d like to keep them separated. An example would be a CRM application that has both customer and prospect objects, which come from different parts of the CRM application’s data model. In this case, the best approach is to define two Sources in your Verato configuration - one might be named crm.customers and the other might be named crm.prospects. When you synchronize customer objects from the CRM application, you do so using the crm.customers source name in your API requests. When you synchronize prospect objects from the CRM application, you do so using the crm.prospects source name in your API requests. The Source definitions configured in Verato do not need to correspond 1-to-1 with physical source applications or databases - they should align with logical groupings of identity records.
You have a single application or data source that you use to ‘feed’ data into Verato, but that data source is itself an aggregation of other data sources. For example, you are an insurance company who has a database where you have aggregated customer data from auto, home, and life insurance policies. Suppose your policy database is called “PDB”. You do have the option to simply define one source named ‘pdb’ in your Verato configuration, and you will use that data value as the Source name in all your Verato API requests. A better approach would be to concatenate that source name with an additional field that indicates the policy type, and use that concatenation as the Source name in all your Verato API requests. Suppose this PDB database also has a ‘Policy Type’ attribute with values of AU, HO, and LI. One way of constructing the source definitions in Verato would be to define sources named PDB-AU, PDB-HO, and PDB-LI, and when you construct each API request, you append the ‘Policy Type' value onto the fixed string of “pdb-”. The advantage of doing this is that Verato’s in-product reporting, task detection, and permission settings can be used to apply more granular behavior on a source-by-source basis.
You have an application or data source where each person record is uniquely identified by a combination of more than one data value. For example, suppose that you have an application with records for healthcare providers (doctors or nurses), and each record in the database is uniquely identified by the combination of a ‘Provider Type’ code (which might have values like MD, DO, or NP) and a ‘Provider License Number’ value. In this case, to create a unique Native ID value for your Verato API requests, you would need to concatenate the ‘Provider Type’ and ‘Provider License Number’ values and use that concatenation as the Native ID value in your API requests.
Among the implications for how you decide what to use as Source + Native ID are:
The combination of Source + Native ID should be unique - if you use Source + Native ID values that turn out to be non-unique (two different records for two different people are sent to Verato with the same Source + Native ID values but conflicting attribute data) that will result in overlay errors.
Much of Verato’s dashboards and insights use Source as a key parameter - the insights you get from seeing how identities are behaving within and across sources can be powerful. If you send all your data from a single Source code to Verato, even though they really represent multiple original sources, you will lose fidelity when it comes to getting reports and insights.
Many of Verato’s product behaviors, whether matching-related or access-control-related, are based on Source - if you combine multiple original sources and represent them all with just a single Source value when you send data to Verato, you lose flexibility to control product behavior on a per-source basis.
API integration to your Verato instance is often set up using a ‘system’ user account for authentication and authorization purposes. For example, all the adds, updates, deletes, and more from your CRM application get synchronized to Verato through an automated integration process, and that process uses a single Verato user account for API authentication and authorization. For purposes of tracking audit trail, and for providing better visibility into ‘who did what’ when viewing identity data in Verato, our APIs allow you to pass in metadata in your API request for the original system user. This additional metadata should be placed in the “metadata” object within the “sources” object for API calls.
The Post Identity API allows you send in metadata with your API request for the following data elements:
sourceLoginName: this is the user name or user ID of the actual logged-in user in your source system who made an add or update. For example, the user “rsmith” was logged into your CRM system and added a new customer record. This results in an API request to Verato, which is made using a system user named “crm_integration_user”, but you can also pass along the metadata to keep track of the fact that this record addition was done by user “rsmith”.
sourceUserName: this is the human-readable string that corresponds to the sourceLoginName. For example, if the sourceLoginName is “rsmith”, the sourceUserName might be “Robert Smith”.
location: this is an optional metadata element that allows you to indicate which location the user was in who took the action. For exampe, the “rsmith” user in your CRM system might have been working in the Chicago tenant/location within your CRM application, and you want to pass along that metadata.
transactionType: this is an optional metadata element that allows you to track a specific type of transaction (a name or a code) associated with the user’s original action. For example, the new customer addition in the CRM example above might be a transaction type of “Customer onboarding”.
By tracking this additional metadata, you keep available the option to further analyze or audit data in Verato in the future. For example, you might ask the Verato support team in the future to identify the record additions made by user “rsmith”, and that request can only be met if you pass in this metadata, since the actual API user making the API requests is a generic system user.
By default, Verato tracks and reports back on the date-time information for all API activities based on the date and time the API request was received by Verato. In some cases, the date-time when the original activity occurred in your data source could be different.
This is particularly important when you export and load a large bulk set of data during your initial implementation of a Verato instance. If you provide a bulk file to Verato which contains the Source, Native ID, and attribute data values for 1 million source records, Verato’s default bulk data load process will result in a single ‘first created’ and ‘most recently updated’ date-time value for all 1 million source records, based on the date-time when the bulk data load was run. In your source systems, you like have a more accurate representation of when each of those 1 million records was last updated. If you can provide that true ‘last updated date’ in the bulk file, Verato can use that date-time value when loading the data.
This is also true for API interactions as well - when you add or update records using the Post Identity API, you can optionally pass in the date-time value that you want Verato to use for that interaction. This date-time value is the “date” value within the “sources” object.
As an example, suppose your CRM application has a customer record with a unique ID of 123 in the data source. This record was last updated on March 14, 2025 at 09:48:11. Further suppose you first send in this record to your Verato instance, whether by API or in an initial batch data load, on January 19, 2026 at 15:34:51. If you would like the data in your Verato instance to reflect that the record was last updated on March 14, 2025 at 09:48:11, then you must provide that data either in the initial data load file or in the API request you make when you first add the record.