Historical update

As soon as your employment link is created (for SAT Mexico), we asynchronously calculate the employment metrics for the link and will send you the following webhook:

In the webhook payload we include the number of bills found for the link.

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENT_RECORDS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_employment_record_profiles": 1 // The total number of employment record profiles found for the link
  }
}

Once you receive the notification, you can get further details by making the following request:

curl --request GET 'https://api.belvo.com/api/employment-metrics/?link=link_id' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Employment status changes

📘

Interested in accessing this new feature?

Reach out to our team, and they’ll help you get set up!

According to your chosen refresh rate, Belvo will asynchronously retrieve data about any new changes in employment that have appeared for the given link since the last update.

In the webhook payload we include the employment changes identified for the link.

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENT_RECORDS",
  "process_type": "recurrent_update",
  "webhook_code": "employment_changes",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "employment_changes": ["EMPLOYED", "SALARY_INCREASED"] // List of changes since the last check
  }
}

Once you receive the notification, you can get further details by making the following request:

curl --request GET 'https://api.belvo.com/api/employment-records/?link=link_id' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Employment change options

At your given refresh frequency, Belvo will extract new employment information for your link and compare the employment status and salary information with the previous data extraction.

📘

Recommended refresh frequency

We recommend a refresh frequency of a minimum of two months. However, reach out to our team and they'll be able to advise you better depending on your use case.

In the data.employment_changes array of the webhook, you can receive one or more of the following employment changes:

You can receive more than one change in the data.employment_changes array, depending on the situation. For example, if a person changed jobs and is now receiving a higher salary, then in the data.employment_changes array you will receive:

{
  "data": {
    "employment_changes": ["EMPLOYEE_CHANGED_JOBS", "SALARY_INCREASE"]
  }
}

Scenarios with deleted or missing records

Belvo sends employment notifications after comparing the newly retrieved data against previously-retrieved data. However, there can be cases where we update an employment link that does not have any employment record data in Belvo's database. In these cases, you will still receive an employment_changes webhook. However, as Belvo checks the newly returned data against non-existing data in Belvo's database, in this case you will receive one of the following combinations of employment changes:

This can occur due to any of the following reasons:

On link creation, you set stale_in to a period that is less than your refresh rate.

When creating a link, you can optionally add the stale_in parameter to control how long Belvo stores user-derived data. The period is relative to the link’s last_updated_at (the last time that the user’s account was accessed) timestamp.

📘

For example, if you set stale_in to 62 days when you created a link on 01.03.2024, the data is stored in Belvo's database for 62 days after this date. If then for the same link you accessed the data a month later (01.04.2024), then the count is reset and Belvo will delete the data 62 days after 01.04.2024.

However, if you set a stale_in period to less than your refresh rate, Belvo will delete the data before the next refresh. As a result, the newly returned data will be compared against non-existent data, triggering an employment_changes webhook with the statuses mentioned above.

To avoid this, either:

• Do not pass the stale_in parameter (which by default is 365 days).
• Set a stale_in value that is greater than your refresh rate. For example, if you have a refresh period of 60 days, then your stale_in parameter should be set to at least 62 days.

When doing a POST Retrieve employment records, you set save_data to false.

When retrieving employment record data using the Retrieve employment record details, setting save_data to false prevents Belvo from storing the data. Consequently, any newly retrieved data will be compared against non-existent data, resulting in the employment_changes webhook mentioned above.

To avoid this, we recommend that you set save_data to true.

Deleted employment record data

If you delete employment record data using the Delete an employment record request, all data for that employment entry is removed from Belvo's database. During the next update, Belvo compares the new data against the deleted (non-existing) data, resulting in the employment_changes webhook mentioned above.

There was no data in the initial extraction of employment record data

In the case that a previous employment record retrieval was not successful as there was no data for the user in the institution (resulting in the API returning an empty response) or the employment institution was unresponsive, during the next update, Belvo compares the new data against the non-existing data, resulting in the employment_changes webhook mentioned above.