{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/namirialnotify/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Integration workflows","description":"Integration and usage documentation.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"integration-workflows","__idx":0},"children":["Integration workflows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common end-to-end patterns that repeat across the Namirial Notify APIs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use it together with the service reference pages when you are designing a"," ","production integration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"shared-integration-pattern","__idx":1},"children":["Shared integration pattern"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Regardless of service, the recommended lifecycle is:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit the transaction and store the returned identifier."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store your own correlation key, typically ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LookupKey"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure callbacks when you need near-real-time status updates."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use Query or Get operations to reconcile state and retrieve evidence."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Download or request affidavit content only when your workflow needs it."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Step"},"children":["Step"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to persist in your system"},"children":["What to persist in your system"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submit"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request timestamp, environment, service, returned transaction ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Correlation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LookupKey"]}," and any internal business identifier"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tracking"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Last known state, outcome, callback event identifiers"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Evidence retrieval"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Affidavit IDs, attachment IDs, download timestamps"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"workflow-1-evimail-and-evisms","__idx":2},"children":["Workflow 1: EviMail and EviSMS"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this pattern when the certified content is the delivered message itself."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recommended-flow","__idx":3},"children":["Recommended flow"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit the message with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/EviMail/Submit"]}," or"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/EviSms/Submit"]},". Include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Evi-IdempotencyToken"]}," to protect"," ","against duplicate submissions when your client retries."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Persist the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eviId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PushNotificationUrl"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PushNotificationFilter"]},", and optionally"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PushNotificationExtraData"]}," if you want asynchronous updates."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Process callbacks as state changes arrive."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reconcile with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/EviMail/Query"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/EviSms/Query"]}," using"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WithUniqueIds"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WithLookupKeys"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request affidavit metadata from the query response only when needed by using"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IncludeAffidavits"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pass the affidavit IDs from Query or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AffidavitPublished"]}," callbacks to"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /AffidavitsDownload"]}," to retrieve the signed PDFs in a ZIP archive."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For EviMail on-demand affidavits: if the original submit included"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AffidavitKinds: [OnDemand]"]},", request a custom affidavit with"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/EviMail/AffidavitRequest"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"good-production-pattern","__idx":4},"children":["Good production pattern"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use callbacks as the primary signal for progress."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use Query as a reconciliation step, a recovery path, or a scheduled audit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Avoid requesting affidavit or attachment metadata on every poll."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Treat EviMail on-demand affidavits as a separate asynchronous workflow from"," ","normal state tracking."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"workflow-2-evinotice","__idx":5},"children":["Workflow 2: EviNotice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this pattern when the certified content is hosted on the platform and the"," ","recipient interacts with that hosted notice."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recommended-flow-1","__idx":6},"children":["Recommended flow"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit the notice with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/EviNotice/Submit"]},". Include"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Evi-IdempotencyToken"]}," to protect against duplicate submissions when"," ","your client retries."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Persist the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Id"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure callback fields if you need asynchronous updates."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Process notice callbacks such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Processed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Delivered"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Received"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Read"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Replied"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Closed"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retrieve the current record with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/EviNotice/{Id}"]}," when"," ","you need the latest full object."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IncludeAffidavits"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IncludeAttachments"]}," on the Get endpoint for"," ","metadata-driven retrieval."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Download ZIP archives from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/Affidavits"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/Attachments"]}," only when your"," ","process actually needs the files."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The legacy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v2/..."]}," form is still accepted for backward compatibility. For new integrations, use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v2/..."]}," routes shown here."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pagination-pattern","__idx":7},"children":["Pagination pattern"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When reconciling many notices, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/EviNotice/Query"]}," with"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Limit"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Cursor"]}," rather than repeatedly fetching single notices."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"workflow-3-evipost","__idx":8},"children":["Workflow 3: EviPost"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this pattern when physical postal delivery is part of the certified process."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recommended-flow-2","__idx":9},"children":["Recommended flow"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/EviPost/Submit"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Evi-IdempotencyToken"]}," to protect against duplicate submits when"," ","your client retries."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Persist the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uniqueId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PushNotificationUrl"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PushNotificationFilter"]}," when you need"," ","asynchronous state tracking."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reconcile with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/EviPost/Query"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you need a custom affidavit after submission, call"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/EviPost/AffidavitRequest"]},". This requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AffidavitsOnDemandEnabled: true"]}," ","and an advanced ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AffidavitProfile"]}," in the original Submit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When the affidavit is ready, the platform fires an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AffidavitPublished"]}," callback"," ","to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PushNotificationUrl"]}," configured at submission, provided ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AffidavitPublished"]}," ","is included in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PushNotificationFilter"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AdditionalData.AffidavitId"]},", or an affidavit ID returned by Query, to"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /AffidavitsDownload"]}," to retrieve the signed PDF in a ZIP archive."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"good-production-pattern-1","__idx":10},"children":["Good production pattern"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Treat on-demand affidavit generation as a separate asynchronous workflow."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep the main delivery lifecycle and the affidavit-request lifecycle as two"," ","distinct processes in your integration."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"workflow-4-batch-sending-evinotice-evimail-evisms","__idx":11},"children":["Workflow 4: Batch sending (EviNotice, EviMail, EviSMS)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this pattern when you need to send the same certified communication to many recipients as a single managed job."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recommended-flow-3","__idx":12},"children":["Recommended flow"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create an empty batch with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/Evi{Service}/Batches"]},". You receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BatchId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set the content — for EviNotice and EviMail, upload the HTML body with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT .../Body"]},"; for EviSMS, set the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Text"]}," field via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upload recipients with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST .../Recipients"]}," as a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text/csv"]}," file."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optionally add attachments with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST .../Attachments"]}," (EviNotice and EviMail only)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure per-message options (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH .../{BatchId}"]},") — certification level, callbacks, scheduling, etc."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Start processing by setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["State"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Submitted"]}," via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH"]},", or schedule it with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ScheduledDate"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Poll ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET .../{BatchId}"]}," to follow progress (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SentCount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedCount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ProgressPercentage"]},")."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the service reference pages for the CSV column format and the full option set: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/apis/evinotice-api#batch-operations"},"children":["EviNotice batch"]},", ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/apis/evimail-api#batch-operations"},"children":["EviMail batch"]},", ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/apis/evisms-api#batch-operations"},"children":["EviSMS batch"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The batch API is under the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v2"]}," base path (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v2/Evi{Service}/Batches"]},"), even for EviMail and EviSMS whose single-send operations use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"callback-first-query-second","__idx":13},"children":["Callback-first, query-second"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Across EviNotice, EviMail, EviSMS, and EviPost:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Prefer callbacks for near-real-time updates."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use Query or Get endpoints for reconciliation, backfilling, and auditing."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Make callback handling idempotent, because retries can happen if your"," ","endpoint is unavailable or slow."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not assume callbacks arrive in lifecycle order. Deduplicate by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Identifier"]},","," ","use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Date"]}," as the event time, and reconcile with Query or Get."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/dev/callbacks"},"children":["Callbacks and webhooks"]}," for payload examples and retry"," ","behavior."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"polling-based-status-tracking","__idx":14},"children":["Polling-based status tracking"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your integration cannot receive callbacks, you can track status by polling the"," ","Query or Get endpoints. Interpret the results using the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["timestamp fields"]}," rather"," ","than the live ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["State"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Outcome"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["State"]}," changes as the transaction advances,"," ","while ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Outcome"]}," may remain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["None"]}," until closure. Neither should be treated as the"," ","final result until ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["State"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Closed"]},"; at that point, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Outcome"]}," is final. See"," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/user-guides/states-outcomes#state-outcome-and-timestamp-fields"},"children":["State, outcome, and timestamp fields"]}," ","for the full model."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"submission-20x-versus-4xx","__idx":15},"children":["Submission: 20x versus 4xx"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["4xx"]}," response means the request was rejected and the transaction never"," ","entered the system. The error body lists the reasons. Nothing is created and"," ","there is nothing to poll."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["20x"]}," response means the request was accepted. The transaction is created"," ","and processed asynchronously in the background. The applicable submission"," ","timestamp (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NewOn"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SubmittedOn"]},") is set first, followed by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReadyOn"]}," or"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ProcessedOn"]},", then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DispatchedOn"]},", and later milestones as processing advances."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful 20x does ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," guarantee final success. After acceptance, the"," ","transaction can still fail during asynchronous processing — for example, an"," ","EviNotice with an unparseable or encrypted PDF attachment whose"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IncludeOnAffidavits"]}," is enabled is accepted first and only later transitions to"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["State = Closed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Outcome = Failed"]},". There is no dedicated error-detail field in"," ","the API for these cases; the detail is available in the web interface and the"," ","affidavits."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"deriving-status-flags-by-polling","__idx":16},"children":["Deriving status flags by polling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Map your business flags to timestamp fields:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Flag"},"children":["Flag"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field to check"},"children":["Field to check"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Processed and certified by the platform"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReadyOn"]}," is present (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ProcessedOn"]}," for EviNotice)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Handed to the sending process or channel"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DispatchedOn"]}," is present"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Accepted by the recipient's server / operator"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SentOn"]}," is present"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delivered"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DeliveredOn"]}," is present"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReadOn"]}," is present. For EviSMS, read tracking requires RCS delivery; plain SMS cannot report reads."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Downloaded (EviNotice)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["the content/attachment download affidavit is present — there is no timestamp for downloads, and the affidavit is only generated if it was requested at submit time"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transmission diagnostics"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Where exposed, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XmissionResult"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XmissionSummary"]}," provide the recorded"," ","transmission result and human-readable diagnostic details. These fields can be"," ","updated as sending attempts are processed. Do not parse ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XmissionSummary"]}," or use"," ","either field as a lifecycle state. Derive business flags from the milestone"," ","timestamps, and use the final ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Outcome"]}," after the state becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Closed"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recommended-polling-loop","__idx":17},"children":["Recommended polling loop"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit and store the returned ID and your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LookupKey"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Poll Query or Get on a backoff interval until ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["State"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Closed"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On each poll, update your flags from the timestamp fields."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["State"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Closed"]},", read the final ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Outcome"]}," and stop polling."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For EviNotice, EviMail, and EviSMS, keep polling within the transaction's"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TimeToLive"]}," window; once it elapses the state moves to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Closed"]}," and no further"," ","timestamps will appear. EviPost has no submit-configurable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TimeToLive"]}," — its"," ","lifecycle follows postal-operator timelines instead."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a backoff interval rather than tight polling, and reconcile in batches where"," ","the endpoint supports it. The public API references do not define a cross-service"," ","rate-limit contract; confirm expected traffic with your Namirial Notify contact"," ","before go-live."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-implementation-checklist","__idx":18},"children":["Common implementation checklist"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store the service-specific transaction ID returned by Submit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store your own stable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LookupKey"]}," so you can correlate business events."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Separate operational status tracking from large file retrieval."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Design callback processing to be idempotent."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reconcile state periodically, even when callbacks are enabled."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Download affidavit blobs, attachment blobs, or ZIP archives only in the steps"," ","that require them."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related","__idx":19},"children":["Related"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/apis/overview"},"children":["API reference overview"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/dev/callbacks"},"children":["Callbacks and webhooks"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/dev/error-handling"},"children":["Error handling"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/dev/performance-guidelines"},"children":["Performance and scaling"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/user-guides/states-outcomes"},"children":["States and outcomes"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/apis/evimail-api"},"children":["EviMail API"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/apis/evisms-api"},"children":["EviSMS API"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/apis/evinotice-api"},"children":["EviNotice API"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/namirialnotify/apis/evipost-api"},"children":["EviPost API"]}]}]}]},"headings":[{"value":"Integration workflows","id":"integration-workflows","depth":1},{"value":"Shared integration pattern","id":"shared-integration-pattern","depth":2},{"value":"Workflow 1: EviMail and EviSMS","id":"workflow-1-evimail-and-evisms","depth":2},{"value":"Recommended flow","id":"recommended-flow","depth":3},{"value":"Good production pattern","id":"good-production-pattern","depth":3},{"value":"Workflow 2: EviNotice","id":"workflow-2-evinotice","depth":2},{"value":"Recommended flow","id":"recommended-flow-1","depth":3},{"value":"Pagination pattern","id":"pagination-pattern","depth":3},{"value":"Workflow 3: EviPost","id":"workflow-3-evipost","depth":2},{"value":"Recommended flow","id":"recommended-flow-2","depth":3},{"value":"Good production pattern","id":"good-production-pattern-1","depth":3},{"value":"Workflow 4: Batch sending (EviNotice, EviMail, EviSMS)","id":"workflow-4-batch-sending-evinotice-evimail-evisms","depth":2},{"value":"Recommended flow","id":"recommended-flow-3","depth":3},{"value":"Callback-first, query-second","id":"callback-first-query-second","depth":2},{"value":"Polling-based status tracking","id":"polling-based-status-tracking","depth":2},{"value":"Submission: 20x versus 4xx","id":"submission-20x-versus-4xx","depth":3},{"value":"Deriving status flags by polling","id":"deriving-status-flags-by-polling","depth":3},{"value":"Recommended polling loop","id":"recommended-polling-loop","depth":3},{"value":"Common implementation checklist","id":"common-implementation-checklist","depth":2},{"value":"Related","id":"related","depth":2}],"frontmatter":{"title":"Integration workflows","description":"End-to-end integration patterns for submitting transactions, tracking them, and retrieving evidences across the Namirial Notify APIs.","layout":"doc","outline":"deep","keywords":["integration workflow","end to end example","callbacks","affidavits","namirial notify api"],"seo":{"title":"Integration workflows"}},"lastModified":"2026-08-21T12:44:22.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/namirialnotify/dev/integration-patterns","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}