Documents

A document is a file that arrived for a client company, whatever route it came by: a forwarded email, an e-Factura message, a supplier portal, an upload link, or somebody dropping a scan in by hand. The reading taken from it is an invoice, which lives on Invoices.

Syllevo never loses a document. The original is written to immutable storage before any row exists, and it is kept byte for byte as it arrived. Nothing on this page rewrites a file.

Document routes are flat rather than nested under a profile, because a document is addressable on its own. The permission still lives on the client company: the API loads the document inside the caller's organization first, then asks whether the caller holds the right permission on the client it turns out to belong to.

Routes

The document shape

status:

sourceProviderType:

invoice, when there is one:

A sale's document used to answer invoice: null, because the summary looked for a supplier and a sale has none. It now answers the sale, with the customer in the counterparty fields. A reading that has not been settled yet is always a purchase: sales are filed on import and never wait for review.

Use isCreditNote to mark a credit note rather than testing for a negative totalAmount. A 381 with a zero total is still a credit note. On a reading that has not been settled yet, it comes from the type code and total the reading found.

GET /v1/documents

One page of documents, newest arrival first by default.

sortBy:

Two date rules are worth stating, because they are the opposite of each other and both are right:

• Documents filter on arrival. period, from, and to here are about when the file came in, because "what came in for October" is what month-end asks of a collected original.
• Invoices filter on issue date. See Invoices.

Sending period and a from/to range together gives you the overlap of the two, not the union.

Filtering never widens what you can see. Without profileId you get every client this credential can see. With one, that same set is narrowed to one client, so naming a client you cannot see gives an empty page rather than a 403. Asking what is waiting is not a forbidden question just because the answer is nothing.

Sorting orders the whole filtered set before paging, so changing the sort moves rows between pages rather than reordering the page you already have.

GET /v1/documents/facets

How many documents sit behind each choice on the filters. Takes exactly the same parameters as GET /v1/documents.

GET /v1/documents/{id}

One document, plus provenance: every arrival it has had, newest first. View.

A document that arrives twice is one row with two provenance entries, not two rows. This is how you answer "where did this come from, and has it come before".

Each provenance entry:

The three verdicts use EmailAuthenticationResult: 0 unknown, 1 pass, 2 fail, 3 soft fail, 4 neutral, 5 none, 6 temporary error, 7 permanent error.

GET /v1/documents/{id}/download

A short-lived link to the stored original. View.

Call this each time you need the file. Do not store the URL: it expires, and a stored one is a credential you did not mean to keep.

If the row exists but the stored file behind it does not, this answers 409 with document_original_missing. That is not retryable. Re-signing points at the same absent key.

POST /v1/documents

Drops a document in by hand: the invoice a client handed over on paper, or one that arrived outside every connected source. ManageDocuments.

multipart/form-data with two parts:

Limits:

The declared type is checked against the file's own leading bytes before anything is stored. A PDF named .jpg is filed as a PDF. Something claiming to be a PDF and not being one is refused.

POST /v1/documents HTTP/1.1
Host: api.syllevo.com
X-Api-Key: syl_live_examplekeynotreal000000000000
Content-Type: multipart/form-data; boundary=----example

------example
Content-Disposition: form-data; name="profileId"

22222222-2222-4222-8222-222222222222
------example
Content-Disposition: form-data; name="file"; filename="invoice.pdf"
Content-Type: application/pdf

<bytes>
------example--

{
  "duplicate": false,
  "document": {
    "id": "55555555-5555-4555-8555-555555555555",
    "profileId": "22222222-2222-4222-8222-222222222222",
    "status": 0,
    "originalFileName": "invoice.pdf",
    "contentType": "application/pdf",
    "contentHash": "9f2c0000000000000000000000000000000000000000000000000000000000ab",
    "sizeBytes": 84213,
    "receivedAt": "2026-09-11T08:00:00Z",
    "lastArrivalAt": "2026-09-11T08:00:00Z",
    "createdAt": "2026-09-11T08:00:00Z",
    "lastUpdatedAt": null,
    "sourceProviderType": 4,
    "sourceAccountTag": null,
    "lastErrorCode": null,
    "invoice": null,
    "deletedAt": null,
    "deletedByUserId": null,
    "deletedByName": null,
    "purgeAt": null,
    "provenance": []
  }
}

201 means the document is new. 200 means these exact bytes were already on file for this client. In the second case the upload recorded another arrival on the existing document and created nothing, and duplicate is true. That is a success, not an error. Uploading the same file twice is safe, so a client that is not sure whether a send went through can just send it again.

DELETE and POST /v1/documents/{id}/restore

DELETE moves a document to the trash. ManageDocuments. Answers 204 with no body.

Nothing is destroyed at that moment. The document gets deletedAt, deletedByUserId, deletedByName, and a purgeAt about 60 days out, and it disappears from the default list. Pass trashed=true on GET /v1/documents to find it.

POST /v1/documents/{id}/restore brings it back out, clearing those fields. ManageDocuments. Answers 200 with the document.

Sales in the trash

Purchases and sales have separate trash views. GET /v1/documents?trashed=true shows purchases, the same as it always has. Add direction=1 to see trashed sales instead, and send the same parameter to GET /v1/documents/facets to get the sales count in trashed. The other facet counts stay about purchases.

direction=1 without trashed=true is a 400: the working list is the purchases inbox, and it refuses a question about sales rather than answering it with purchases. Imported sales are listed by GET /v1/invoices?direction=outgoing.

DELETE and restore work on a sale's document the same way. Trashing or restoring a sale never changes a completeness count and never touches the usage meter: completeness asks what the client received, and a sale was never counted in it.

The invoice record stays while its files sit in the trash. What happens when the same sale is imported again is in Invoices.

A sale that is on its way to SPV, or that ANAF accepted, stays out of the trash: DELETE on any of its files answers 409 sales_invoice_in_spv. A sale ANAF rejected, or that couldn't be sent, can be trashed as usual, and ANAF's answer archive goes with it.

After purgeAt the original is deleted for good, and there is no route that undoes that.

The review queue

Some documents cannot be filed without a person. The reading might be incomplete, the supplier unidentifiable, or the invoice might look like one already on file. Those get status 2, NeedsReview, and land in this queue.

GET /v1/review

One page of the queue, newest arrival first. View.

GET /v1/review/count

The badge: how much is waiting, in total and per client, over the clients this caller can see.

GET /v1/review/{documentId}

Everything one review screen needs: the document's facts, and the values the pipeline proposes. View.

values and fieldScores are open JSON objects rather than a fixed schema, because the fields a reading proposes depend on what kind of document arrived. Read them defensively.

Use GET /v1/documents/{id}/download to put the original in front of the person deciding.

POST /v1/review/{documentId}/decision

Records a person's answer about one document and applies it. ManageDocuments.

correctedFields is a JSON object, not a string, and it is a full snapshot of the corrected values rather than a diff. Send every field, including the ones you did not change.

POST /v1/review/55555555-5555-4555-8555-555555555555/decision HTTP/1.1
Host: api.syllevo.com
X-Api-Key: syl_live_examplekeynotreal000000000000
Content-Type: application/json

{
  "outcome": 1,
  "correctedFields": {
    "number": "EU-2026-000120",
    "issueDate": "2026-09-04",
    "totalAmount": 1190.0,
    "currencyCode": "RON",
    "supplierName": "Example Utilities SA",
    "supplierTaxIdentifier": "RO00000000"
  },
  "notes": "Number was misread as EU-2026-00012O."
}

{
  "decisionId": "99999999-9999-4999-8999-999999999999",
  "documentId": "55555555-5555-4555-8555-555555555555",
  "profileId": "22222222-2222-4222-8222-222222222222",
  "outcome": 1,
  "status": 3,
  "decidedAt": "2026-09-11T08:05:00Z"
}

Statuses to expect:

The plain 409 is the ordinary two-people-one-queue case rather than an error. Refresh the queue, do not retry.

Decisions are append-only. A reviewer who changes their mind decides again, and both answers stay in the record. That is the point of the record.