Supplier welcome letter (example)

An example for learning the drafting library — not suitable for real-world use. The organisation, Calderbrook Housing Group, and every detail about it are fictional. Every page of every export says Example document — not suitable for real-world use, and each letter carries a draft banner until someone marks it reviewed.

An automated letter is one nobody writes: another system asks for it when something happens and files what comes back. This one welcomes a supplier once they're approved: their supplier number, the details on record, how to invoice, when and how payment is made, and a warning about payment fraud, with the site rules added for a works contractor. You can produce it in Ferrith Chat like any other document, or from your finance system through the API: see Produce it from another system.

What's inside

• A document type, Supplier welcome letter (example): a letterhead and an opening, then Your details on our records, Sending us invoices, How and when we pay, Working in residents' homes and on our sites and Protecting you from payment fraud, then the closing. Nothing is numbered, the title names the supplier and their number, and the footer carries the organisation's registration line, the supplier number and the page numbers.
• 8 building blocks, from Letterhead to Closing.
• 26 fields, grouped on the form as The supplier, Paying the supplier, Our contact and Our organisation (set by the workspace). Payment terms (days) (30) and Invoices are sent by (email) arrive pre-filled, and a member may change them. The organisation's details are fixed: set by the workspace and read-only on the form, so a change of address reaches every letter produced after it.

Templates and selection tests aren't in the pack, so the import adds only what the document type needs. Build a template and Build the selection test describe the ones this example was designed around.

The new starter welcome letter is its companion: the same organisation, a letter from an HR system.

Import it

1. Download the zip and import it: Drafting → Drafting library → Document types → Import a library. How importing a library works covers each step.
2. If your workspace already has the organisation's fields (the new starter welcome letter brings Organisation name, Organisation address, Main telephone number, Registration line and Logo too), choose Use the existing field for each, so one change reaches both letters.
3. On the Blocks tab, open each of the eight blocks and choose Publish.
4. Download the logo, calderbrook-logo.png. On the Fields tab, open Logo, upload it as the default, switch Members may change it off and save. Pictures don't travel in a library: without a default, the letterhead prints [Logo].
5. If you like, set the organisation's fields to your own details on the Fields tab; they print in the letterhead, the letter and the footer.
6. The document type arrives restricted to you. Widen its Who can use when others should try it.

Build one yourself

On the Drafting page choose New draft, pick Supplier welcome letter (example), then Build it myself:

• Letterhead, Opening and Closing are already in the plan and can't be removed: the document type always includes them.
• Tick Your details on our records, Sending us invoices, How and when we pay and Protecting you from payment fraud.
• Continue to the form. The organisation's details show read-only; Payment terms (days) and Invoices are sent by are pre-filled, and Reset to default brings a changed one back.
• Set Supplier category to Works contractor: Working in residents' homes and on our sites joins the plan by itself, with the insurance minimums in figures and words.
• Leave Contact name empty: the letter writes to Dear Sir or Madam and closes Yours faithfully. Give a name and it becomes Dear and the name, closing Yours sincerely.
• Leave VAT registration number empty: the details table says Not registered for VAT and the invoice checklist asks for a note instead.
• Change Invoices are sent by to Supplier portal or Post: Sending us invoices gives that route instead of the invoice mailbox.
• Assemble, then export as Word or PDF: the letterhead with the logo, the details table, the numbered invoice checklist and the footer print in both.

Ask the AI

Choose New draft → Ask the AI, pick the letter and paste one of the briefs below. The three blocks the type always includes, and the block the rules add, come in either way.

A works contractor

Kestrel Property Maintenance Ltd was approved as a supplier on 5 October 2026, supplier number 100234. They're a works contractor at Unit 7, Avon Trade Park, Keynsham, Bristol BS31 9ZZ, and our contact there is Jo Bloggs. They'll invoice by email on 30-day terms.

• Picks: Your details on our records, Sending us invoices, How and when we pay and Protecting you from payment fraud.
• From your brief offers, usually quoted from the brief: the supplier's name, number and address, the contact, Works contractor as the category, the approval date and email as the invoice route. Accept them and Working in residents' homes and on our sites joins the plan.

A goods supplier

Brightline Office Supplies, 14 Station Road, Chippenham SN15 9ZZ, supplier number 100235, approved on 5 October 2026 to supply stationery. They'll send their invoices through our supplier portal.

• Picks: the same four blocks.
• Leaves out: Working in residents' homes and on our sites.
• From your brief: the name, number and address, Goods as the category, the approval date and the supplier portal.

The AI chooses from each block's description and Use when note, and from the document type's guidance; it never sees a block's text.

Build a template

A template fixes the blocks a letter starts with, so a member goes straight to the form, and it's what the API produces documents from. Once the blocks are published, choose + New template on the library's Templates tab:

• Name: Supplier welcome letter.
• Document type: Supplier welcome letter (example).
• Blocks: Your details on our records, Sending us invoices, How and when we pay and Protecting you from payment fraud. The three blocks the type always includes are added for you, and Working in residents' homes and on our sites arrives whenever the form says Works contractor.
• Require a review before export: off. A letter produced by another system has no one waiting to review it, and with the review on, the API's download waits until someone does.

Save it, then choose New draft → Use a template: the plan is fixed, and the draft opens on the form. Templates in the user guide covers the editor.

Build the selection test

A selection test checks the AI's picks for a brief. Once the blocks are published, choose + New selection test on the library's Selection tests tab:

Goods supplier — the brief from A goods supplier:

• Must pick: Your details on our records, Sending us invoices, How and when we pay and Protecting you from payment fraud.
• Must not pick: Working in residents' homes and on our sites.

Then choose Run all; it should pass. Each run is one model call on your workspace's allowance. Selection tests in the user guide explains the scores.

Produce it from another system

The letter was built to be produced with no one opening Ferrith Chat. When a supplier is approved, your finance system, or anything that holds the supplier record, posts the supplier's details to the template through the document templates API and files the PDF it gets back. You need the Automation plan, the template above, and an API key with the document-templates:read, documents:write and documents:read scopes.

1. Read the template's questions: GET https://api.ferrith.ai/document-templates/{TEMPLATE_ID} returns its inputSchema, with the organisation's fields marked read-only.

2. Post the supplier's details. Replace {TEMPLATE_ID} with the template's id from the list of templates (GET https://api.ferrith.ai/document-templates):

   bash

   curl -X POST -H "Authorization: Bearer fck_EXAMPLE_REPLACE_WITH_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"title": "Supplier welcome letter — Kestrel Property Maintenance Ltd (100234)", "strict": true, "input": {"supplier": {"number": "100234", "name": "Kestrel Property Maintenance Ltd", "address": "Unit 7, Avon Trade Park\nKeynsham\nBristol BS31 9ZZ", "contact_name": "Jo Bloggs", "category": "Works contractor", "approved_on": "2026-10-05", "invoice_channel": "Email", "remittance_email": "accounts@kestrel-maintenance.example", "bank_account_ending": "4821"}}}' \
     "https://api.ferrith.ai/document-templates/{TEMPLATE_ID}/documents"
   

3. Download the letter from the response's pdf link, as bytes or with ?encoding=base64 as JSON.

What the posting system needs to get right:

• Nest the keys: supplier.vat_number is posted as "supplier": { "vat_number": "…" }, inside "input".
• Leave out an answer you don't have rather than sending an empty value, which is refused. A missing optional answer takes the letter's other wording: no contact name writes to Sir or Madam, no VAT number prints Not registered for VAT.
• Dates as yyyy-MM-dd, numbers as JSON numbers, and a choice exactly as its option, such as "Works contractor".
• Never post the organisation's fields: they're fixed by the workspace, and posting one is refused.
• "strict": true refuses a letter with a missing answer instead of producing one with a marker in it.

Letters produced this way carry the draft banner too, until someone marks them reviewed in the app. In a library of your own, switch the banner off on the document type and replace the example header with your own.

What it shows

Related: producing a document and the drafting library in the user guide, and document templates in the API guide.