# Submit a certified postal communication

Submit a Base64-encoded PDF smaller than 2,097,152 bytes before encoding. Acceptance does not confirm later PDF validation or postal delivery. A processing failure or postal-service rejection can close the communication with outcome `Failed`; use Query to check the outcome.

Endpoint: POST /EviPost/Submit
Version: 1.0
Security: basicAuth

## Security:

  - `basicAuth` (unknown)
    http basic

## Header parameters:

  - `X-Evi-IdempotencyToken` (string)
    Optional idempotency token (GUID recommended) to prevent duplicate submissions on retry. A replay of a cached `200 OK` submission returns `202 Accepted`. Responses `400`, `401`, `408`, `409`, `429`, and `5xx` are not cached for replay.

## Request fields (application/json):

  - `LookupKey` (string)
    Optional identifier set by the issuer. Can be used later to locate the evidence via the Query endpoint.

  - `Document` (string, required)
    The document or letter to be sent, base64-encoded PDF.

  - `RecipientName` (string, required)
    Non-blank display name of the recipient.

  - `RecipientLegalName` (string)
    Legal name or corporate name of the recipient.

  - `RecipientAddress` (object, required)

  - `RecipientAddress.StreetAddress` (string, required)
    Street name and number. Maximum 100 characters for the recipient and 255 for the issuer.

  - `RecipientAddress.PostalCode` (string, required)
    Postal code.

  - `RecipientAddress.Locality` (string, required)
    City or town.

  - `RecipientAddress.Region` (string)
    Province or region. Required in RecipientAddress when PostServiceType is Registered. The issuer region must also be present, either supplied in IssuerAddress or filled from the site address.

  - `RecipientAddress.Country` (string, required)
    ISO 3166-1 alpha-2 country code (e.g. ES).

  - `RecipientAddress.PostOfficeBoxAddress` (string)
    Post office box address, if applicable.

  - `RecipientPhone` (string)
    Recipient phone number. Use + followed by the country code and phone number, with digits only.

  - `RecipientEmail` (string)
    Email address of the recipient.

  - `IssuerName` (string)
    Display name of the sender. Supply it explicitly to record it in the evidence.

  - `IssuerLegalName` (string)
    Legal or corporate name of the sender. Supply it explicitly to record it in the evidence.

  - `IssuerPhone` (string)
    Issuer phone number. Use + followed by the country code and phone number, with digits only.

  - `IssuerEmail` (string)
    Email address of the issuer.

  - `IssuerComments` (string)
    Optional additional comments from the issuer.

  - `Options` (object)

  - `Options.PostServiceType` (string)
    Controls the type of postal delivery. `Registered` sends a certified postal communication equivalent to a burofax (via the national postal operator, Correos); enabling `Letter` receipt, attempt or disposal options or passing non-zero attempts or disposal days returns 400. `Letter` sends to a printing and enveloping provider (MRW). `LetterLite` is a single-attempt printed letter available only within mainland Spain; omit the attempt and disposal options. Sites billed per submission cannot use `LetterLite`. Defaults to `Registered` when omitted.
    Enum: "Registered", "Letter", "LetterLite"

  - `Options.PostServiceProfile` (string)
    Optional provider profile for `Letter`. Omit it unless support has given you a profile identifier.

  - `Options.CertificationLevel` (string)
    Legal framework and geographic variant for certification. Supported values include `Standard`, `Advanced`, and their regional variants, such as `Standard_EU` or `Advanced_EU`. Availability depends on the account. EviPost does not support QERDS certification levels. Supply the level explicitly; the API does not use the Web form’s account default.
    Enum: "Standard", "Advanced", "Standard_CO", "Standard_CR", "Standard_EC", "Standard_EU", "Standard_MX", "Standard_PE", "Advanced_CO", "Advanced_CR", "Advanced_EC", "Advanced_EU", "Advanced_MX", "Advanced_PE"

  - `Options.AffidavitProfile` (string)
    Controls which affidavits are generated during the process.
    Enum: "None", "Basic", "AdvancedContentOnSubmit", "AdvancedContentOnClose", "AdvancedContentOnSubmitAndOnClose"

  - `Options.AffidavitsOnDemandEnabled` (boolean)
    Set at Submit for an advanced content profile to enable on-demand affidavit requests on an open `Letter` or `LetterLite`. A configurable limit applies per communication. `Registered` accepts the flag at Submit but cannot use AffidavitRequest.

  - `Options.OnlineRetentionPeriod` (integer)
    Online evidence retention in years. Currently 1 year by default.

  - `Options.NotaryRetentionPeriod` (integer)
    Set to 5 for five years of custody or 0 to disable. Any non-zero value applies five years. Supply `NotaryProfile` for a positive value.

  - `Options.NotaryProfile` (string)
    Provisioned notary profile. Required when `NotaryRetentionPeriod` is greater than 0; omit otherwise. Use non-empty alphanumeric segments separated by colons, up to 50 characters in total.

  - `Options.EvidenceAccessControlMethod` (string)
    Controls how recipients access the evidence record. If omitted, the API uses `Public` (no access challenge). Set the method explicitly. When set to `Challenge`, both `EvidenceAccessControlChallenge` and `EvidenceAccessControlChallengeResponse` must also be supplied.
    Enum: "AutoChallenge", "Public", "Challenge"

  - `Options.EvidenceAccessControlChallenge` (string)
    Challenge question. Required when `EvidenceAccessControlMethod` is `Challenge`.

  - `Options.EvidenceAccessControlChallengeResponse` (string)
    Answer to the challenge question. Required when `EvidenceAccessControlMethod` is `Challenge`.

  - `Options.Language` (string)
    Language for the evidence record and generated affidavits. Defaults to the site's configured language when omitted.
    Enum: "en", "es", "ca", "it", "pt", "pt-BR", "fr", "de", "ro"

  - `Options.CostCentre` (string)
    Optional billing group identifier. Groups submissions for invoicing and expense allocation.

  - `Options.EnableDeliveryReceipt` (boolean)
    For `Letter` type only. Enables delivery receipt tracking.

  - `Options.EnableDeliveryAttempts` (boolean)
    For `Letter`: set to true with a positive DeliveryAttemptsNumber.

  - `Options.DeliveryAttemptsNumber` (integer)
    For `Letter`: a positive number requires EnableDeliveryAttempts: true. The maximum is currently 2 by default.

  - `Options.CustomFields` (array)
    Array of custom key-value fields attached to the submission. Fields with `IsLookupKey: true` are indexed and returned in query results under `LookupKey`, concatenated with `::`. Do not combine them with a top-level `LookupKey`.

  - `Options.CustomFields.Key` (string, required)
    Identifier of the custom field.

  - `Options.CustomFields.Label` (string, required)
    Display label for the field.

  - `Options.CustomFields.Value` (string, required)
    Value of the custom field.

  - `Options.CustomFields.IsLookupKey` (boolean)
    If true, this value is indexed and surfaced in query results under `LookupKey`.

  - `Options.CustomFields.TypeName` (string, required)
    Field type. Currently only `Text` is supported.
    Enum: "Text"

  - `Options.CustomFields.DefaultValue` (string)

  - `Options.CustomFields.DefaultValueIsForced` (boolean)

  - `Options.CustomFields.Required` (boolean)

  - `Options.CustomFields.ValidationRegex` (string)
    Regex expression to validate the field value.

  - `Options.CustomFields.ValidationMessage` (string)
    Message shown when validation fails.

  - `Options.CustomFields.MaxLength` (integer)
    Maximum character length of the field value.

  - `Options.PushNotificationUrl` (string)
    URL to receive HTTP POST callbacks when the postal communication changes state.

  - `Options.PushNotificationFilter` (array)
    Event names that trigger callbacks. Supply both the URL and a non-empty filter, or omit both. Submit returns 400 if only one is set or if the filter repeats a value. AffidavitPublished is an event, not a state.

  - `Options.PushNotificationExtraData` (string)
    Free-text value included in every callback payload under `AdditionalData.ExtraData`.

  - `Options.EnableDisposal` (boolean)
    For `Letter`; set to true with a positive DisposalDaysAmmount.

  - `Options.DisposalDaysAmmount` (integer)
    For `Letter`: set to 0 for no disposal, or 1 to 15 with EnableDisposal set to true. The field retains its original spelling.

  - `Options.OwnerNotificationTemplate` (string)
    Identifier of an enabled custom template used for the issuer's status notification email. See [Using communication templates from the API](/products/namirialnotify/dev/templates).

  - `Options.OwnerNotificationTemplateValues` (object)
    Key-value pairs supplying values for the user variables declared in OwnerNotificationTemplate.

  - `Options.LtaStorage` (boolean)
    When true, the evidence for this transaction is stored in Namirial Archive during post-close processing after tracking reaches `Closed`. Requires LTA to be enabled for the site. `OnlineRetentionPeriod` separately controls online accessibility.

## Request examples:

  - `Registered postal communication` (unknown)

## Response 200:

  - `200` (unknown)
    Postal communication accepted

## Response 200 fields (application/json):

  - `uniqueId` (string, required)
    Unique identifier of the submitted postal communication. Serialized as 32 hexadecimal characters without dashes.

## Response 200 headers (application/json):

  - `X-Evi-IdempotencyStatus` (string)
    Idempotency outcome for the submission request.
    Enum: "New"

## Response 202:

  - `202` (unknown)
    Idempotent replay. The same X-Evi-IdempotencyToken was used for a cached 200 OK submission. The original response body is returned; the postal communication is not resubmitted.

## Response 202 fields (application/json):

  - `uniqueId` (string, required)
    Unique identifier of the submitted postal communication. Serialized as 32 hexadecimal characters without dashes.

## Response 202 headers (application/json):

  - `X-Evi-IdempotencyStatus` (string)
    Idempotency outcome for the submission request.
    Enum: "Replay"

## Response 400:

  - `400` (unknown)
    Invalid request or business rule failure

## Response 400 fields (application/json):

  - `responseStatus` (object)

  - `responseStatus.errorCode` (string)

  - `responseStatus.message` (string)

  - `responseStatus.errors` (array)

## Response 401:

  - `401` (unknown)
    Authentication failed

## Response 403:

  - `403` (unknown)
    Access denied. The authenticated account is not provisioned for EviPost. Contact your Namirial Notify account manager to enable this service.

## Response 409:

  - `409` (unknown)
    Another Submit with the same X-Evi-IdempotencyToken is currently in flight.

## Response 409 headers:

  - `X-Evi-IdempotencyStatus` (string)
    Idempotency outcome for the submission request.
    Enum: "Conflict"

## Response 492:

  - `492` (unknown)
    Submission quota for this recipient or for this service type on the site was reached. Avoid retrying immediately; contact support if it persists.

## Response 492 fields (application/json):

  - `responseStatus` (object)

  - `responseStatus.errorCode` (string)

  - `responseStatus.message` (string)

  - `responseStatus.errors` (array)

