New starter welcome letter (example)

An example for learning the drafting library — not suitable for real-world use. The organisation, Calderbrook Housing Group, its people 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 new starter: where and when to arrive, what to bring and who to ask, signed by the Head of People, with an enclosed page setting out the first week and the main terms. You can produce it in Ferrith Chat like any other document, or from your HR system through the API: see Produce it from another system.

What's inside

• A document type, New starter welcome letter (example): an opening, Your first day and What to bring, then the closing with the signature; Your first week starts a new page, followed by Your main terms at a glance. Nothing is numbered, the title names the starter and their employee number, the header carries the organisation's logo on every page, and the footer carries the registration line and the page numbers.
• 7 building blocks, from Opening to Your main terms at a glance.
• 28 fields, grouped on the form as The new starter, The job, The first day and Our organisation (set by the workspace). The start time (9:00am), hours (37.5 a week), holiday (27 days), probation (6 months), equipment (a laptop and an ID badge) and whether the right to work is already checked (no) arrive pre-filled, and a member may change them. The organisation's details and the signatory are fixed: set by the workspace and read-only on the form.

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 supplier welcome letter is its companion: the same organisation, a letter from a finance 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 supplier 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 seven blocks and choose Publish.
4. Download the two pictures, calderbrook-logo.png and calderbrook-signature.png. On the Fields tab, open Logo, upload the logo as the default, switch Members may change it off and save; then the same for Signatory's signature with the signature. Pictures don't travel in a library: without them, the header prints [Logo] and the closing [Signatory's signature]. If you already gave Logo a picture for the supplier letter, it's done.
5. If you like, set the organisation's fields and the signatory to your own details on the Fields tab; they print in the opening, the closing, the footer and the enclosure.
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 New starter welcome letter (example), then Build it myself:

• Opening and Closing are already in the plan and can't be removed: the document type always includes them.
• Tick Your first day, What to bring, Your first week and Your main terms at a glance.
• Continue to the form. The organisation's details and the signatory show read-only; the start time, hours, holiday, probation and equipment are pre-filled, and Reset to default brings a changed one back.
• Tick pool car under Equipment we'll provide: Driving for work joins the plan by itself, asking the starter to bring a driving licence. The equipment prints as one sentence: "your laptop, ID badge and pool car".
• Set Work pattern to Home-based: the first day becomes a welcome call from the line manager, the equipment is delivered to the starter's home, and the letter no longer names an office.
• Answer Right to work already checked with yes: the passport line leaves What to bring.
• Set Contract to Fixed term and answer Fixed term ends on: the terms show when the contract ends.
• Assemble. The letter ends with the signature, Your first week starts a new page, and the probation's end date is worked out from the start date. Export as Word or PDF: the logo, the signature, the tables and the new page print in both.

Ask the AI

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

A hybrid starter with a pool car

Sam Taylor joins us as a Repairs Planner in Property Services on Monday 2 November 2026, reporting to Priya Nair. Permanent, hybrid, based at our Bath office. Sam lives at 14 Elm Grove, Frome BA11 9ZZ, and their employee number is E10457. Sam needs a laptop, a mobile phone, an ID badge and a pool car.

• Picks: Your first day, What to bring, Your first week and Your main terms at a glance.
• From your brief offers, usually quoted from the brief: Sam's names, address and employee number, the job, the team, the line manager, the start date, Hybrid, Bath, Permanent, and the four items under Equipment we'll provide. Accept them and Driving for work joins the plan.

A home-based starter on a fixed term

Alex Morgan starts as an Income Officer in Rent and Income on 9 November 2026, working from home on a fixed-term contract ending 8 November 2027, with Dan Price as line manager. Alex lives at 3 Quarry Close, Corsham SN13 9ZZ, employee number E10458. A laptop only; Alex's right to work has already been checked.

• Picks: the same four blocks.
• Leaves out: Driving for work.
• From your brief: Alex's details, the job and team, the start and end dates, Home-based, Fixed term, a laptop under Equipment we'll provide and yes to Right to work already checked.

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: New starter welcome letter.
• Document type: New starter welcome letter (example).
• Blocks: Your first day, What to bring, Your first week and Your main terms at a glance. The two blocks the type always includes are added for you, and Driving for work arrives whenever the equipment includes a pool car.
• 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:

Home-based, fixed term — the brief from A home-based starter on a fixed term:

• Must pick: Your first day, What to bring, Your first week and Your main terms at a glance.
• Must not pick: Driving for work.

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 new starter is set up, your HR system, or anything that holds the employee record, posts the starter'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 and the signatory marked read-only.

2. Post the starter'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": "New starter welcome letter — Sam Taylor (E10457)", "strict": true, "input": {"employee": {"number": "E10457", "first_name": "Sam", "full_name": "Sam Taylor", "address": "14 Elm Grove\nFrome BA11 9ZZ", "job_title": "Repairs Planner", "team": "Property Services", "manager_name": "Priya Nair", "start_date": "2026-11-02", "work_pattern": "Hybrid", "office": "Bath", "contract_type": "Permanent", "equipment": ["laptop", "mobile phone", "ID badge", "pool car"]}}}' \
     "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: employee.start_date is posted as "employee": { "start_date": "…" }, 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, and a missing default takes the default: leave out the start time and the letter says 9:00am.
• Dates as yyyy-MM-dd, numbers and yes or no as JSON (37.5, true), a choice exactly as its option ("Home-based"), and several choices as a list (["laptop", "pool car"]).
• Never post the organisation's fields or the signatory: 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.