openapi: 3.0.3 info: title: "DOCUMENT SERVICE API" description: "This RESTful API is designed to serve the Flemish Government Document Senders. It can be used to send Documents over different delivery channels (paper, email or ebox). The API adopts the Federated e-Box API. This version has operations that can be used to service both citizen and enterprises. Release date January 31, 2023." contact: name: "Magda helpdesk" email: "helpdesk.magda@vlaanderen.be" license: name: "e-Box" url: "https://overheid.vlaanderen.be/magda" version: "1.0" servers: - url: "/api/v1/messages" tags: - name: "messages" paths: /files/upload/EMAIL: post: tags: - "messages" summary: "Internal service. Upload a message to the printing partner, for it to be sent via email." operationId: "uploadMessageEMAIL" parameters: - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/Idempotency-Key' requestBody: content: multipart/form-data: schema: required: - file properties: file: type: string description: "ZIP file containing a JSON-description of the message to Send + n PDF files." format: binary required: true responses: 201: $ref: '#/components/responses/Created' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' /files/upload/PAPER: post: tags: - "messages" summary: "Internal service. Upload a message to the printing partner, for it to be sent via paper." operationId: "uploadMessagePAPER" parameters: - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/Idempotency-Key' requestBody: content: multipart/form-data: schema: required: - file properties: file: type: string description: "ZIP file containing a JSON-description of the message to Send + n PDF files." format: binary required: true responses: 201: $ref: '#/components/responses/Created' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' /messages: post: tags: - "messages" summary: "Send a message, using a channel (email, paper mail, ebox) and delivery method (registered or normal) of your choice. More than 6 upfiles only supported for PAPER delivery." operationId: createMessage parameters: - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/Idempotency-Key' requestBody: content: multipart/form-data: schema: type: object required: - messageToSend properties: messageToSend: $ref: '#/components/schemas/MessageToSend' upfile1: type: string format: binary nullable: true upfile2: type: string format: binary nullable: true upfile3: type: string format: binary nullable: true upfile4: type: string format: binary nullable: true upfile5: type: string format: binary nullable: true upfile6: type: string format: binary nullable: true upfile7: type: string format: binary nullable: true upfile8: type: string format: binary nullable: true upfile9: type: string format: binary nullable: true upfile10: type: string format: binary nullable: true upfile11: type: string format: binary nullable: true upfile12: type: string format: binary nullable: true upfile13: type: string format: binary nullable: true upfile14: type: string format: binary nullable: true upfile15: type: string format: binary nullable: true upfile16: type: string format: binary nullable: true upfile17: type: string format: binary nullable: true upfile18: type: string format: binary nullable: true upfile19: type: string format: binary nullable: true upfile20: type: string format: binary nullable: true qrfile: type: string format: binary nullable: true required: true responses: 201: description: Created headers: X-Magda-Exceptions: description: "Only used in the context of EBOX delivery and if there was a problem with the consent of the receiver's ebox." schema: $ref: '#/components/schemas/MagdaExceptionList' content: application/json: schema: $ref: '#/components/schemas/SendStatusMessageList' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' get: tags: - "messages" summary: "Allows to search for messages." operationId: findMessages parameters: - name: delivery in: query description: "Which delivery channel was used" style: form explode: true schema: type: array items: $ref: '#/components/schemas/DeliveryChannel' - name: sentAfter in: query description: "Message was sent after this date-time (yyyy-MM-dd'T'HH:mm:ssXXX). A time offset needs to be provided." schema: type: string format: date-time - name: sentBefore in: query description: "Message was sent before this date-time (yyyy-MM-dd'T'HH:mm:ssXXX). A time offset needs to be provided." schema: type: string format: date-time - name: subject in: query description: "What was the subject of the message. Case insensitive search. Search for the value as a substring" schema: type: string - name: receiver in: query description: "Free search field that will be used to find the messages based on Receiver information: firstName, lastName, organisationName, citizenId, organisationId, emailAddress. Case insensitive search. for the value as a substring" schema: type: string - name: firstName in: query description: "What was the first name of the message receiver. Case insensitive search. Search for the value as a substring" schema: type: string - name: lastName in: query description: "What was the last name of the message receiver. Case insensitive search. Search for the value as a substring" schema: type: string - name: organization in: query description: "What was the organization name of the message receiver. Case insensitive search. Search for the value as a substring" schema: type: string - name: email in: query description: "What was the email address of the message receiver. Case insensitive search. Search for the value as an exact string" schema: type: string - name: insz in: query description: "What was the INSZ number of the message receiver. Case insensitive search. Search for the value as an exact string" schema: type: string - name: kbo in: query description: "What was the INSZ number of the message receiver. Case insensitive search. Search for the value as an exact string" schema: type: string - name: postalCode in: query description: "What was the Postal Code of the message receiver. Case insensitive search. Search for the value as an exact string" style: form explode: true schema: type: array items: type: string - name: status in: query description: "What is the actual status of the message. Case insensitive search. Search for the value as an exact string" style: form explode: true schema: type: array items: type: string - name: key1 in: query description: "The message must have at least one busines data element that this key. Case insensitive search. Search for the value as an exact string" schema: type: string - name: value1 in: query description: "Only usable in combination with key1 query parameter. The message must have at least one busines data element with key key1 query parameter that has value1 as it value. Case insensitive search. Search for the value as an exact string" style: form explode: true schema: type: array items: type: string - name: key2 in: query description: "The message must have at least one busines data element that this key. Case insensitive search. Search for the value as an exact string" schema: type: string - name: value2 in: query description: "Only usable in combination with key2 query parameter. The message must have at least one busines data element with key key2 query parameter that has value1 as it value. Case insensitive search. Search for the value as an exact string" style: form explode: true schema: type: array items: type: string - name: retourReceivedAfter in: query description: "The message was returned to sender on the provided date or later. Only applicable for messages delivered by PAPER." schema: type: string format: date-time - name: eboxReadAfter in: query description: "The message was returned to sender on the provided date or later. Only applicable for messages delivered by EBOX." schema: type: string format: date-time - name: withSigning in: query description: "Signing requested or not" schema: type: boolean default: true - name: orderBy in: query description: "On which field to sort. In case DELIVERY is chosen, secondary sorting is done based on DATE_SENT - DESC." schema: type: string default: DATE_SENT enum: - DATE_SENT - DELIVERY - name: order in: query description: "Descending or ascending sorting" schema: type: string default: DESC enum: - ASC - DESC - name: take in: query description: "How many results need to be returned" schema: type: integer - name: skip in: query description: "How many results need to be skipped" schema: type: integer - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/Idempotency-Key' responses: 200: description: OK content: application/json: schema: $ref: '#/components/schemas/MessageSearchResults' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' /messages/{messageId}: put: tags: - "messages" summary: "Internal service. POST a message that was signed." operationId: updateMessage parameters: - $ref: '#/components/parameters/MessageId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/Idempotency-Key' requestBody: content: multipart/form-data: schema: type: object required: - messageToSend properties: messageToSend: $ref: '#/components/schemas/MessageToSend' upfile1: type: string format: binary nullable: true upfile2: type: string format: binary nullable: true upfile3: type: string format: binary nullable: true upfile4: type: string format: binary nullable: true upfile5: type: string format: binary nullable: true upfile6: type: string format: binary nullable: true upfile7: type: string format: binary nullable: true upfile8: type: string format: binary nullable: true upfile9: type: string format: binary nullable: true upfile10: type: string format: binary nullable: true upfile11: type: string format: binary nullable: true upfile12: type: string format: binary nullable: true upfile13: type: string format: binary nullable: true upfile14: type: string format: binary nullable: true upfile15: type: string format: binary nullable: true upfile16: type: string format: binary nullable: true upfile17: type: string format: binary nullable: true upfile18: type: string format: binary nullable: true upfile19: type: string format: binary nullable: true upfile20: type: string format: binary nullable: true qrfile: type: string format: binary nullable: true required: true responses: 201: description: Created headers: X-Magda-Exceptions: description: "Only used in the context of EBOX delivery and if there was a problem with the consent of the receiver's ebox." schema: $ref: '#/components/schemas/MagdaExceptionList' content: application/json: schema: $ref: '#/components/schemas/SendStatusMessageList' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' /eboxPreferences/search: post: tags: - "messages" summary: "Consult the EboxPreferences by posting a list of eboxIds. Can be used in bulk but only for one ebox type at once." operationId: getEboxPreferencesByList parameters: - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/Idempotency-Key' requestBody: description: List of eboxIds content: application/json: schema: $ref: '#/components/schemas/EboxIdSameTypeList' required: false responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/EboxInfoList' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 404: description: No mailbox found content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' /searchMessageStatus: post: tags: - "messages" summary: "Internal service. Obtain a messageStatus for a list of eBox messages." operationId: getEBoxStatus parameters: - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/Idempotency-Key' requestBody: description: "The MessagesStatusRequest is a list of couples messageId/eboxId." content: application/json: schema: $ref: '#/components/schemas/MessageIdEboxIdList' required: false responses: 201: description: Created content: application/json: schema: $ref: '#/components/schemas/EBoxMessagesStatusList' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 404: $ref: '#/components/responses/MessageNotFound' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' /messages/{messageId}/attachments: get: tags: - "messages" summary: "Allows to download the attachments of a message. In case an attachment ID is provided, the service will try to provide the concerned attachment. In case no attachmentId is provided, the service will try to provide all attachments of the concerned message. In case multiple attachments are available, they will be provided within a ZIP file." operationId: getMessageAttachments parameters: - $ref: '#/components/parameters/MessageId' - name: attachmentFileName in: query description: "Which attachment to get: the file name including the extention" schema: type: string - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/Idempotency-Key' responses: 200: description: OK headers: content-type: description: "The content type of the attachment: PDF or ZIP." schema: type: string content: application/octet-stream: schema: type: string format: binary 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 403: $ref: '#/components/responses/NoMessageAuthorization' 404: description: Message or attachment not found content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' /messages/{messageId}/status: get: tags: - "messages" summary: "Allows to obtain the status of a message." operationId: getMessageStatus parameters: - $ref: '#/components/parameters/MessageId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/Idempotency-Key' responses: 200: description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/EBoxMessageStatus' - $ref: '#/components/schemas/PaperOrEmailMessageStatus' - $ref: '#/components/schemas/SigningMessageStatus' discriminator: propertyName: objectType 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 403: $ref: '#/components/responses/NoMessageAuthorization' 404: $ref: '#/components/responses/MessageNotFound' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' /messages/{messageId}/IPEXdata: patch: tags: - "messages" summary: "Allows to update the ipex data of a message." operationId: updateIpexData parameters: - $ref: '#/components/parameters/MessageId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/Idempotency-Key' requestBody: description: "The Status Update Request" content: application/json: schema: $ref: '#/components/schemas/UpdateIpexDataRequest' required: true responses: 204: description: No Content 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 403: $ref: '#/components/responses/NoMessageAuthorization' 404: $ref: '#/components/responses/MessageNotFound' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' /messages/{messageId}/preview: get: tags: - "messages" summary: "Allows to obtain a preview of the PDF of a paper message (including front pages)." operationId: GetPaperPDFPreview parameters: - $ref: '#/components/parameters/MessageId' - $ref: '#/components/parameters/CorrelationId' responses: 200: description: OK headers: content-type: description: "The content type of the binary: PDF." schema: type: string content: application/octet-stream: schema: type: string format: binary 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 403: $ref: '#/components/responses/NoMessageAuthorization' 404: description: Message or PDF not found content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' /messages/{messageId}/metadata: get: tags: - "messages" summary: "Allows to download the meta-data of a message." operationId: getMessageMetadata parameters: - $ref: '#/components/parameters/MessageId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/Idempotency-Key' responses: 200: description: OK content: application/json: schema: $ref: '#/components/schemas/MessageMetadata' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 403: $ref: '#/components/responses/NoMessageAuthorization' 404: $ref: '#/components/responses/MessageNotFound' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' /statusRequest: post: tags: - "messages" summary: "Operation to obtain the messageStatus for a list of messages that were sent via one and the same deliveryChannel." operationId: getMessageStatuses parameters: - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/Idempotency-Key' requestBody: description: "The MessagesStatusRequest is a list of status requests of one and the same deliveryChannel." content: application/json: schema: $ref: '#/components/schemas/MessageIdsOfSameChannel' required: false responses: 200: description: OK content: application/json: schema: $ref: '#/components/schemas/MessagesStatusOfSameDeliveryChannel' 400: $ref: '#/components/responses/BadRequest' 401: $ref: '#/components/responses/InvalidAuthorization' 404: $ref: '#/components/responses/MessageNotFound' 500: $ref: '#/components/responses/UnexpectedServerError' 502: $ref: '#/components/responses/BadGateway' 503: $ref: '#/components/responses/ServiceUnavailable' 504: $ref: '#/components/responses/GatewayTimeout' components: parameters: CorrelationId: name: x-correlation-id in: header required: true schema: $ref: '#/components/schemas/Correlation-Id' Idempotency-Key: name: Idempotency-Key in: header required: false schema: $ref: '#/components/schemas/IdempotencyKey' MessageId: name: messageId in: path description: "Globally unique identifier (GUID) for the message" required: true schema: type: string responses: Created: description: Created content: application/json: schema: $ref: '#/components/schemas/UploadStatusMessage' Published: description: Created content: application/json: schema: $ref: '#/components/schemas/PublicationStatusMessage' BadRequest: description: Invalid data supplied content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' InvalidAuthorization: description: Invalid authorization content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' NoMessageAuthorization: description: Not authorized to obtain this message content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' MessageNotFound: description: Message not found content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' UnexpectedServerError: description: Unexpected Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' BadGateway: description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' ServiceUnavailable: description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' GatewayTimeout: description: Gateway Timeout content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' schemas: AttachmentToPublish: required: - httpPartName - mainContent type: object properties: attachmentTitle: $ref: '#/components/schemas/TranslatedString' httpPartName: type: string description: the name of the http part that contains the bytes, filename and mime type of the document. mainContent: type: boolean description: "Indicates the priority of this attachment: ''true'' means that this attachment is considered as main content of the message, ''false'' means this attachment is considered as an annex. Attention, the readStatus of a message will be true as soon as a ''mainContent'' is consulted." digest: $ref: '#/components/schemas/Digest' attachmentSigned: type: boolean description: "Boolean used to indicate if the attachment is signed or not." default: false description: "An attachment item contains the meta data of the attachment." BusinessDataToPublish: required: - key - values type: object properties: key: type: string description: "Significative key of the businessData element." name: $ref: '#/components/schemas/TranslatedString' description: $ref: '#/components/schemas/TranslatedString' values: type: array description: "Values represented by the businessData." items: $ref: '#/components/schemas/TranslatedString' description: "A businessData element contains businessData concerning the message linked to it, in the form of a name and an array of values. To publish a BusinessData element, at least a key and an array of values is needed." Digest: required: - digestMethod - digestValue type: object properties: digestValue: type: string description: "Digest value returned by the cryptographic hash function encoded in base64url as defined in RFC 4648 nr5 (https://tools.ietf.org/html/rfc4648#section-5)." digestMethod: type: string description: "Cryptographic hash function used to obtain the digest." enum: - sha_256 description: "Object containing the digestValue and digestMethod describing the cryptographic hash function of an item." EboxId: required: - eboxIdValue - eboxType type: object properties: eboxType: type: string enum: - ENTERPRISE - CITIZEN eboxIdValue: $ref: '#/components/schemas/PersonOrEnterpriseIdentifier' EboxIdSameTypeList: required: - eboxIdType - eboxIdValueList - eboxType type: object properties: eboxType: type: string example: ENTERPRISE eboxIdType: type: string example: EnterpriseNumber eboxIdValueList: type: array items: $ref: '#/components/schemas/PersonOrEnterpriseIdentifier' EboxInfo: required: - eboxId - exclusivelyEbox type: object properties: eboxId: $ref: '#/components/schemas/EboxId' exclusivelyEbox: type: boolean description: "Indication if the enterprise/citizen has chosen to use the ebox as the exclusive channel (Do not send a paper copy anymore)." example: true lastConnectionDate: type: string description: "Most recently date-time when a user has been connected to its ebox using official GUI. Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the ebox was last consulted." format: date-time example: 2019-04-19T20:00:00Z totalNumberOfMessages: type: integer description: "Sum of all messages for every document provider." example: 999 totalNumberOfUnreadMessages: type: integer description: "Sum of all unread messages for every document provider." example: 3 EboxInfoList: type: array items: $ref: '#/components/schemas/EboxInfo' MessageIdEboxId: type: object properties: messageId: type: string description: Identifier of a message eboxId: $ref: '#/components/schemas/EboxId' MessageToSend: required: - delivery type: object properties: delivery: $ref: '#/components/schemas/DeliveryChannel' eboxDeliveryData: $ref: '#/components/schemas/MessageToPublish' paperDeliveryData: $ref: '#/components/schemas/PaperDeliveryData' emailDeliveryData: $ref: '#/components/schemas/EmailDeliveryData' signingWorkflowData: $ref: '#/components/schemas/SigningWorkflowData' businessData: type: array description: "List of business data" items: $ref: '#/components/schemas/BusinessDataToPublish' description: "A messageToSend is composed of a delivery channel and optionally a messageToPublish (via ebox), an email data block and a physical address data block." MessageMetadata: type: object properties: messageSent: $ref: '#/components/schemas/MessageToSend' dateSent: type: string description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message was sent. Zero offset format." format: date-time consent: type: boolean description: "The consent status at the time the message was sent. In case we did not obtain consent info at the time of sending, this property will not be included in the response." statusInfo: $ref: '#/components/schemas/DeliveryInformation' attachmentsMetaData: type: array description: "The URLs on which the attachments of this message can be downloaded." items: $ref: '#/components/schemas/AttachmentMetaData' description: "The meta-data of the message. Can be used to obtain some of the pramaters on how the message was delivered." MessageReceiver: type: "object" description: "The data of the message receiver." properties: firstName: type: "string" description: "Only applicable for EBOX, PAPER or AUTOMATIC delivery. In case of EBOX delivery, it is populated with the first name of the forTheAttentionOf block." lastName: type: "string" description: "In case of EBOX delivery, it is populated with the first name of the forTheAttentionOf block. In case of EMAIL delivery, it is populated with the value of the name fields of the receiver block." organisationName: type: "string" description: "Only applicable for PAPER or AUTOMATIC delivery." citizenId: type: "string" description: "The national number of the receiver. Only applicable for EBOX or AUTOMATIC delivery." organisationId: type: "string" description: "The company number of the receiver. Only applicable for EBOX or AUTOMATIC delivery." emailAddress: type: "string" description: "Only applicable for EMAIL delivery." MessageSearchResults: required: - totalAmount type: object properties: totalAmount: type: integer description: "The total amount of messages in this collection" messages: type: array description: "The collection of the overview data of each message." items: $ref: '#/components/schemas/MessageOverview' description: "The consise information about a collection of messages." DeliveryChannel: type: string description: "The delivery method used to deliver the message" enum: - EBOX - PAPER - EMAIL - AUTOMATIC - PAPER_AND_EBOX MessageIdList: description: "When instantiated, make sure to use the value 'MessageIdList' for the property objectType." type: object required: - content properties: objectType: type: string content: type: array items: type: string MessageOverview: required: - dateSent - delivery - messageMetadataURI type: object properties: delivery: $ref: '#/components/schemas/DeliveryChannel' dateSent: type: string description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message was sent. Zero offset format." format: date-time subject: type: string description: "The subject of the message" receiver: $ref: '#/components/schemas/MessageReceiver' messageMetadataURIs: $ref: '#/components/schemas/DeliveryInformation' description: "The consise information about a message." AttachmentMetaData: required: - fileName type: object properties: fileName: type: string url: type: string description: "The URL where the attachment can be downloaded." description: "The metaData of the attachment." MessageToPublish: required: - bodyMainContent - recipient - replyAuthorized - subject type: object properties: recipient: $ref: '#/components/schemas/EboxId' forTheAttentionOf: $ref: '#/components/schemas/ForTheAttentionOf' originalMessageId: type: string description: "Id of the original message (bidirectional use case)." subject: $ref: '#/components/schemas/TranslatedString' messageTypeId: type: string description: "Identifier of a messageType." expirationDate: type: string description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will expire in the ebox." format: date-time senderOrganizationId: pattern: '[0-1][0-9]{9}' type: string description: "Enterprise number (BCE - KBO number) of the sender organization." example: "0406798006" senderApplicationId: type: string description: "Identifier of the senderApplication." registeredMail: type: boolean description: "Indicates whether or not the message was published as a registered mail in the ebox." default: false attachments: type: array description: "A list of attachments." items: $ref: '#/components/schemas/AttachmentToPublish' bodyMainContent: type: boolean description: "This property must be present only if there is a body. Indicates the priority of the bodyContent: true means that the body is considered as main content of the message, false means it is considered as an annex. Attention, the readStatus of a message will be true as soon as a mainContent is consulted." default: false bodyContent: $ref: '#/components/schemas/TranslatedString' businessDataList: type: array description: "List of business data" items: $ref: '#/components/schemas/BusinessDataToPublish' messageData: type: string description: "The MessageData structure exists to convey information that SHOULD NOT be displayed to the endUser. This is in contrast with BusinessData structure which SHOULD be displayed as is to the endUser." paymentData: $ref: '#/components/schemas/PaymentData' replyAuthorized: type: boolean description: "Indicate if the message allows replies." default: false replyDueDate: type: string format: "date-time" description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) until when the reply is possible." messageActionIds: type: array description: "Array of actions identifiers that can publish messages of this message" items: type: string description: "A messageToPublish is basically composed of a mandatory set of metadata (e.g. recipient, subject, messageTypeId, etc.); optional attachment(s) and/or body, with at least one main content." TypedMessageIdEboxIdList: description: "A typed version of the MessageIdEboxIdList. When instantiated, make sure to use the value 'TypedMessageIdEboxIdList' for the property objectType." required: - content type: object properties: objectType: type: string content: $ref: '#/components/schemas/MessageIdEboxIdList' MessageIdEboxIdList: type: array items: $ref: '#/components/schemas/MessageIdEboxId' MessageIdsOfSameChannel: description: "When instantiated, make sure to use the value 'MessageIdsOfSameChannel' for the property objectType." required: - deliveryChannel type: object properties: deliveryChannel: $ref: '#/components/schemas/DeliveryChannel' messages: type: object oneOf: - $ref: '#/components/schemas/MessageIdList' - $ref: '#/components/schemas/TypedMessageIdEboxIdList' discriminator: propertyName: objectType EBoxMessageStatus: description: "When instantiated, make sure to use the value 'EBoxMessageStatus' for the property objectType." required: - eboxId - messageId - readStatus type: object properties: objectType: type: string messageId: type: string description: "Identifier of a message." eboxId: $ref: '#/components/schemas/EboxId' expirationDate: type: string description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will expire in the ebox, including an offset)" format: date-time readStatus: type: boolean description: "Indicates whether or not the main content of the message has already been opened." default: false visible: type: boolean description: "Indication whether or not the message is visible or not." default: true statuses: type: array items: $ref: '#/components/schemas/MessageStatusEvent' PaperOrEmailMessageStatus: description: "When instantiated, make sure to use the value 'PaperOrEmailMessageStatus' for the property objectType." required: - messageId type: object properties: objectType: type: string messageId: type: string shippingDate: type: string description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message was injected in the bpost framework." format: date-time mailId: type: string trackAndTraceUri: type: string statuses: type: array items: $ref: '#/components/schemas/MessageStatusEvent' SigningMessageStatus: description: "When instantiated, make sure to use the value 'SigningMessageStatus' for the property objectType." required: - messageId type: object properties: objectType: type: string messageId: type: string description: "Signing message id which corresponds to the package id of the Signing Hub." statuses: type: array items: $ref: '#/components/schemas/MessageStatusEvent' MessageStatusEvent: type: object properties: id: type: string status: type: string updated: type: string description: Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when this status was updated. format: date-time comment: type: string EBoxMessagesStatusList: type: array items: $ref: '#/components/schemas/EBoxMessageStatus' MessagesStatusOfSameDeliveryChannel: required: - deliveryChannel - messageStatuses type: object properties: deliveryChannel: $ref: '#/components/schemas/DeliveryChannel' messageStatuses: type: array items: oneOf: - $ref: '#/components/schemas/EBoxMessageStatus' - $ref: '#/components/schemas/PaperOrEmailMessageStatus' discriminator: propertyName: objectType RemittanceInformationStructured: description: "The sum of reference, type and issuer length shall be less of 280 characters." type: object required: - reference properties: reference: type: "string" description: "Remittance Information Structured Reference" maxLength: 320 type: type: "string" description: "Remittance Information Structured Type" maxLength: 320 issuer: type: "string" description: "Remittance Information Structured Issuer" maxLength: 320 QrCodeToPublish: type: object required: - type - data - httpPartName properties: data: type: "string" description: "QR Code data deeplink" maxLength: 320 type: type: "string" description: "QR Code type" maxLength: 320 httpPartName: type: "string" description: "QR Image as HttpPart (mediaType infered)" Beneficiary: type: object description: "Only address fields that are actually used in this context: line1, city, postalCode, country. Other address fields are irrelevant within the context of a Benificiary." required: - name properties: name: type: "string" description: "Beneficiary Name" address: $ref: '#/components/schemas/Address' PaymentData: required: - amount - currency - dueDate - iban - paymentDataId - vatAmount type: object properties: paymentDataId: type: string description: Identifier of the paymentData. totalAmount: type: number description: Amount that needs to be paid, vat included. format: double pattern: '^\d*(.\d){0,1}\d{0,1}$' amount: type: number description: Amount that needs to be paid, vat not included. format: double pattern: '^\d*(.\d){0,1}\d{0,1}$' vatAmount: type: number description: Amount of the vat, to be added to the base amount when applicable. format: double pattern: '^\d*(.\d){0,1}\d{0,1}$' currency: type: string description: Currency in which the amount must be paid, following ISO 4217. maxLength: 3 dueDate: type: string description: Date on which the payment needs to be fulfilled. format: date-time iban: type: string description: Bank account on which the amount must be paid, following ISO 13616:2007. maxLength: 23 bic: type: string description: Bank Identifier Code. maxLength: 8 reference: type: string description: Reference added to the payment. beneficiary: $ref: '#/components/schemas/Beneficiary' remittanceInformationUnstructured: type: "string" maxLength: 140 description: 'Remittance Information Unstructured' remittanceInformationStructured: $ref: '#/components/schemas/RemittanceInformationStructured' qrCode: $ref: '#/components/schemas/QrCodeToPublish' description: Data concerning payments. SendStatusMessageList: type: array items: $ref: '#/components/schemas/SendStatusMessage' SendStatusMessage: required: - messageId type: object properties: messageId: type: string description: Identifier of a message expirationDate: type: string description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will expire in the ebox." format: date-time deliveryChannel: $ref: '#/components/schemas/DeliveryChannel' code: type: string description: Business Code message: type: string description: Business Code Description PublicationStatusMessage: required: - expirationDate - messageId type: object properties: messageId: type: string description: Identifier of a message. expirationDate: type: string description: Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the message will expire in the ebox. format: date-time code: type: string description: Business Code. message: type: string description: Business Code Description. UploadStatusMessage: required: - uuid type: object properties: uuid: type: string description: Identifier of a message. host: type: string filename: type: string MagdaException: required: - code - date - diagnosis - origin - type type: object properties: code: type: integer description: "HTTP status code of the request from which this exception stemmed." origin: maxLength: 5 type: string description: "Who originated this exception." type: type: string description: "Specifies the kind of Exception that occurred. ERROR: The main flow could not be executed successfully. WARNING: The main flow was executed successfully, but there was a non-blocking problem. INFO: The main flow was executed without any problem, but there is addition information that can be communicated." enum: - ERROR - WARNING - INFO date: type: string description: "Date-time (yyyy-MM-dd'T'HH:mm:ssXXX) when the error was found." format: date-time diagnosis: type: string description: "Short explation of the exception. The possible values are explained in the user guide." circumstance: type: string description: "More details of the cause of the exception." annotations: type: string description: "Not yet in use. To be worked out later." elementReferences: type: string description: "Contains a reference to the payload element on which this exception is applicable." description: "A representation of a MAGDA exception." MagdaExceptionList: type: object properties: content: type: array items: $ref: '#/components/schemas/MagdaException' ErrorMessage: required: - detail - title type: object properties: type: type: string description: "A URI reference that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be about:blank." title: type: string description: "A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation." status: type: string description: "The HTTP status code generated by the origin server for this occurrence of the problem." detail: type: string description: "A human-readable explanation specific to this occurrence of the problem." instance: type: string description: "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced." description: "A representation of a generic error message." TranslatedString: type: object properties: nl: type: string fr: type: string de: type: string description: Common type defined to provide a string value for each supported language among nl, fr, de. Address: type: object required: - country - line1 properties: title: type: string firstName: type: string maxLength: 320 lastName: type: string maxLength: 320 organisation: type: string line1: type: string maxLength: 320 line2: type: string postalCode: type: string maxLength: 20 city: type: string maxLength: 120 region: type: string country: type: string description: ISO2 country code maxLength: 8 PaperDeliveryData: type: object oneOf: - $ref: '#/components/schemas/PaperDeliveryDataAddress' - $ref: '#/components/schemas/PaperDeliveryDataSsin' discriminator: propertyName: objectType PaperDeliveryDataAddress: type: object properties: objectType: type: string registeredMail: type: boolean default: false description: Indicates if the mail should be sent as a registered mail or not. acknowledgmentOfReceipt: type: boolean default: false description: Indicates if the receiever needs to sign a document in which the reception of the mail is conformed. Thei document is mailed back to the reourAddress. In case this is true, retourAddress is mandatory. side: type: string default: RV enum: - RV - RS offset: type: integer description: Indicates the page on which the printing of the first file should start (offset = 0 => start printing on front side of first page. Detail explanation to be found in the user guide. Behaviour to be considered in combination with side and keycommunicatedViaChannel parameters). nullable: true default: null minimum: 0 maximum: 3 documentType: type: string description: Indicates the kind of document (F.i. 'invoice', 'Informative Letter'). Will be used by the printing partner for reporting purposes. maxLength: 120 priority: type: string default: dlp4 description: 'Indicates how many days bpost has to deliver the paper mail: dlp1/dlp3/dlp4.' documentAvailableUntilDate: type: string format: date description: 'Date (yyyy-MM-dd) until when the document should be available for download.' keyCommunicatedViaChannel: type: string default: SEPARATE_PAGE enum: - SAME_PAGE - SEPARATE_PAGE - SEPARATE_LETTER - NO_DOWNLOAD_KEY description: Indicates if the key that is required to download a digital copy of the document must be sent separately from the original document. retourAddress: $ref: '#/components/schemas/Address' sendPaperIfNotReadByDate: type: string format: date-time description: 'Earliest date-time when a delayed paper delivery should be started in case the ebox message remains unread. Only applicable for AUTOMATIC delivery channel and consent given.' address: $ref: '#/components/schemas/Address' PaperDeliveryDataSsin: type: object properties: objectType: type: string registeredMail: type: boolean default: false description: Indicates if the mail should be sent as a registered mail or not. acknowledgmentOfReceipt: type: boolean default: false description: Indicates if the receiever needs to sign a document in which the reception of the mail is conformed. Thei document is mailed back to the reourAddress. In case this is true, retourAddress is mandatory. side: type: string default: RV enum: - RV - RS offset: type: integer description: Indicates the page on which the printing of the first file should start (offset = 0 => start printing on front side of first page. Detail explanation to be found in the user guide. Behaviour to be considered in combination with side and keycommunicatedViaChannel parameters). nullable: true default: null minimum: 0 maximum: 3 documentType: type: string description: Indicates the kind of document (F.i. 'invoice', 'Informative Letter'). Will be used by the printing partner for reporting purposes. maxLength: 120 priority: type: string default: dlp4 description: 'Indicates how many days bpost has to deliver the paper mail: dlp1/dlp3/dlp4.' documentAvailableUntilDate: type: string format: date description: 'Date (yyyy-MM-dd) until when the document should be available for download.' keyCommunicatedViaChannel: type: string default: SEPARATE_PAGE enum: - SAME_PAGE - SEPARATE_PAGE - SEPARATE_LETTER - NO_DOWNLOAD_KEY description: Indicates if the key that is required to download a digital copy of the document must be sent separately from the original document. retourAddress: $ref: '#/components/schemas/Address' sendPaperIfNotReadByDate: type: string format: date-time description: 'Earliest date-time when a delayed paper delivery should be started in case the ebox message remains unread. Only applicable for AUTOMATIC delivery channel and consent given.' receiverSsin: $ref: '#/components/schemas/NationalNumber' NationalNumber: type: string pattern: "[0-9]{10,11}" example: "70012533955" description: "The national number of the concerned person." EmailDeliveryData: type: object properties: registeredMail: type: boolean description: Indicates if the email should be sent as a registered email or not. default: false receiver: type: object properties: name: type: string email: type: string maxLength: 320 sender: type: object properties: name: type: string email: type: string maxLength: 320 subject: type: string maxLength: 320 body: type: object properties: file: type: string content: type: string SigningWorkflowData: type: object description: 'A list of recipients and signature fields for who needs to sign where on the documents.' required: - signingWorkflowType - signers - signatureFields properties: signingWorkflowType: type: string enum: - SERIAL - PARALLEL - CUSTOM signers: type: array minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/Signer' signatureFields: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/SignatureField' Signer: type: object required: - email - name properties: email: type: string maxLength: 320 name: type: string emailNotification: type: boolean mobileNumber: type: string role: type: string enum: - SIGNER - REVIEWER - EDITOR - INPERSON_HOST - PLACEHOLDER - CARBON_COPY signingOrder: type: integer SignatureField: type: object required: - httpPartName - order - levelOfAssurance properties: httpPartName: type: string description: the name of the http part that contains the bytes, filename and mime type of the document. order: type: integer minimum: 1 maximum: 10 levelOfAssurance: type: array minItems: 1 maxItems: 10 items: type: string enum: - ADVANCED_ELECTRONIC_SIGNATURE - HIGH_TRUST_ADVANCED - QUALIFIED_ELECTRONIC_SIGNATURE - ELECTRONIC_SEAL fieldDetails: oneOf: - $ref: '#/components/schemas/FixedFieldDetails' - $ref: '#/components/schemas/AutoplaceFieldDetails' FixedFieldDetails: type: object required: - pageNumber - dimensions properties: pageNumber: type: integer fieldName: type: string dimensions: type: object required: - left - top - width - height properties: left: type: integer top: type: integer width: type: integer height: type: integer display: type: string AutoplaceFieldDetails: type: object required: - searchText - maxLength - multiline properties: searchText: type: string description: Word that needs to be searched in the document. placement: type: string description: If the text is found, fields are to be placed in the document. Placement of the field can be mentioned in this attribute. Possible values of placement of a field are LEFT, RIGHT, TOP, BOTTOM. If no value is provided the default value will be LEFT. fieldType: type: string description: Type of field to be created in the document. Possible values are "ELECTRONIC_SIGNATURE", "DIGITAL_SIGNATURE", "IN_PERSON_SIGNATURE", "INITIALS", "TEXT", "NUMBER" ,"NAME", "EMAIL", "COMPANY", "JOBTITLE", "RADIOBOX", "CHECKBOX", "DATE" multiline: type: boolean validationRule: type: string description: One or more rules for validation of the fields possible values are "MANDATORY" or "OPTIONAL". value: type: string description: Value that user want to show in the field. radioGroupName: type: string description: The group name required only when adding a Radio Box type field to group multiple Radio boxes together. maxLength: type: integer description: Maximum length of the value allowed in the field. Must between 1 - 9999. format: int32 format: type: string description: >-

Text format of the field. Used for the date type field only. Possible values are

placeholder: type: string description: Placeholder is needed for IN_PERSON_SIGNATURE or Text type form fields. Placeholder is shown as a collaborator name on the UI e.g., Customer, Doctor, Director. It helps to generally identify who is intended to sign or fill the field. font: description: Font of the fields text allOf: - $ref: '#/components/schemas/Font' dimensions: type: object required: - width - height properties: width: type: integer height: type: integer Font: type: object properties: name: type: string description: >- Name of the font selected for the text field. Possible values are "COURIER", "HELVETICA". size: type: string description: >- Size of the font selected for the text field. Possible values are 8, 10, 12, 14, 16, 18, 20 embeddedSize: type: string description: Size of the font in the original PDF document. ForTheAttentionOf: type: object properties: id: type: string type: type: string name: type: string UpdateIpexDataRequest: type: object properties: status: type: string enum: - Created - Error - Failed - Printed - Processing - Sent - Pending - Cancelled ipexError: type: string ipexProcessDate: type: string format: date-time description: "Message was processed by IPEX at this date-time (yyyy-MM-dd'T'HH:mm:ssXXX). A time offset needs to be provided." ipexMailId: type: string ipexRetourDate: type: string format: date-time description: "Message was returned to sender and found by IPEX at this date-time (yyyy-MM-dd'T'HH:mm:ssXXX). A time offset needs to be provided." DeliveryInformation: type: array description: "The URLs on which information can be retrieved for a message. Can be a collection in case multiple deliveries were done for this messages." items: type: object properties: delivery: $ref: '#/components/schemas/DeliveryChannel' messageId: type: string uri: type: string Correlation-Id: description: "ID of the transaction. Use this ID for log tracing and incident handling." type: string maxLength: 36 minLength: 10 IdempotencyKey: description: "When retrying a failed call, the retry call should have the same Idempotency Key." type: string maxLength: 36 minLength: 10 PersonOrEnterpriseIdentifier: type: string pattern: "[0-9]{10,11}" description: the unique identifier of a citizen example: "0406798006"