Skip to content

HTTP Endpoint

The Endpoint

POST https://api.semadox.net/incoming

Request payload

Receive Files to process asynchronously.

We use multipart/form-data requests to submit data to our API for the case of transmitting PDF files.

Parameters:

Name Type Description Default
file UploadFile

The pdf file we take care of.

 required
message_id Annotated[str, Form()]

The message id provided by you (should be unique).

 required
party_id Annotated[str | None, Form()]

The party identifier. This identifies, which template should be used. This is mutually exclusive to template. Prefer using template if possible.

 None
template Annotated[str | None, Form()]

The explicitly provided template name. This is mutually exclusive to party_id.

 None
subject Annotated[str, Form()]

The subject of the email the file was attached to.

 required
result_mode Annotated[ResultMode | None, Form()]

Optional result mode to use. Possible values are default and no_items. Use no_items if you don't want to process the document items. If not provided, the default mode is used.

 None

NOTE: template and party_id are mutually exclusive. Prefer using template if possible.

Example Request

POST /incoming HTTP/1.1
Host: api.semadox.net
Content-Type: multipart/form-data; boundary=example-part-boundary
Content-Length: 1234
Authorization: Bearer 1234abcd

--example-part-boundary
Content-Disposition: form-data; name="subject"

A subject from email
--example-part-boundary
Content-Disposition: form-data; name="message_id"

1234abced
--example-part-boundary
Content-Disposition: form-data; name="template"

your assigned template
--example-part-boundary
Content-Disposition: form-data; name="file"; filename="invoice123.pdf"
Content-Type: application/pdf

<binary pdf data>
--example-part-boundary--

Example Request (with party_id instead of template)

POST /incoming HTTP/1.1
Host: api.semadox.net
Content-Type: multipart/form-data; boundary=example-part-boundary
Content-Length: 1234
Authorization: Bearer 1234abcd

--example-part-boundary
Content-Disposition: form-data; name="subject"

A subject from email
--example-part-boundary
Content-Disposition: form-data; name="message_id"

1234abced
--example-part-boundary
Content-Disposition: form-data; name="party_id"

your assigned party id
--example-part-boundary
Content-Disposition: form-data; name="file"; filename="invoice123.pdf"
Content-Type: application/pdf

<binary pdf data>
--example-part-boundary--

Example Request ("no items" mode)

POST /incoming HTTP/1.1
Host: api.semadox.net
Content-Type: multipart/form-data; boundary=example-part-boundary
Content-Length: 1234
Authorization: Bearer 1234abcd

--example-part-boundary
Content-Disposition: form-data; name="result_mode"

no_items
--example-part-boundary
Content-Disposition: form-data; name="subject"

A subject from email
--example-part-boundary
Content-Disposition: form-data; name="message_id"

1234abced
--example-part-boundary
Content-Disposition: form-data; name="template"

your assigned template
--example-part-boundary
Content-Disposition: form-data; name="file"; filename="invoice123.pdf"
Content-Type: application/pdf

<binary pdf data>
--example-part-boundary--

JSON variant of the endpoint

In addition to the multipart/form-data endpoint described above we also provide a variant which expects JSON in its request body. We still recommend using the multipart variant if possible. Its URL: https://api.semadox.net/incoming-json.

Request payload (JSON variant)

incoming_json endpoint request payload.

Attributes:

Name Type Description
file_base64 Base64Bytes

The pdf file we take care of encoded as base64.
filename str | None

The name of the input file (optional).
message_id str

The message id provided by you (should be unique).
template str

The name of the template to use when processing the file.
subject str

The subject of the email the file was attached to.
result_mode ResultMode | None

Optional result mode to use. Possible values are default and no_items. Use no_items if you don't want to process the document items. If not provided, the default mode is used.

Example Request (JSON variant)

POST /incoming-json HTTP/1.1
Host: api.semadox.net
Content-Type: application/json
Content-Length: 1234
Authorization: Bearer 1234abcd

{
  "file_base64": "JVBERi0xLjMgZmFrZSBwZGY=",
  "filename": "abc.pdf",
  "message_id": "123abcdef",
  "template": "the_template_name",
  "subject": "the subject"
}

Response payload

The response will come as application/json.

incoming endpoint response.

Attributes:

Name Type Description
log_id str

log id of the processed message
status str

status message

HTTP Status Codes

Code Meaning
202 Accepted - The PDF will be processed.
400 Further details in the JSON code field of the response. Most probably this is returned because there is no template configured.
415 The file you passed is not a PDF file.
422 One of the fields is missing.

Example Response

HTTP/1.1 202 OK
Content-Type: application/json

{"log_id": "13123", "status": "processing data"}

Document details endpoint

GET https://api.semadox.net/documents/{log_id}

log_id parameter should equal to the log_id field returned from the POST /incoming endpoint.

Example Request

GET /documents/296791909332963328 HTTP/1.1
Host: api.semadox.net
Authorization: Bearer 1234abcd

Response payload

The response will come as application/json.

Document details model for api responses.

Attributes:

Name Type Description
id str

database id of the document
filename str

name of the file
message_id str

id of the message
document_date date | None

date of the document
source_path str | None

path to the source document (a .pdf file - if archived)
result_json_path str | None

path to the result json file (if processed correctly)
result_path str | None

path to the result file (if processed correctly)
document_state DocumentState

state of the document

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "296791909332963328",
  "filename": "Rechnung_380086835.1_5.2024.pdf",
  "message_id": "<d42b85f6-aeac-4ef2-bfa5-681a3a195ef0@zeus.a1.net>",
  "document_date": "2024-05-24",
  "source_path": "/documents/296791909332963328.pdf",
  "result_json_path": "/documents/296791909332963328/result.json",
  "document_state": "processed_success"
}

The possible values of the document_state field are described below (they will be lowercased in the response):

Document state.

Attributes:

Name Type Description
DEFERRED_FOR_RETRY

the document processing failed because of mapping errors and it will be retried later.
DLQ

the document processing failed and it will be checked manually.
PROCESSED_IGNORED

the document was ignored according to its processing rules.
PROCESSED_REJECTED

the document was rejected according to its processing rules. The details were not yet sent to the client.
PROCESSED_SUCCESS

the document was successfully processed. The result was not sent yet.
RECEIVED

the document was received, but the processing has not started yet.
SENT_REJECTED

the document was rejected according to its processing rules and its details were sent to the client.
SENT_SUCCESS

the document was successfully processed and its result was sent successfully.
FINISHED_SUCCESS

the document was successfully processed and its result was sent successfully.
FINISHED_REJECTED

the document was rejected according to its processing rules and its details were sent to the client.
FINISHED_IGNORED

the document was ignored according to its processing rules.
FINISHED_WITH_FAILURE

the document processing workflow failed.
UNKNOWN

and unknown state. Shouldn't happen in practice.