Files the document carries beside its pages

Carry whole files inside the PDF — the data an invoice was made from, the same statement in another form — each named, described and dated.

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

A PDF can carry files inside it, the way an envelope carries a letter plus a form. Whoever opens the document sees a list of what it carries and can save any of it. This is what makes an electronic invoice work: the pages are the invoice a person reads, and the file carried inside is the same invoice in a form a program reads, so the two can never say different things. Each carried file is given the name it is saved as, a sentence saying what it is for a person reading the list, what kind of file it is, when its content was last touched, and — the one that matters — what it is to the document: the file the document was made from, the same thing said another way, or something added to it.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

Written at the top level of a request, under "attachments"

attachments declares the files the document carries beside its pages, each named as the request claims it by, in the order they are carried. The bytes themselves arrive alongside the request, as a part under that name. relationship has no default and is required: nobody but the sender knows whether the file is the source the document was made from, an alternative saying the same thing in another form, the data behind it, or a supplement. modified is when the data in the file was last touched, not when the PDF was built. A page claims the files it belongs to through page_files, and an archival document carries them under the rules its standard sets.

Every key, with its default

The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.

  • attachments — array, optional, empty by default.
  • attachments[].name — string, required. The name of the supplied part holding the file, which is also the name the rest of the request claims it by.
  • attachments[].file_name — string, required. The name the file is attached under, and the name a reader offers to save it as.
  • attachments[].description — string, required. What the file is, in words, for a person reading the list of what the document carries.
  • attachments[].media_type — string, required. The file's media type: text/xml for an XML document.
  • attachments[].relationship — string, required, no default. One of source, alternative, data, supplement, unspecified.
  • attachments[].modified — string, required, an ISO 8601 timestamp. When the data in the file was last changed, not when the PDF was built.

Scope: the whole document. page_files says which pages claim which of these files; a file no page claims is carried by the document itself.

A whole request that draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

{
  "attachments": [
    {
      "name": "statement_4711",
      "file_name": "statement-4711.xml",
      "description": "The statement as a data file",
      "media_type": "text/xml",
      "relationship": "data",
      "modified": "2026-08-03T09:15:00+02:00"
    }
  ],
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "rect": { "llx": 72, "lly": 700, "urx": 523, "ury": 740 },
      "content": ["A page, and a data file carried beside it"],
      "font": "sans",
      "font_size": 12
    }
  ]
}

The line that sends it, in three languages

The document as a whole

The numbers the reader shows A hundred letters in a single file What the document says about itself A file still readable in thirty years An invoice a person and a machine both read The address relative links are read against The PDF version the file declares What an image says about itself Which carried files a page claims The identity card a single page carries The accessibility standard the document claims

Where to go next

Every key of a request, in one page The other thirty-two settings of a request

See the prices See the examples

Glossary

byte
The unit a file's weight is counted in, the way a parcel is counted in grams. A thousand of them make a kilobyte, and a million make a megabyte — the size of one photograph taken with a telephone. A one-page PDF here weighs between six thousand and a hundred and twenty thousand, so a hundred of them fit in the space of five photographs.
standard
A rule argued out in committee, published under a number anybody may buy and read, and identical for every firm claiming it. A claim to follow one can therefore be checked against the text. A way of working that merely spread because it worked is a habit of the trade: useful, widespread, and answerable to no text at all.
Factur-X
An invoice that is a page for a person and a data file for a machine, in one document. The page looks like any invoice; inside, the same amounts are attached in a form accounting software reads without anybody retyping them. French law requires this exchange between companies.
attachment
A whole file tucked inside a PDF and carried along with it, the way a paper clip holds a sheet to a folder. Opening the document is enough to get it back out. An electronic invoice works this way: the page a person reads carries the same amounts as a file accounting software reads.
request
One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.

Every word the site explains