Guide to synchronising profile data with your system data

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.

This developer guide takes you through the steps to use the Collected data updated webhook and update a profile's collected data in PassFort API 4.0.

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.

To enable to the webhook to send callbacks:

  1. Go to Manage account > Webhook config.
  2. Ensure Webhooks enabled is selected.
  3. Ensure the Shared secret field contains the Secret you’re using.
  4. Ensure the Endpoint field contains the endpoint you want to receive callbacks.
  5. Select Collected data updated.
  6. Click Save. Any time a profile’s collected_data changes, a callback is sent to the endpoint you specified.

Callbacks from this webhook have three key parts:

  • data.old_data: This object contains the information that was in the profile’s collected_data before it was changed.
  • data.new_data: This object contains the information that is in the profile’s collected_data after the changes.
  • data.profile_id: This field contains the profile ID of the profile that was changed.

In this example, a date of birth was added to an individual profile.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "COLLECTED_DATA_UPDATED",
"secret": "yourSecret",
"timestamp": 1567009086,
"data": {
"apikey": {
"name": "API Key Name"
},
"customer_ref": null,
"new_data": {
"entity_type": "INDIVIDUAL",
"personal_details": {
"dob": "1975-04-19",
"name": {
"family_name": "Wheeler",
"given_names": [
"Alex",
"D"
]
}
}
},
"old_data": {
"contact_details": {},
"entity_type": "INDIVIDUAL",
"personal_details": {
"name": {
"family_name": "Wheeler",
"given_names": [
"Alex",
"D"
]
}
}
},
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
"user": null
}
}

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.

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

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.

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.
Some additional fields 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?