Webhooks

Webhooks are an alternative to frequent polling. When the verification of a contractor is complete, we send a POST call with the full result – so you do not have to spend your rate limit budget on repeated queries.

Note

The callback URL is set in the API settings in the Web Panel. Your endpoint should respond quickly with 2XX and do the actual processing asynchronously.

employee.verified

WEBHOOKemployee.verified

Verification completed

Sent when a contractor has completed ID verification, or when the result changes to a terminal state. id_verification_detail has the same structure as in GET /users/{id}.

Fields

Field	Type	Description
`id`	`integer`	User ID at EasyFreelance.
`email`	`string`	The contractor's email address.
`internal_id`	`integer` / `null`	Your own ID, if set.
`status`	`string`	`Verified`, `Incomplete`, `Not verified` or `Error`.
`verification_status`	`string` / `null`	Status of the entity verification, for example `approved`.
`verification_provider`	`string` / `null`	`BankID` or `ID`.
`verification_id`	`uuid` / `null`	The session the event relates to.
`onboarding`	`object`	Onboarding status v2.
`id_verification_detail`	`object`	Detailed result of the identity verification.

Status values

status	Meaning
`Verified`	The session was approved, and the identity is complete.
`Incomplete`	The session is incomplete, or the entity was approved without a complete identity.
`Error`	Error during processing – for example a duplicate national identity number.
`Not verified`	Declined, expired or other outcomes.

Example

POST to your callback URL

{
  "id": 123,
  "email": "[email protected]",
  "internal_id": 456,
  "status": "Error",
  "verification_status": null,
  "verification_provider": null,
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "onboarding": {
    "is_onboarded": false,
    "missing_steps": [
      "id_verification"
    ],
    "steps": {
      "email_verified": true,
      "terms_approved": true,
      "profile": true,
      "id_verification": false,
      "bank_account": false
    },
    "status_version": "v2",
    "evaluated_at": "2026-07-08T12:00:00+00:00"
  },
  "id_verification_detail": {
    "complete": false,
    "entity_status": null,
    "provider": "BankID",
    "missing_fields": [],
    "reason_codes": [
      "ssn_duplicate"
    ],
    "partner_instructions": [
      {
        "code": "contact_support",
        "message": "Verification stopped: national ID number already exists in the system."
      }
    ]
  }
}

Practical advice

Treat the webhook as a signal, not as the source of truth: retrieve GET /users/{id} afterwards if you need the latest state.
Be prepared to receive the same event more than once. Use verification_id to recognise duplicates.
Feel free to combine the webhook with low-frequency polling as a safety net, in case a call does not come through.

Getting started

Flows