# QERDS user registration API

QERDS-level EviNotice requires the recipient to complete an identity verification step before accessing the notice. The notice flow can redirect an unregistered recipient to enrollment only when the EviNotice submission enables QERDS enrollment and supplies a site-configured enrollment profile.

The enrollment API allows you to pre-register a recipient in the QERDS identity verification service **before** sending any notification. Once registered, subsequent QERDS notices sent to that recipient bypass the enrollment step and go directly to identity verification or delivery.

This API is hosted separately from the main Namirial Notify API and uses a different authentication method.

## Endpoint


```
PUT https://verifid.ecertia.com/api/v1/Enrollments
```

## Authentication

The VerifID API uses API key authentication. Include your API key in the request header on every call.


```
X-VerifID-ApiToken: <your-api-key>
```

> **Note:** This is different from the Basic authentication used by the main Namirial Notify API (`api.evicertia.com`). Your VerifID API key is provided separately by Namirial.


## Request body

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `Profile` | string | Yes | Identity verification profile. Determines which provider and method will be used to verify the user. Must match a profile configured on your site. |
| `Email` | string | Yes | Email address of the user to enroll. |
| `Phone` | string | No | Phone number of the user. Required for SMS-channel QERDS enrollments. |
| `Language` | string | No | Language preference for the enrollment UI and generated documents. Uses ISO 639-1 codes (e.g. `it`, `es`, `en`). |
| `ReturnUrl` | string | Yes | URL to redirect the user to after the enrollment completes. The result is appended as a query string — see [Return URL](#return-url) below. |
| `Grants` | string[] | No | Specific grants to request for this enrollment. When omitted, grants are determined by the profile. |
| `Tenant` | string | No | Tenant identifier. Used when multiple tenants share the same VerifID configuration. |
| `Attributes` | object | No | Additional key-value pairs required by the selected profile. Some profiles (e.g. `Bit4Id::SPIDOnly`) require `FirstName` and `LastName` to be passed here. |


### Example request


```json
PUT /api/v1/Enrollments HTTP/1.1
Host: verifid.ecertia.com
X-VerifID-ApiToken: <your-api-key>
Content-Type: application/json

{
  "Profile": "Bit4Id::SPIDOnly::Customer",
  "Email": "j.doe@example.com",
  "Language": "it",
  "ReturnUrl": "https://your-system.example.com/enroll/callback",
  "Attributes": {
    "FirstName": "John",
    "LastName": "Doe"
  }
}
```

## Response

### 200 OK

A successful request returns the enrollment record with the URL to send the user to for the verification step.

| Field | Type | Description |
|  --- | --- | --- |
| `Id` | string (UUID) | Unique identifier for the enrollment. |
| `Kinds` | string[] | Communication channels registered on the enrollment (`Email`, `Phone`). |
| `State` | string | Current state of the enrollment process. Initially `New`. |
| `EnrollUrl` | string | URL to redirect the user to in order to start the enrollment/verification process. |
| `Outcome` | string | Outcome of the enrollment process once completed. `null` when still in progress. |
| `Name` | string | First name of the user as recorded. |
| `LastName` | string | Last name of the user as recorded. |
| `DocumentNumber` | string | Document number associated with the user, if available. `null` when not yet captured. |
| `Email` | string | Email address of the user. |
| `Phone` | string | Phone number of the user, if provided. |
| `Language` | string | Language preference for the enrollment. |
| `Provider` | string | Identity provider handling the verification (e.g. `bit4id`, `uanataca`). |
| `IdentificationUrl` | string | URL to the identification provider, if available at enrollment time. |
| `ReturnUrl` | string | The return URL after the enrollment completes. |


### Example response


```json
{
  "Id": "018fa01b-1c42-4588-90da-dcaa52a8a236",
  "Kinds": ["Email"],
  "State": "New",
  "Outcome": null,
  "Name": "John",
  "LastName": "Doe",
  "DocumentNumber": null,
  "Email": "j.doe@example.com",
  "Phone": null,
  "Language": "it",
  "Provider": "bit4id",
  "IdentificationUrl": null,
  "EnrollUrl": "https://verifid.ecertia.com/enrollment/start/018fa01b-1c42-4588-90da-dcaa52a8a236",
  "ReturnUrl": "https://your-system.example.com/enroll/callback"
}
```

After receiving the response, redirect the user to `EnrollUrl` to complete the identity verification step.

## Error responses

### 400 Bad Request


```json
{
  "Type": "https://verif.id/error/-bad-request",
  "Title": "The request is invalid",
  "Details": "Bit4Id::SPIDOnly::Customer can't enroll requests with an empty lastname"
}
```

Returned when required fields are missing or invalid for the selected profile.

### 401 Unauthorized


```json
{
  "Type": "https://verif.id/error/-authn",
  "Title": "There was a problem authenticating the request",
  "Details": "Authentication failed: bad token."
}
```

Returned when the `X-VerifID-ApiToken` header is missing or the key is invalid.

### 503 Service Unavailable


```json
{
  "Type": "https://verif.id/error/-service-unavailable",
  "Title": "The server is currently unable to handle the request",
  "Details": "Problems found trying to contact with OnBoarding Today API"
}
```

Returned when the upstream identity provider is unreachable.

## Return URL

When the enrollment completes, VerifID redirects the user to your `ReturnUrl` with the result appended as query string parameters:


```
https://your-system.example.com/enroll/callback?verifidResult=<result>&verifidError=<code>
```

| Parameter | Values | Description |
|  --- | --- | --- |
| `verifidResult` | `success`, `error` | Whether the enrollment completed successfully. |
| `verifidError` | Error code string | Present only when `verifidResult` is `error`. |


### `verifidError` codes

| Code | Description |
|  --- | --- |
| `NotSupportedDocument` | Identity document provided during validation is not supported. |
| `RequestAlteredInfo` | Verification information was altered during the onboarding process. |
| `RequestIsExpired` | The enrollment request has expired. |
| `RequestInvalidInfo` | Enrollment request data is incorrect. |
| `UnexpectedFailure` | Unexpected failure while processing the enrollment. |
| `OnBoardingProviderError` | Error with the onboarding identity provider. |
| `PdfValidationError` | PDF certificate validation failed. |


## Related

- [Certification levels](/products/namirialnotify/user-guides/certification-levels) — QERDS level codes and supported jurisdictions
- [EviNotice service guide](/products/namirialnotify/services/evinotice)
- [API collections](/products/namirialnotify/dev/postman-collections)