/api/applications/ID/offers/ID/letters

Letterheads are document templates that can be used to generate attachments to offers.

In reality, there is also a middle-step in that process — first a Letter is created from the Letterhead. Such a Letter represents a generated (and potentially user-customised) document, where each template marker has already been replaced by actual applicant data. For the purposes of attaching to an offer, the Letter is converted to a PDF and attached to an offer just like a regular uploaded PDF. All of this happens seamlessly in the UI, however, for the API the entire data model is explicitly shown.

Fetching a list of the Letters is usually not useful for the API consumers. The GET calls are only offered for the sake of completeness.

The only useful call here is the one to generate a new letter. As a matter of convenience, such letters get also attached automatically to the offer in question. Read more below.

HEAD, GET

Get a list of all letters that have been generated from

Syntax

GET /api/applications/123/offers/321/letters
Host: apply.example.edu
Authorization: DREAM apikey="..."

Response headers

Content-Type: application/json
Content-Length: 1234
X-Count: 1

Response example

{
  "1": {
    "id": 1,
    "rendered": "2025-01-02T15:44:09+00:00",
    "letterhead": "/api/letterheads/1",
    "administrator": null
  }
}

POST

This allows to generate a new offer attachment from a letterhead.

The process is actually comprised of 3 stages:

  1. A letter is generated from a letterhead
  2. The letter is rendered to PDF
  3. The PDF file is attached to the offer

This POST call, by the semantics of it, is meant to allow step 1 — the creation of the letter. But a bare letter, on its own, is pretty useless. Therefore, as a matter of convenience, this call also renders the PDF file and attaches it to the offer.

Note that this call is equivalent to the “one click attach” feature in the offer dialog. The same limitations apply:

  • There should not already be a pre-existing letter generated from this letterhead. Otherwise, this call could overwrite existing user customisation beyond the letterhead template. Keep in mind that the letterhead template can (and often is) edited when generating (and attaching) a letter.
  • The letterhead template markers should all be possible to correctly fill. For example, if there is a marker to replace the applicant's phone number, the call will not work if the phone number field is not properly filled in the application. In short, this call only allows for the “happy path”, as it does not offer ways to recover from errors or substitute missing information.

Syntax

POST /api/applications/123/offers/321/letters
Host: apply.example.edu
Authorization: DREAM apikey="..."

Parameters

Name Description
letterhead Required Letterhead ID to use as the template for generating this letter

Response headers

Content-Type: application/json
Content-Length: 0
Location: /api/applications/123/offers/321/letters/1001

Response codes

201 Created New letter was created, rendered to PDF and attached to the offer
400 Bad Request The letterhead ID was not provided as a parameter
404 Not Found The letterhead was not found
400 Bad Request There is already a pre-existing letter generated from this letterhead
400 Bad Request Errors or warnings were encountered when filling the letterhead markers