Historical update

As soon as your banking recurrent link is created, we asynchronously load the employment information available for the link and will send you the following webhook:

Webhook Code	Description
historical_update	The total number of employments found for the link.

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

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENTS",
  "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_employments": 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/co/employments/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Query Parameter	Description	Example
`link`	The `link_id` you received in the webhook notification.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

👍
For details about the response body, make sure to check out our List Employments (Colombia) API reference documentation or Employment (Colombia) Data Dictionary.

New employments available

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

Webhook Code	Description
`new_accounts_available`	The number of new employments found since the last update.

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

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENTS",
  "process_type": "recurrent_update",
  "webhook_code": "new_employments_available",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_employments": 1 // Number of new employments found since last event
  }
}

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

curl --request GET 'https://api.belvo.com/api/co/employments/?link={id}&created_at__range=date1,date2' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Query Parameter	Description	Example
`link`	The `link_id` you received in the webhook notification.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`created_at__range`	The date range you want to receive employments for. We recommend that `date1` is the date when you previously received a notification and `date2` is the date when you receive the current notification (both in `YYYY-MM-DD` format).	`2024-05-01,2024-06-01`