Skip to content

Diia authorization

Request

Use this endpoint to identify the applicant through the Diia app. The applicant confirms the authorization in the Diia app, and our system gets the full name and the tax ID number (RNOKPP) of the applicant.

How it works

  1. You send a request with the ID of a form that has Diia settings.
  2. Our system returns confirmation_url. This is a deep link to the Diia app.
  3. You show the link to the applicant. The applicant opens it and confirms the authorization in Diia.
  4. Our system updates the applicant profile (or creates a new applicant), adds the tax ID number document, and sends the "UA Diia auth completed" callback to the callback URL of the form.

If you do not send applicant_id, our system creates a new applicant after the authorization. The response contains the ID that this applicant will get.

Our system charges the request after the applicant completes the authorization.

Security
API-Key
Bodyapplication/jsonrequired
form_idstringrequired

ID of the form that has Diia settings

Example:"a1b2c3d4e5f60718293a4b5c6d7e8f901234"
applicant_idstring

Optional. ID of an existing applicant

Example:"0f1e2d3c4b5a69788796a5b4c3d2e1f00123"
external_applicant_idstring

Optional. Your ID of the applicant. Our system uses it when it creates a new applicant

Example:"user-10001"
redirect_urlstring, <= 2048 characters

Optional. URL that Diia opens after the authorization. If you do not send it, our system uses the redirect URL of the form

Example:"https://example.com/diia/done"
{
  "form_id": "a1b2c3d4e5f60718293a4b5c6d7e8f901234",
  "external_applicant_id": "user-10001"
}

Responses

OK

The request was processed. Check the status field: when our system cannot create a Diia session or a deep link, it returns 200 with status set to error.

Bodyapplication/json
One of:
statusstring
Example:"ok"
dataobject
Response
{
  "status": "ok",
  "data": {
    "applicant_id": "0f1e2d3c4b5a69788796a5b4c3d2e1f00123",
    "confirmation_url": "https://diia.example.com/deep-link/00000000"
  }
}