Contact requests

Many records live only in a box: county probate files, church registers, pension files, letters held by a state archive. The report (POST /v1/subjects/{id}/report) lists them under not_online, each with the plan nodes it covers and the archives that could hold the records. A contact request turns one of those rows into a letter a person can send.

The flow

• Draft: POST /v1/contact-requests with subject_id and a node_id from not_online[].node_ids, or a record description. The response has the letter (email_subject and body), the archive's address, the page it was read from and the date, and delivery: a mailto link, the archive's form, its postal address and a printable PDF.
• Review and edit: PATCH /v1/contact-requests/{id} with email_subject, body, record or requester, while the status is drafted.
• Send it yourself: open the mailto link in your own email, use the archive's form, or print GET /v1/contact-requests/{id}/letter and post it. Then POST /v1/contact-requests/{id}/sent with via (email, post or form).
• Paste the reply: POST /v1/contact-requests/{id}/reply with the text. Lineage reads it as a fee quote (with amount and currency), a question, a record attached (with a citation line: Received from the archive by letter, and the date) or a decline, which closes the request.
• Follow up once: POST /v1/contact-requests/{id}/follow-up, from 14 days after the letter was marked sent, if no reply has come.
• Pay any fee to the archive directly. Lineage never pays or collects archive fees.

Draft from a plan node

curl https://api.lineage.rexstjohn.com/v1/contact-requests \
  -H "Authorization: Bearer $LINEAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject_id": "sub_...", "node_id": "node_..."}'

The record fields come from the node (record types, years, place). archive_id is optional: left out, the best match for the node's source and the subject's places is used.

Draft a specific record

curl https://api.lineage.rexstjohn.com/v1/contact-requests \
  -H "Authorization: Bearer $LINEAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject_id": "sub_...", "archive_id": "us-ky-kdla", "record": {"description": "Marriage bond of Thomas Lincoln and Nancy Hanks", "date": "1806", "place": "Washington County, Kentucky"}, "requester": {"name": "Ada Researcher", "email": "ada@example.com"}}'

{
  "object": "contact_request",
  "id": "cr_9fK2mQ7xLp4Vn8Rt1Ab3",
  "status": "drafted",
  "archive": {
    "id": "us-ky-kdla",
    "name": "Kentucky Department for Libraries and Archives",
    "language": "en"
  },
  "to": {
    "email": null,
    "postal": [
      "Archives Research Room",
      "Kentucky Department for Libraries and Archives",
      "P.O. Box 537",
      "300 Coffee Tree Road",
      "Frankfort, KY 40602"
    ],
    "form_url": "https://secure.kentucky.gov/formservices/KDLA/RecordsOrdering"
  },
  "address_verification": {
    "source_url": "https://kdla.ky.gov/Archives-and-Reference/Pages/Records-Requests.aspx",
    "checked_at": "2026-11-02"
  },
  "email_subject": "Records request: Thomas Lincoln (1778 to 1851)",
  "delivery": {
    "sent_by_lineage": false,
    "mailto": "mailto:...",
    "letter_pdf_url": "https://api.lineage.rexstjohn.com/v1/contact-requests/cr_9fK2mQ7xLp4Vn8Rt1Ab3/letter"
  },
  "credits_spent": 0
}

The example archive and its address are real entries in the directory; the request id is an example.

Rules, enforced in code

• Lineage drafts; a person sends. Nothing is sent by Lineage, by email or by post.
• The archive's address is read on its own official site, stored with that page's URL and the date, and re-checked at least every 90 days or the draft is refused.
• No requests about anyone who may be alive: the subject must have passed the living-person gate, and living relatives never appear in a letter.
• Archive opt-outs are checked before every draft.
• One draft per record, and one follow-up draft 14 days after the first is marked sent.
• At most 25 drafts to one archive in any 7 days, across all accounts.
• Plain text, in the archive's language, and every letter says how the requester found the archive.
• Lineage never pays or collects archive fees. The person pays the archive directly.

The living-person gate runs before every draft: the subject must have a death date on record or a birth more than 110 years ago, or the request returns living_person_blocked and nothing is stored. Record fields and edits that name someone born within 110 years, or say someone is alive, are refused the same way. Living relatives never appear in a letter.

The archive directory

GET /v1/archives (no key) lists 12 archives. Each address was read on the archive's own official site, and the entry keeps that page's URL, the date it was read and the words that contain the address. Nothing comes from a third-party directory and nothing is guessed. A draft is refused when the check is older than 90 days, until the address is read again.

Errors

For archives

Archives can ask to receive no drafts, or correct their listing; see https://api.lineage.rexstjohn.com/archives. An opt-out is checked before every draft.