Sync profile data with your system data in the API
After a profile is created, it’s best practice to make sure the data in your systems and the data in Passfort match. If profile data changes in Passfort, you should update your system data. Likewise, if your system data about a profile changes, you should send the updates to Passfort.
A profile's documents, for example, a driver's license or passport, are stored in collected data.
If you've updated the data used for the profile's due diligence checks, you may wish to run these checks again.
What are ETags?
Passfort uses ETags to ensure the latest information in Passfort is never overwritten.
One Etag corresponds to a version of the data. It looks something like this: W/"1579973191.798".
When you GET profile data, the ETag corresponding to the latest version of the data is returned in the header. The field in the header is called Etag.
When you make a POST request, you should include the latest ETag in the header of the request. The field you need to include in the header is called If-Match.
If the ETag you send in the POST request matches the latest ETag, the profile data will be updated with the data from your request body. The response from the POST request has a new ETag in its header because the data has been updated.
If the ETag doesn't match, the response returns a 412 Precondition Failed status and the response body contains the latest profile data, without the changes from your request. Get the latest ETag from the 412 response and try the POST request again.
Warning
Passfort strongly recommends using ETags whenever possible to ensure data is not overwritten. However, to ensure Passfort is backward compatible, if you do not send an ETag in the header, the request will be processed and a 200 status will be returned.
If you want to find out what the latest ETag is, you can always make a GET request to the collected_endpoint described in Get the existing collected data.
Update your system data when Passfort's profile data changes
Use the collected data update or collected data changed webhook to receive a notification any time a profile’s collected_data changes in Passfort.
The webhook payload contains a copy of the new data and the old data so you can see what's changed.
Use the payload to compare the information contained in data.new_data with the information in your system, and update your system if required.
Update Passfort's profile data when your system data changes
To update a profile, send a request to get its collected_data, then post the collected_data back to the profile with any amendments.
Get the existing collected data
Make a request to the following endpoint:
Request endpoint:
GET https://api.passfort.com/4.0/profiles/{profile_id}/collected_dataThe response returns everything that currently exists in the profile’s collected_data. Copy the entire response body. You’ll need this for the next step.
The response also returns a header called Etag. Copy the value, for example, W/"1579973191.798", so you can return it in Send the modified data.
It’s important to copy the entire response body because when you post back, you must send everything you want to keep in collected_data. It’s not possible to update specific fields.
Example: Individual profile
In this example, an individual profile for someone named Alex D Wheeler is returned. The only information the profile contains is the company name.
Sample response:
{
"entity_type": "INDIVIDUAL",
"personal_details": {
"name": {
"family_name": "Wheeler",
"given_names": [
"Alex",
"D"
]
}
}
}Example: Company profile
In this example, a company profile for Passfort Limited is returned. The only information it contains is the name, a company number, and a country of incorporation.
Sample response:
{
"entity_type": "COMPANY",
"metadata": {
"country_of_incorporation": "GBR",
"name": "Passfort Limited",
"number": "09565115"
}
}Modify the data
Take the response you copied in the first step. You can make these changes:
Add or remove any of the optional fields.
Modify the values for any of the optional or required fields.
All required and optional keys for collected_data are listed in the Create a profile developer resources.
Passfort does not have any character limitations for profile data unless otherwise specified in the API reference. However, your data provider may specify their own limitations for the data when it's used to run checks. Contact your data provider to find out more.
Send the modified data
Pass the updated data back using the following request endpoint.
In the header of the request, include a parameter called If-Match with the value of the ETag you obtained in Get the existing collected data.
For example If-Match: W/"1579973191.798"
Request endpoint:
POST https://api.passfort.com/4.0/profiles/{profile_id}/collected_dataThe profile is updated and the response returns everything that currently exists in the profile’s collected_data after the updates. Confirm it matches what you sent.
The response also includes the new ETag in a header parameter called Etag.
Note that if the ETag doesn't match, the response returns a 412 Precondition Failed status and the response body contains the latest profile data, without the changes from your request. Get the latest ETag from the 412 response and try the POST request again.
When you update a profile's collected_data by sending the preceding request, the Collected data updated/changed webhook sends a payload to say that a profile's data has been updated. If you’re using the Collected data updated webhook, make sure you only act on the payload when it shows that the data returned does not match the data in your systems. Otherwise, you may end up with an endless loop where your system updates Passfort, receives a notification from the Collected data updated webhook, and tries to act on data it has just sent.
One way to distinguish between whether the collected_data was updated by the user or via the portal is to look at the payload from the collected data updated or collected data changed event. If the user parameter is an object, a user updated the profile. If the value is null, the profile was updated via the API. Some additional keys may be added to the profile's collected_data automatically, for example, original_structured_address.
Example: Individual profile
In this example, we’ll add a date of birth to the individual profile in the previous example.
Sample request body:
{
"entity_type": "INDIVIDUAL",
"personal_details": {
"dob": "1975-04-19",
"name": {
"family_name": "Wheeler",
"given_names": [
"Alex",
"D"
]
}
}
}In this case, the response is identical to the request.
Example: Company profile
In this example, we’ll add a date of incorporation to the company profile in the previous example.
Sample request body:
{
"entity_type": "COMPANY",
"metadata": {
"country_of_incorporation": "GBR",
"incorporation_date": "2010-10-02",
"name": "Passfort Limited",
"number": "09565115"
}
}In this case, the response is identical to the request.