# 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.

Where this integration workflow is enabled, the enrollment API starts recipient enrollment **before** a QeRDS notice is sent. Creating an enrollment does not complete identity verification. After successful verification, a matching identity can be reused by subsequent notices within the applicable identity context and service requirements. The recipient still follows the notice's applicable identity-confirmation and access checks. Successful enrollment in the current notice session has a distinct direct-access path; see [How a recipient receives an EviNotice](/fr/products/namirialnotify/recipient/receive-evinotice#verify-your-identity-qerds-notices).

This API is hosted separately from the main Namirial Notify API and uses a different authentication method. For issuer credentials, the qualified-submission certificate and complete notice examples, see [Integrate QeRDS notices](/fr/products/namirialnotify/dev/qerds-integration).

## Availability and prerequisites

Before using this API, confirm with your Namirial commercial contact or project manager that the registration workflow is enabled for your integration. Obtain the applicable environment URL, API key, enrollment profile and any tenant configuration during onboarding. The endpoint and example below do not establish availability of a particular provider or identification method for your account.

Calling this separate API is not a prerequisite for every QeRDS submission. An existing matching verified identity or the notice's configured enrollment flow may be used instead; see [recipient enrollment in the notice flow](/fr/products/namirialnotify/dev/qerds-integration#enable-recipient-enrollment).

### AML ID eligibility

AML ID is available only to financial institutions that have a specific agreement with Namirial, and only for the Italian qualified variant (`QERDS_IT`). This restriction covers both registering identities and reusing identities through AML ID.

Before selecting a profile, confirm with your Namirial commercial contact or project manager whether the intended flow uses AML ID and is covered by the agreement. For other identification methods, confirm availability and provisioning separately.

## 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:** Qualified EviNotice submission on the Namirial Notify API uses Basic credentials plus client-certificate authentication. This VerifID API uses its separately provided API key. See [qualified-submission setup](/fr/products/namirialnotify/dev/qerds-integration#use-the-correct-environment-and-authentication).


## 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

The profile/provider values in this example are illustrative. Use the profile and attributes provisioned for your integration; the example does not establish that the named provider or method is enabled for your account.

```http
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 creates an enrollment and returns the URL for its verification step. A `200 OK` response or a `State` of `New` is not confirmation that the recipient has been identified; the enrollment must complete successfully before the resulting identity can be reused.

| 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](/fr/products/namirialnotify/user-guides/certification-levels) — QeRDS level codes and supported jurisdictions
- [EviNotice service guide](/fr/products/namirialnotify/services/evinotice)
- [API collections](/fr/products/namirialnotify/dev/postman-collections)