This guide follows a qualified EviNotice from preparation and submission to recipient access and evidence retrieval. For the service and identification concepts, start with QeRDS with EviNotice.
The examples use the EviNotice v2 contract and the explicit values QERDS_ES and QERDS_IT. Use the variant enabled for your account.
Before submitting, confirm that:
- The issuing account is identity-verified, its legal-document kind is eligible for QeRDS, and its identity-verification configuration includes the intended qualified variant. These account prerequisites apply to both
QERDS_ESandQERDS_IT. See Sender identification for onboarding guidance. - You have Namirial Notify credentials and the certificate specifically issued and provisioned for qualified API submission in the intended environment.
- The email address associated with the certificate matches the issuing account's email address.
- The recipient can be identified using the information and identity context for the notice.
- If you enable enrollment during the notice flow, the enrollment profile is configured on the site and suitable for the intended variant and recipient.
- Any supplied
QERDSIdentityTenantis configured on the site for the selected variant.
Issuer identity verification and variant enablement are configured on the account during onboarding, outside the Submit JSON body. The client certificate separately authenticates the HTTPS connection for qualified API submissions.
| Environment | API base URL |
|---|---|
| Pre-production / QA | https://api.ecertia.com |
| Production | https://api.evicertia.com |
Send submissions to the API host for the environment, rather than the customer's Web site host:
POST /v2/EviNotice/SubmitQualified submission requires HTTP Basic credentials plus client-certificate authentication. Configure your HTTPS client with the certificate issued for this API use; the certificate is part of the connection configuration, not a field in the JSON body. Confirm the supplied certificate format and supported client setup during provisioning.
Request the certificate through your Namirial commercial contact or project manager. Have the company name, contact email and mobile number, issuing account email, site URL and intended environment available so the certificate can be provisioned for the correct issuer and site.
The certificate must be associated with the site and authorized issuing account. Test and production certificates are managed separately; use the certificate supplied for the environment you are calling. Its email must match the issuer used in Basic authentication.
This certificate authenticates the issuer's API connection. Service qualification and the certificates used in a recipient's identification or signing process have distinct roles.
For a supplied password-protected PKCS#12 (.p12) bundle, configure the HTTPS client's certificate file and password. Check that the client supports the supplied format and retains any certificate chain needed by the connection.
The following interactive example uses a curl/TLS backend that can load P12 files directly. Set NOTIFY_ISSUER_EMAIL to the issuing account, QERDS_P12_FILE to the bundle path and NOTICE_IDEMPOTENCY_TOKEN to the token for this logical submission. Save the Spanish request body below, with matching test-recipient details, as qerds-es.json.
curl --request POST \
--user "$NOTIFY_ISSUER_EMAIL" \
--cert-type P12 \
--cert "$QERDS_P12_FILE" \
--header 'Content-Type: application/json' \
--header "X-Evi-IdempotencyToken: $NOTICE_IDEMPOTENCY_TOKEN" \
--data-binary @qerds-es.json \
'https://api.ecertia.com/v2/EviNotice/Submit'Enter the account and certificate passwords when prompted. For the Italian request, use the corresponding qerds-it.json body and a new token for that distinct notice. Reuse a token only when retrying the same logical submission.
Certificate handling depends on the client:
- A TLS backend that uses a certificate store, such as Windows Schannel, needs its supported store configuration instead of the direct P12 file argument.
- In the certificate-file portion of curl's
--certargument, escape a literal colon as\:so it is not treated as the password separator. Preserve that escape when quoting the argument in your shell. - For unattended jobs, use your HTTP client's protected credential/keystore configuration or a curl configuration file restricted to the integration account. Keep passwords out of command-line arguments.
- If an OpenSSL-based client cannot load an older P12 bundle using legacy encryption, ask the certificate provider for a compatible re-export. See the OpenSSL PKCS#12 guidance.
See the curl client-certificate options and follow the setup supplied for your integration client.
The separate VerifID enrollment API uses its own API key. That key does not replace the credentials or certificate used to submit the EviNotice. See QeRDS user registration API.
Both variants require RecipientLegalIdRequired: true.
| Notification destination | QERDS_ES | QERDS_IT |
|---|---|---|
DeliverySignMethod: EmailPin; DeliverySignFixedEmail equals RecipientAddress | DeliverySignMethod: MobilePin; supply the recipient's valid DeliverySignFixedMobile | |
| Mobile | DeliverySignMethod: MobilePin; DeliverySignFixedMobile equals RecipientAddress | DeliverySignMethod: EmailPin; supply the recipient's valid DeliverySignFixedEmail |
| Legal document | Supply document kind and value together for confirmation, or omit both so the recipient provides them | RecipientLegalIdKind and RecipientLegalIdValue are required and must validate together |
For the Spanish variant, use identical values in RecipientAddress and the fixed PIN destination. Write email addresses in lowercase without surrounding spaces and mobile numbers in the same E.164 form, such as +34600000000.
Identification remains mandatory when enrollment is disabled. Set QERDSEnrollmentAllowed: false only when the recipient already has a verified identity available to the notice's identity context.
The qualified requirements below apply in addition to the generic Submit fields Subject, Body and RecipientAddress. The generic schema's required-field list alone does not describe all QeRDS validation. See the full EviNotice request schema for the other submission options.
| Field | Type | Use in a qualified request |
|---|---|---|
CertificationLevel | string | Select the account-enabled variant, QERDS_ES or QERDS_IT, explicitly. |
AffidavitKinds | array of strings | Include both SubmittedAdvanced and Read, or include CompleteAdvanced. Additional kinds can be requested. |
EvidenceAccessControlMethod | string | Set Public explicitly for both qualified variants. This controls access to the evidence record; recipient identification for the hosted notice remains required. |
RecipientLegalIdRequired | boolean | Must be true for both variants, including recipients who are already identified. |
RecipientLegalIdKind | string | Legal-document kind recognized by the service and suitable for the configured identity flow. Send it together with RecipientLegalIdValue; both are mandatory for QERDS_IT. For QERDS_ES, supply both or omit both. |
RecipientLegalIdValue | string | The matching recipient's document number. It must be valid for the selected kind; the Italian variant validates the pair at submission. |
QERDSEnrollmentAllowed | boolean | Set to true to allow enrollment when no matching verified identity is found. Omitting it does not enable enrollment. Setting it to false still requires an existing matching verified identity for access. |
QERDSEnrollmentProfile | string | Required when enrollment is enabled. Any supplied non-empty profile must match a profile configured on the site, even when enrollment is disabled. |
QERDSIdentityTenant | string | Optional identity context used for recipient identity lookup and in-notice enrollment. When supplied, it must exactly match a tenant configured on the site for the selected certification variant. Obtain the appropriate value during provisioning. |
CommitmentChoice | string | Optional recipient acceptance/rejection action; the API default is Disabled. To collect recipient comments, use Reject. |
CommitmentCommentsAllowed | boolean | Keep disabled when CommitmentChoice is Accept or AcceptOrReject. To collect comments on a qualified notice, set CommitmentChoice: Reject and enable this field. |
DeliverySignMethod | string | Set EmailPin or MobilePin according to the ES/IT routing table above. |
DeliverySignFixedEmail | string | Required for the qualified EmailPin path and used only with that method. It must match RecipientAddress for an ES email notice; for an IT mobile notice it is the recipient's separate email destination. |
DeliverySignFixedMobile | string | Required for the qualified MobilePin path and used only with that method. It must match RecipientAddress for an ES mobile notice; for an IT email notice it is the recipient's separate mobile destination. |
NotificationChannels | array of strings | Routes the notice alert. When omitted, email recipients use Email and mobile recipients use SMS. This is separate from the PIN-delivery channels. |
MobilePinChannels | array of arrays of strings | Optional, only with DeliverySignMethod: MobilePin. Configures three non-empty PIN-delivery attempt groups. See Mobile PIN channels for canonical values, defaults and enablement requirements. |
For QeRDS acceptance, comments and acceptance reasons are unavailable. Leave AcceptReasons unset and RequireAcceptReason false or omitted. Rejection reasons can be configured with CommitmentChoice: Reject and CommitmentCommentsAllowed: true.
Document-kind identifiers such as IDC:ES, PAS:ES and TIN:IT are case-sensitive examples, not an exhaustive list. The service validates the identifier and document value. Confirm the kinds supported by the target environment and the configured identity flow; a recognized document kind does not by itself establish that a particular identification method is available.
QERDSIdentityTenant selects the identity context used to look up the recipient's verified identity and, when in-notice enrollment runs, to create it. The same context is recorded with the recipient's QeRDS service-terms acceptance. QERDSEnrollmentProfile selects the process offered if a new enrollment is needed. These are separate settings; one does not replace the other.
If Namirial has provisioned a tenant for the integration, add its actual identifier to the appropriate complete request below:
{
"QERDSIdentityTenant": "<PROVISIONED_IDENTITY_TENANT>"
}This is a request fragment, not a complete submission. Replace the placeholder with the tenant configured for the requested variant. The API does not require this field on every qualified request; confirm the intended identity context during provisioning rather than assuming that omitting it selects a site-specific tenant.
To allow a new recipient to enroll during the notice flow, replace QERDSEnrollmentAllowed: false in either complete request below with the following fields:
{
"QERDSEnrollmentAllowed": true,
"QERDSEnrollmentProfile": "<PROVISIONED_ENROLLMENT_PROFILE>"
}This fragment is merged into the complete request; it is not a separate API call. Replace the profile placeholder with the actual site-configured profile for the intended variant and recipient. The site must have that profile configured before submission. If the integration also uses a provisioned QERDSIdentityTenant, retain it in the same request. Do not copy a provider/profile or tenant identifier from another account's example.
The remaining qualified requirements still apply, including the Italian variant's legal-document pair and the appropriate PIN destination. A supplied profile is validated against the site even when QERDSEnrollmentAllowed is false.
If the selected identification method is AML ID, both registration and identity reuse are limited to QERDS_IT and to financial institutions with a specific agreement with Namirial. Enabling enrollment does not remove these conditions. See AML ID eligibility.
Successful matching enrollment during the same recipient session can give direct access. Failed enrollment or an identity that does not match the notice leaves access blocked until the issuer resolves the requirement. See the recipient identification flow.
This example uses email notification and an already identified recipient. Replace the example contact details with those of an authorized test recipient whose verified identity is available to the configured service.
Configure the client certificate on the HTTPS connection, then send:
POST /v2/EviNotice/Submit HTTP/1.1
Host: api.ecertia.com
Authorization: Basic <base64(issuer-email:password)>
Content-Type: application/json
X-Evi-IdempotencyToken: 5f19c728-e17c-4f2e-86fd-b915523cbe02{
"LookupKey": "QERDS-ES-EXAMPLE-001",
"Subject": "Document available for review",
"Body": "<p>Please review the communication on this secure page.</p>",
"RecipientAddress": "recipient@example.com",
"RecipientDisplayName": "Example Recipient",
"IssuerLegalName": "Example Organisation",
"CertificationLevel": "QERDS_ES",
"RecipientLegalIdRequired": true,
"QERDSEnrollmentAllowed": false,
"NotificationChannels": ["Email"],
"DeliverySignMethod": "EmailPin",
"DeliverySignFixedEmail": "recipient@example.com",
"EvidenceAccessControlMethod": "Public",
"AffidavitKinds": ["SubmittedAdvanced", "Dispatched", "DeliveryResult", "Read", "Closed"]
}The recipient opens the email link and completes the identity confirmation and applicable notice-access steps. If no matching verified identity is available, this example does not enroll the recipient; the issuer must resolve that requirement.
This example also uses an already identified recipient. The notification goes to email and the access PIN goes to mobile. This template uses the recipient's Italian Codice Fiscale (TIN:IT). Replace the example contacts and placeholder with the matching data of the authorized recipient. Supply the valid 16-character Codice Fiscale corresponding to the verified identity; the service checks its format and checksum.
Use the same v2 endpoint and authentication setup as above, with a new idempotency token for this distinct notice:
{
"LookupKey": "QERDS-IT-EXAMPLE-001",
"Subject": "Document available for review",
"Body": "<p>Please review the communication on this secure page.</p>",
"RecipientAddress": "recipient@example.com",
"RecipientDisplayName": "Example Recipient",
"IssuerLegalName": "Example Organisation",
"CertificationLevel": "QERDS_IT",
"RecipientLegalIdRequired": true,
"RecipientLegalIdKind": "TIN:IT",
"RecipientLegalIdValue": "<RECIPIENT_CODICE_FISCALE>",
"QERDSEnrollmentAllowed": false,
"NotificationChannels": ["Email"],
"DeliverySignMethod": "MobilePin",
"DeliverySignFixedMobile": "+390000000000",
"EvidenceAccessControlMethod": "Public",
"AffidavitKinds": ["SubmittedAdvanced", "Dispatched", "DeliveryResult", "Read", "Closed"]
}The recipient needs access to both the notification email address and the configured mobile number. The issuer must have the Italian qualified configuration enabled before using this request. With this explicit MobilePin method and no MobilePinChannels, PIN delivery defaults to three SMS attempt groups; see Mobile PIN channels to configure another enabled channel combination.
A successful new submission returns 200 OK with the notice ID:
{
"Id": "9f3e1a02-b74c-4d8e-91c5-f00012345678"
}Persist Id, your LookupKey, the environment and the idempotency token. Use the same token when retrying the same logical submission; a replay of a previously successful request returns 202 Accepted with the original response body.
A 409 Conflict response means another submission with the same token is still in flight. Wait before retrying the same logical request with the same token; do not create a new token merely to bypass the conflict.
Submission acceptance means the API accepted the notice. It does not establish that the recipient has completed identification, received the notification or read the content.
Qualified notices use the existing EviNotice v2 operations. The additional certificate prerequisite described in this guide applies to qualified Submit; it does not create separate QeRDS endpoints.
| Purpose | Operation | Main request fields and result |
|---|---|---|
| Submit one notice | POST /v2/EviNotice/Submit | The qualified request fields apply alongside the generic request fields. A successful submission returns the notice Id. |
| Retrieve one notice | GET /v2/EviNotice/{Id} | Supply the notice Id. Use IncludeAffidavits / IncludeAttachments for the corresponding metadata. |
| Find notices and track progress | POST /v2/EviNotice/Query | Filters include Owner, LookupKeys, LinkedId, State and Outcome, with Limit / Cursor for pagination. The response contains Cursor and Results. |
| Request additional evidence | POST /v2/EviNotice/Affidavits/Request | Supply the notice Id; optional flags are IncludeBody, IncludeAttachments and IncludeEvents. The original submission must include OnDemand in AffidavitKinds, and the notice must still be eligible. The response's RequestId identifies the generation request. |
| Download one affidavit | GET /v2/EviNotice/Affidavits/{Id} | Supply the affidavit Id, not the notice ID. Returns a PDF. |
| Download all notice affidavits | GET /v2/EviNotice/{Id}/Affidavits | Supply the notice Id. Returns the available affidavits in a ZIP archive. |
| Download notice attachments | GET /v2/EviNotice/{Id}/Attachments | Supply the notice Id. Returns the attachments in a ZIP archive. |
Get and Query use their own response schemas; they do not echo all Submit settings. In particular, the v2 responses do not return QERDSEnrollmentAllowed, QERDSEnrollmentProfile, QERDSIdentityTenant or the RecipientLegalId* settings. Keep the submitted configuration in your integration if you need it later. See the complete request and response schemas.
The separate recipient registration API is an enrollment interface, not an additional step required for every Submit call. Confirm whether that workflow applies to your integration before using it.
The table covers single-notice operations. Batch resources and shared ID-based downloads have separate references; the qualified examples in this guide do not validate a batch-submission workflow.
- The recipient opens the notification link, completes the required identity steps and accepts any pending QeRDS service terms/privacy conditions. Existing identities and new enrollment have different paths; see How a recipient receives an EviNotice.
- Use callbacks if your application needs asynchronous updates. Configure a reachable callback URL and the events your process consumes.
- Reconcile the notice using Get or Query. Keep notification delivery, hosted-notice access and reading distinct when interpreting progress.
- Retrieve affidavit metadata and download the available evidence using the EviNotice API reference. See Evidence and affidavits for interpretation.
The API reference documents Basic authentication for Get, Query and evidence downloads. The additional client-certificate prerequisite described here is for qualified Submit; confirm any environment-specific connection requirements with Namirial during provisioning.
| Check | What to verify |
|---|---|
| Certificate authentication | The supplied certificate is configured on the HTTPS client for the intended environment and associated with the issuer/site. |
| Certificate and issuer mismatch | The certificate's email matches the account used in Basic authentication. |
| Qualified variant unavailable | The issuer is identity-verified, its legal-document kind is eligible for QeRDS, and its identity-verification configuration includes the selected variant, for both ES and IT. |
| Affidavit kinds rejected | Include SubmittedAdvanced and Read, or CompleteAdvanced, in AffidavitKinds. |
| Evidence access rejected | Set EvidenceAccessControlMethod: Public explicitly. |
| Commitment comments rejected | Keep comments disabled for Accept and AcceptOrReject; use Reject when collecting comments or rejection reasons. |
| Enrollment unavailable | Enrollment is enabled in the request when needed and the selected profile is configured on the site. |
| Identity or document mismatch | Contact details, document kind/value and any supplied identity tenant refer to the intended verified recipient. |
| PIN destination | The destination follows the ES same-channel or IT cross-channel requirements. |
Use the returned Problem+JSON details and request ID when investigating an error. For response formats and shared handling, see EviNotice API errors and Error handling.