> ## Documentation Index
> Fetch the complete documentation index at: https://help.draftable.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API Self-Hosted v3 – Understanding fonts and font substitution
> Why comparisons on API Self-Hosted can report style changes for fonts that are not in your documents, which fonts ship with the product, and how to upload your own.
If you are seeing **style or font changes reported in a comparison for fonts that do not appear anywhere in your documents**, this article explains why, and what to do about it.
The short version: your PDF references a font it does not carry with it, API Self-Hosted does not have that font installed, and something else gets substituted in its place. The comparison then correctly reports that the two sides are set in different fonts.
## Why this happens
### Fonts are not always inside the file
There are three ways a PDF can reference a font, and the difference matters enormously.
| Method | What is stored in the PDF | Renders correctly anywhere? |
| :---------------------------- | :----------------------------------------------- | :----------------------------------------------------: |
| **Embedded** | The entire font file | Yes |
| **Embedded subset** | Only the glyphs actually used | Yes |
| **Referenced (not embedded)** | Font metadata only, such as the name and metrics | Only if the font is installed on the system opening it |
With the first two, the document carries everything needed to display its own text. With the third, the PDF is effectively saying *"render this in Times New Roman"* and relying on the machine opening it to have Times New Roman available. If it does not, that machine substitutes something else.
A single PDF can mix all three methods, **including within the same font family**. It is entirely possible for one document to contain an embedded Times New Roman, a subset-embedded Times New Roman Bold, and a non-embedded Times New Roman reference, all at once. Each block of text points at a specific font object, so some text renders correctly and some gets substituted.
This is the single most common cause of the problem. The presence of an embedded copy of a font in a PDF **does not** mean non-embedded references to the same font will use it.
### Arial and Times New Roman are not included
Fonts such as **Arial**, **Times New Roman**, **Calibri** and **Cambria** are proprietary. They ship with Microsoft Windows and Microsoft Office, but that licence does not extend to redistributing them inside another product. Draftable cannot include them in API Self-Hosted without licensing them from the font foundry.
API Self-Hosted therefore ships with a large set of **open-licensed fonts** instead, including metric-compatible substitutes designed to occupy the same space on the page:
| If your document asks for | API Self-Hosted substitutes |
| :------------------------ | :-------------------------- |
| Times New Roman | Liberation Serif |
| Arial / Helvetica | Liberation Sans |
| Courier New | Liberation Mono |
| Calibri | Carlito |
| Cambria | Caladea |
These substitutes are metrically compatible, so line breaks and pagination are preserved. But they are **different fonts with different names**, and that is exactly what the comparison reports.
This is why the phantom font is so often reported as **"Liberation Serif"**. Liberation Serif is not coming from your document. It is what API Self-Hosted used in place of a Times New Roman reference it could not resolve.
### Why the same documents compare cleanly on Draftable's cloud API
Nothing is wrong with your instance. The difference is simply **which fonts are installed on the machine performing the conversion**. Self-hosted deployments ship a deliberately restricted, licence-safe font set, and you control what is added to it.
## Recognising the symptom
You are almost certainly looking at font substitution rather than a genuine content change if:
* The reported changes are **style or formatting changes**, not text changes
* The font names in the report include fonts that **appear nowhere in either document**, particularly Liberation Serif, Liberation Sans, Carlito or Caladea
* The two documents were produced by **different software** (for example one by Aspose and one by GemBox), or one is a PDF and the other a DOCX
* Converting the DOCX to PDF before submitting **reduces but does not eliminate** the detections
## Diagnosing it
Most PDF editors expose this under **Document Properties → Fonts**. You are looking for each font's name and whether it is listed as *Embedded*, *Embedded Subset*, or neither.
A document whose fonts are all embedded or subset-embedded will always render correctly. A document with non-embedded entries is the one causing the substitution. In a typical case, one side of the comparison is fully embedded and the other is not.
Write down every font listed without embedding. These are the fonts API Self-Hosted needs and does not have. This is the list you will upload in the next section.
Document Properties also shows the producing application. Differing producers is a strong signal that the two files handle embedding differently, and points at a fix you can make upstream.
## Fix 1: upload the missing fonts
API Self-Hosted v3 lets you install additional fonts through the administration interface. This is the direct fix.
You are responsible for ensuring you hold the rights to any font you upload. Draftable cannot advise on font licensing. Uploading a font you have licensed for your own systems into your own self-hosted instance is a decision for you and your licensing team to make.
The **Fonts** page is split into two panels: the fonts that ship with the product on the left, and the fonts you have added on the right.
Font management is restricted to superuser accounts. Navigate to **Fonts** in the administration menu.
The left-hand panel lists every font that ships with API Self-Hosted, in alphabetical order. Check here first, because the font you need may already be present under a different name.
This is where you can confirm for yourself that **Caladea** and **Carlito** are present while Cambria and Calibri are not, which is the substitution described earlier in this article.
In the **Custom fonts** panel, select **Upload font**. You can select multiple files at once. Both **TrueType (.ttf)** and **OpenType (.otf)** are supported.
Upload **every variant** you need, not just the regular weight. A document referencing Times New Roman Bold needs the bold font file; the regular file will not satisfy it.
Uploading stages a font but does not activate it. Select **Reload font services** to distribute the fonts to the services that perform document conversion and rebuild their font caches.
Each font in the Custom fonts list carries a status icon. Wait until every font shows as **installed** before testing.
| Icon state | Meaning |
| :------------------ | :------------------------------------------ |
| Installed | The font is live on the conversion services |
| Pending sync | Uploaded, but not yet distributed |
| Syncing | Currently being distributed |
| Marked for deletion | Removal requested, pending the next reload |
| Error | The font could not be synced |
Submit a fresh comparison. Existing comparisons are not reprocessed, so you must create a new one to see the effect.
Uploaded fonts are stored centrally in your instance and distributed to the conversion services on reload, so a font only needs to be uploaded once regardless of how many worker replicas you run.
### If uploading the font does not fix it
This happens, and it is usually one of three things.
* **The font name does not match.** A PDF may reference `TimesNewRomanPSMT` or `TimesNewRomanPS-BoldMT` rather than `Times New Roman`. These are distinct font names, and the file you upload must supply the name the document actually asks for. Take the exact name from the Document Properties font list.
* **You uploaded only some variants.** Regular, bold, italic and bold-italic are separate font files. Each must be uploaded.
* **The font services were not reloaded**, or the sync had not finished when you re-tested.
## Fix 2: embed fonts at the source
Uploading fonts treats the symptom. Embedding fonts when the PDF is generated removes the cause, and it makes your documents render consistently everywhere, not just in Draftable.
If the PDFs are produced by software you control, look for a **"embed all fonts"** setting in its PDF export options. Most PDF generation libraries and applications support this, and many have it disabled by default to reduce file size.
If you can only fix one side, fix the side that currently has non-embedded fonts. Getting both sides embedded is what produces a genuinely clean comparison.
## Fix 3: compare like with like
Comparing a **PDF against a DOCX** generally produces more style detections than PDF against PDF, because the two formats are converted through different paths before comparison.
Converting the DOCX to PDF before submitting usually improves the result. It rarely eliminates the problem entirely, because the underlying font availability issue is unchanged, but it removes one variable. Combine it with Fix 1 or Fix 2 for the best outcome.
## Removing a font
To remove a custom font, select **Remove** next to it in the Custom fonts panel, then select **Reload font services**. The font is marked for deletion immediately and is removed from the conversion services on the next reload.
System fonts cannot be removed.
## Summary
| Situation | Recommended action |
| :------------------------------------------------------- | :------------------------------------------------- |
| Non-embedded proprietary fonts, and you hold the licence | Upload the fonts (Fix 1) |
| You control how the PDFs are generated | Embed all fonts at source (Fix 2) |
| Comparing PDF against DOCX | Convert to a common format first (Fix 3) |
| Font uploaded but still substituting | Check the exact font name and upload every variant |
## Related articles