# Query certified postal communications (GET)

Endpoint: GET /v1/EviPost/Query
Version: 1.0
Security: basicAuth

## Security:

  - `basicAuth` (unknown)
    http basic

## Query parameters:

  - `WithUniqueIds` (string)
    Filter by one or more unique IDs (comma-separated).

  - `WithLookupKeys` (string)
    Filter by one or more lookup keys (comma-separated).

  - `OnState` (string)
    Filter by current state. Contact support before using this parameter.

  - `WithOutcome` (string)
    Filter by outcome. Contact support before using this parameter.

  - `OrderResultsBy` (string)
    Sort field for results.

  - `Offset` (integer)
    Number of results to skip for pagination.

  - `Limit` (integer)
    Default and maximum are 100 without affidavits, 25 with affidavit metadata, and 1 with embedded affidavit PDFs.

  - `IncludeDocumentOnResult` (boolean)
    Include the base64-encoded original document in results.

  - `IncludeAffidavitsOnResult` (boolean)
    Include affidavit metadata in results.

  - `IncludeAffidavitBlobsOnResult` (boolean)
    When enabled with IncludeAffidavitsOnResult, embeds Base64 affidavit PDFs in affidavits[].bytes. Some deployments enable blobs when this flag is omitted. Set false explicitly for metadata-only results and use /AffidavitsDownload to fetch PDFs.

## Response 200:

  - `200` (unknown)
    Query executed successfully

## Response 200 fields (application/json):

  - `totalMatches` (integer)
    Total number of records matching the query filters.

  - `results` (array)

  - `results.evidenceId` (string)
    Unique identifier of the postal communication. Serialized as 32 hexadecimal characters without dashes.

  - `results.lookupKey` (string)
    Lookup key set at submission. If multiple CustomFields were indexed, values are concatenated with `::`.

  - `results.recipientName` (string)

  - `results.address` (object)
    Recipient postal address. Returned with camelCase field names.

  - `results.address.streetAddress` (string)

  - `results.address.postalCode` (string)

  - `results.address.locality` (string)

  - `results.address.region` (string)

  - `results.address.country` (string)
    ISO 3166-1 alpha-2 country code (e.g. ES).

  - `results.address.postOfficeBoxAddress` (string)

  - `results.document` (string)
    Base64-encoded original document. Only present when `IncludeDocumentOnResult` is true.

  - `results.state` (string)
    Current lifecycle state. `Undelivered` records reported non-delivery but does not itself close tracking. For `Registered` and `Letter` with delivery tracking enabled, the platform accepts a later valid delivery report before closure; the operator sequence is unconfirmed. `LetterLite` cannot complete normal closure with `Delivered` once non-delivery has been recorded. A `Letter` workflow configured for disposal can continue to `Disposed`; a later failure report for `Letter` can instead lead to `Failed` before closure. Individual delivery attempts are events and do not necessarily change the state. `Unknown` may appear for transitional internal states; contact support if seen in production responses.
    Enum: "Draft", "Submitted", "Processed", "Sent", "Dispatched", "Delivered", "Missing", "Closed", "Issued", "Failed", "Undelivered", "Disposed", "Cancelled"

  - `results.stateDate` (string)
    Date of the recorded state.

  - `results.lastStateChangeDate` (string)
    Date when the platform last updated the state or online retention expiry.

  - `results.outcome` (string)
    Result recorded so far; it may change while the communication is open. Treat this as the final postal result when `state` is `Closed`. `Undelivered` does not by itself identify an item awaiting collection or a return-to-sender action. `Expired` is listed in the contract but is not supported as the outcome of normal postal closure. A tracking timeout does not automatically assign `Expired`; check the current state with Query and contact support if it appears. `Unknown` may appear for transitional internal states; contact support if seen in production responses.
    Enum: "None", "Delivered", "Dispatched", "Acknowledged", "Declined", "Hindered", "Cancelled", "Expired", "Failed", "Sent", "Rejected", "Undelivered", "Disposed"

  - `results.outcomeDate` (string)
    Date assigned to the outcome.

  - `results.creationDate` (string)

  - `results.submittedOn` (string)

  - `results.processedOn` (string)

  - `results.dispatchedOn` (string)

  - `results.sentOn` (string)

  - `results.deliveredOn` (string)

  - `results.closedOn` (string)

  - `results.issuedOn` (string)
    Timestamp when the postal item was issued.

  - `results.timeToLive` (integer)
    Tracking window in minutes: 50400 for Registered and 21600 for Letter or LetterLite. A timeout does not set the Expired outcome.

  - `results.costCentre` (string)
    Cost-centre label recorded with the transaction for internal billing allocation.

  - `results.onlineRetentionPeriod` (integer)

  - `results.notaryRetentionPeriod` (integer)

  - `results.notaryProfile` (string)

  - `results.sourceChannel` (string)
    Enum: "Web", "Api", "Smtp"

  - `results.enableDeliveryReceipt` (boolean)
    For `Letter` type. Whether delivery receipt tracking is enabled.

  - `results.deliveryAttemptsNumber` (integer)
    For `Letter` type. Number of delivery attempts configured before the process ends.

  - `results.disposalDaysAmmount` (integer)
    Number of days after which an undelivered postal item is disposed of. (Note: the field name retains its original spelling in the API.)

  - `results.affidavits` (array)
    Affidavit entries. Set IncludeAffidavitsOnResult to true to retrieve metadata. Some deployments embed PDFs unless IncludeAffidavitBlobsOnResult is explicitly false.

  - `results.affidavits.uniqueId` (string)
    Unique identifier of the affidavit. Serialized as 32 hexadecimal characters without dashes.

  - `results.affidavits.date` (string)
    Creation timestamp of the affidavit.

  - `results.affidavits.evidenceUniqueId` (string)
    Unique identifier of the evidence this affidavit belongs to. Serialized as 32 hexadecimal characters without dashes.

  - `results.affidavits.partyUniqueId` (string)
    Identifier of the related delivery/party, when applicable. Serialized as 32 hexadecimal characters without dashes.

  - `results.affidavits.bytes` (string)
    Base64-encoded affidavit PDF, populated when blob inclusion is enabled. Send IncludeAffidavitBlobsOnResult=false for metadata only.

  - `results.affidavits.description` (string)
    Human-readable description of the affidavit.

  - `results.affidavits.kind` (string)
    Technical identifier of the affidavit kind, when available.

  - `results.affidavits.additionalData` (object)
    Additional affidavit metadata as key-value pairs.

## Response 400:

  - `400` (unknown)
    Invalid query, including a limit above the applicable maximum.

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

