Skip to content

Integrate QeRDS notices

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.

Prepare the integration

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_ES and QERDS_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 QERDSIdentityTenant is 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.

Use the correct environment and authentication

EnvironmentAPI base URL
Pre-production / QAhttps://api.ecertia.com
Productionhttps://api.evicertia.com

Send submissions to the API host for the environment, rather than the customer's Web site host:

POST /v2/EviNotice/Submit

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

Configure a PKCS#12 certificate

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 --cert argument, 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.

Choose the variant and recipient path

Both variants require RecipientLegalIdRequired: true.

Notification destinationQERDS_ESQERDS_IT
EmailDeliverySignMethod: EmailPin; DeliverySignFixedEmail equals RecipientAddressDeliverySignMethod: MobilePin; supply the recipient's valid DeliverySignFixedMobile
MobileDeliverySignMethod: MobilePin; DeliverySignFixedMobile equals RecipientAddressDeliverySignMethod: EmailPin; supply the recipient's valid DeliverySignFixedEmail
Legal documentSupply document kind and value together for confirmation, or omit both so the recipient provides themRecipientLegalIdKind 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.

QeRDS request fields

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.

FieldTypeUse in a qualified request
CertificationLevelstringSelect the account-enabled variant, QERDS_ES or QERDS_IT, explicitly.
AffidavitKindsarray of stringsInclude both SubmittedAdvanced and Read, or include CompleteAdvanced. Additional kinds can be requested.
EvidenceAccessControlMethodstringSet Public explicitly for both qualified variants. This controls access to the evidence record; recipient identification for the hosted notice remains required.
RecipientLegalIdRequiredbooleanMust be true for both variants, including recipients who are already identified.
RecipientLegalIdKindstringLegal-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.
RecipientLegalIdValuestringThe matching recipient's document number. It must be valid for the selected kind; the Italian variant validates the pair at submission.
QERDSEnrollmentAllowedbooleanSet 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.
QERDSEnrollmentProfilestringRequired when enrollment is enabled. Any supplied non-empty profile must match a profile configured on the site, even when enrollment is disabled.
QERDSIdentityTenantstringOptional 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.
CommitmentChoicestringOptional recipient acceptance/rejection action; the API default is Disabled. To collect recipient comments, use Reject.
CommitmentCommentsAllowedbooleanKeep disabled when CommitmentChoice is Accept or AcceptOrReject. To collect comments on a qualified notice, set CommitmentChoice: Reject and enable this field.
DeliverySignMethodstringSet EmailPin or MobilePin according to the ES/IT routing table above.
DeliverySignFixedEmailstringRequired 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.
DeliverySignFixedMobilestringRequired 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.
NotificationChannelsarray of stringsRoutes the notice alert. When omitted, email recipients use Email and mobile recipients use SMS. This is separate from the PIN-delivery channels.
MobilePinChannelsarray of arrays of stringsOptional, 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.

Select the identity tenant

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.

Enable recipient enrollment

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.

Submit a Spanish-variant notice

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.

Submit an Italian-variant notice

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.

Store the submission result

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.

Follow recipient access and retrieve evidence

API operations for a qualified notice

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.

PurposeOperationMain request fields and result
Submit one noticePOST /v2/EviNotice/SubmitThe qualified request fields apply alongside the generic request fields. A successful submission returns the notice Id.
Retrieve one noticeGET /v2/EviNotice/{Id}Supply the notice Id. Use IncludeAffidavits / IncludeAttachments for the corresponding metadata.
Find notices and track progressPOST /v2/EviNotice/QueryFilters include Owner, LookupKeys, LinkedId, State and Outcome, with Limit / Cursor for pagination. The response contains Cursor and Results.
Request additional evidencePOST /v2/EviNotice/Affidavits/RequestSupply 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 affidavitGET /v2/EviNotice/Affidavits/{Id}Supply the affidavit Id, not the notice ID. Returns a PDF.
Download all notice affidavitsGET /v2/EviNotice/{Id}/AffidavitsSupply the notice Id. Returns the available affidavits in a ZIP archive.
Download notice attachmentsGET /v2/EviNotice/{Id}/AttachmentsSupply 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.

Track recipient access and evidence

  1. 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.
  2. Use callbacks if your application needs asynchronous updates. Configure a reachable callback URL and the events your process consumes.
  3. Reconcile the notice using Get or Query. Keep notification delivery, hosted-notice access and reading distinct when interpreting progress.
  4. 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.

Resolve prerequisite failures

CheckWhat to verify
Certificate authenticationThe supplied certificate is configured on the HTTPS client for the intended environment and associated with the issuer/site.
Certificate and issuer mismatchThe certificate's email matches the account used in Basic authentication.
Qualified variant unavailableThe 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 rejectedInclude SubmittedAdvanced and Read, or CompleteAdvanced, in AffidavitKinds.
Evidence access rejectedSet EvidenceAccessControlMethod: Public explicitly.
Commitment comments rejectedKeep comments disabled for Accept and AcceptOrReject; use Reject when collecting comments or rejection reasons.
Enrollment unavailableEnrollment is enabled in the request when needed and the selected profile is configured on the site.
Identity or document mismatchContact details, document kind/value and any supplied identity tenant refer to the intended verified recipient.
PIN destinationThe 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.