Models
Inbox Document
Properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The Recommand document ID. Use it with the other document endpoints. Example: "doc_01JQZ8X0M4T7RB6K9V2NDHW3PA" |
teamId | string | Yes | The ID of the team the document belongs to. Example: "team_01JQZ8X0M4T7RB6K9V2NDHW3PA" |
companyId | string | Yes | The ID of the company the document was sent for or received by. Example: "c_01JQZ8X0M4T7RB6K9V2NDHW3PA" |
direction | incoming | outgoing | Yes | Whether the document was received by this company (incoming) or sent by it (outgoing). Example: "incoming". Values: incoming, outgoing |
senderId | string | Yes | The Peppol address of the sender, as scheme:identifier. Example: "0208:1012081766" |
receiverId | string | null | Yes | The Peppol address of the receiver, as scheme:identifier. Null for documents that were never addressed on the network, such as email-only sends and French e-reporting reports. Example: "0208:0428643097" |
docTypeId | string | Yes | The full Peppol document type identifier the document was exchanged under. It names the syntax and the customization the document follows. Example: "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1" |
processId | string | Yes | The Peppol process identifier the document was exchanged under. It names the business process the document type is used in. Example: "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0" |
countryC1 | string | Yes | The country of the originating sender (Peppol corner 1), in ISO 3166-1 alpha-2 format. Peppol requires it on every transmission so receivers can apply country-specific rules. Example: "BE" |
type | string (enum) | Yes | What kind of document this is. unknown means the document could not be recognised as one of the supported types, in which case parsed is null and only the XML is available. Example: "invoice". Values: invoice, creditNote, selfBillingInvoice, selfBillingCreditNote, messageLevelResponse, frenchInvoicingCdar, frenchB2CSalesReport, frenchB2CPaymentReport, frenchB2BiInvoiceReport, frenchB2BiPaymentReport, unknown |
readAt | string | null | Yes | When the document was marked as read. Null while it is unread, which is what puts an incoming document in the inbox |
createdAt | string | Yes | When the document was sent or received |
updatedAt | string | Yes | When the document record last changed |
validation | Document Validation | null | Yes |
sentOverPeppol | boolean | Yes | Whether the document was handed over to the Peppol network. False for a document that was only delivered by email. Whether it reached the recipient is what deliveryStatus and deliveries say. Example: true |
sentOverEmail | boolean | Yes | Whether the document was delivered by email, either as the only channel or alongside Peppol. Example: false |
emailRecipients | string[] | Yes | The email addresses the document was delivered to. Empty when it was not sent by email. Example: [] |
labels | object[] | Yes | The labels assigned to this document. Manage them with the assign and unassign label endpoints |
peppolMessageId | string | null | Yes | The AS4 message ID of the transmission. Null when the document did not travel over Peppol, and for playground teams, whose transmissions are simulated |
peppolConversationId | string | null | Yes | The AS4 conversation ID the transmission belongs to. It ties a document to the responses that follow it |
receivedPeppolSignalMessage | string | null | Yes | The AS4 signal message the receiving access point returned to acknowledge an outgoing transmission. Null for incoming documents and when the access point returned none |
envelopeId | string | null | Yes | The envelope ID of the document, also known as the SBDH instance identifier (Standard Business Document Header Instance Identifier) |
deliveryStatus | pending | delivered | failed | null | Yes | Whether the document reached its recipient, summarised over its deliveries: delivered when at least one delivery was confirmed, failed when every delivery failed, pending while any is still awaiting the channel's confirmation. Null for documents without deliveries, such as incoming documents and filed reports. Example: "delivered". Values: pending, delivered, failed, null |
deliveries | object[] | Yes | Where an outgoing document stands with each recipient: one entry per channel and address it was sent to. Empty for incoming documents and filed reports. sentOverPeppol says the document was handed to the network; a delivery says whether it arrived |
validation (One of)
Document Validation:
| Name | Type | Required | Description |
|---|---|---|---|
result | valid | invalid | not_supported | error | Yes | valid: the document passed every rule that applies to it. invalid: at least one rule was violated; see errors. not_supported: no ruleset is available for this document type, so nothing was checked. error: the validation service could not be reached or its answer could not be read. Example: "valid". Values: valid, invalid, not_supported, error |
errors | object[] | Yes | The findings the validation produced. Empty when the document is valid, and also when the result is not_supported or error |
validation.errors properties
| Name | Type | Required | Description |
|---|---|---|---|
ruleCode | string | null | No | The identifier of the rule that was violated, for example an EN 16931 or Peppol BIS business rule code. Null for findings that come from something other than a coded rule, such as a schema error. Example: "PEPPOL-EN16931-R010" |
errorMessage | string | Yes | What the rule expected, in the words of the ruleset that raised it |
errorLevel | string | Yes | How serious the finding is. Only findings the ruleset treats as errors make a document invalid. Example: "ERROR" |
fieldName | string | null | No | Where in the document the finding applies, usually as an XPath. Null when the finding is not tied to one place |
source | string | No | Which ruleset produced the finding, for example the syntax schema or a Peppol business rule set |
labels properties
| Name | Type | Required | Description |
|---|---|---|---|
colorHex | string | Yes | The colour the label is shown in, as a hex code. Example: "#3B82F6" |
externalId | string | null | Yes | Your own identifier for the label, if you set one. It is unique within the team, so you can address a label by the id your system already uses. Example: "erp-routing-inbox" |
id | string | Yes | The label's identifier, used wherever a label is assigned or unassigned. Example: "lbl_01JQZ8X0M4T7RB6K9V2NDHW3PA" |
name | string | Yes | The label's name, as it is shown in the dashboard and returned on the documents and suppliers it is assigned to. Example: "ERP" |
deliveries properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The delivery ID. It identifies this delivery in document.delivery_status_changed webhook events. Example: "dlv_01JQZ8X0M4T7RB6K9V2NDHW3PA" |
channel | peppol | email | Yes | How the document was sent to this address. Example: "peppol". Values: peppol, email |
address | string | Yes | The Peppol address or email address the document was sent to. Example: "0208:0428643097" |
status | pending | delivered | failed | Yes | pending: the channel accepted the document and has not confirmed arrival. delivered: the channel confirmed arrival; for Peppol the recipient's access point acknowledged the document, for email the recipient's mail server accepted the message. failed: the document did not arrive; for email the message bounced or was refused. See failure. Example: "delivered". Values: pending, delivered, failed |
statusChangedAt | string | Yes | When the delivery reached its current status |
failure | Delivery Failure | null | Yes |
references | object | Yes | The identifiers the delivery is known by on its channel: the AS4 and envelope IDs for peppol deliveries, the mail service's messageId for email deliveries |
deliveries.failure (One of)
Delivery Failure:
| Name | Type | Required | Description |
|---|---|---|---|
category | recipient_not_found | document_not_supported | validation | transport | recipient_rejected | duplicate | other | Yes | Why the delivery failed, in the same terms for every channel and access point: recipient_not_found (the address is not registered on the network, or the mailbox does not exist), document_not_supported (the recipient does not receive this document type), validation (the document was refused by a rule), transport (it could not be transmitted, or the mail server did not take the message), recipient_rejected (the recipient or their server refused it, for email a block or spam complaint), duplicate or other. Example: "validation". Values: recipient_not_found, document_not_supported, validation, transport, recipient_rejected, duplicate, other |
message | string | null | Yes | What went wrong, as the channel or access point described it |
providerCode | string | null | Yes | The access point's or mail service's own code for the failure, when it reported one: an access point error code, or a bounce type such as HardBounce. Example: "TXE-1005" |
deliveries.references properties
| Name | Type | Required | Description |
|---|---|---|---|
peppolMessageId | string | null | No | The AS4 message ID of the transmission |
peppolConversationId | string | null | No | The AS4 conversation ID of the transmission |
envelopeId | string | null | No | The envelope ID (SBDH instance identifier) of the transmission |
messageId | string | null | No | The mail service's message ID of the email, for email deliveries. It is the ID a bounce or delivery notification from the mail service refers to. Null when the delivery predates message tracking |