Sync profile data with your system data (API)

After a profile is created, it’s best practice to make sure the data in your systems and the data in PassFort matches.

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 (e.g. a drivers license used for a Verify identity or Verify address check) are stored in collected data.

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. You should get the latest ETag by making a GET request to the collected_data endpoint described below in step 1, and try the POST request again.

We strongly recommend using ETags whenever possible to ensure data is not overwritten. However, to ensure PassFort is backwards 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 below in step 1.

Update your system data when PassFort's profile data changes

Use the Collected data updated webhook to receive a notification any time a profile’s collected_data changes in PassFort.

The webhook callback contains a copy of the new data and the old data so you can see what's changed.

Use the callback 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.

1. Get the existing collected data

Make a request to the endpoint below.

Request endpoint:

GET https://api.passfort.com/4.0/profiles/{profile_id}/collected_data

The 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 (e.g. W/"1579973191.798") so you can return it in step 3.

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"
}
}

2. 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.

3. Send the modified data

Pass the updated data back using the request endpoint below.

In the header of the request, include a parameter called If-Match with the value of the ETag you obtained in step 1.

For example: If-Match: W/"1579973191.798"

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/collected_data

The 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. You should get the latest ETag by making a GET request to the collected_data endpoint described in step 1, and try the POST request again.

When you update a profile's collected_data by sending the request above, the Collected data updated webhook sends a callback 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 callback 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 callback from the Collected data updated 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 (e.g. original_structured_address).
Example: Individual profile

In this example, we’ll add a date of birth to the individual profile in the example above.

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 example above.

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.


How did we do?


Powered by HelpDocs (opens in a new tab)