# GetLedgerMergeDocumentUrl - Advanced Documentation

## Overview
Returns a ready-to-fetch URL that generates a Word document by merging an Invoice or Disbursal merge template with one ledger entry on a claim. Use it when the user wants a document built from a single ledger entry (a time or expense entry). The URL has the caller's identity already embedded, so a plain GET with no cookies or headers returns the document. The document is generated when the URL is fetched, for the company and staff member who requested the URL.

The endpoint merges the given template with the ledger entry, which it injects as RecordType `Ledger` with Prefix `Ledger`. Ledger documents use Invoice or Disbursal templates. Find them with `SecureApi.GetMergeTemplatesByTypeName("Invoice")` or `SecureApi.GetMergeTemplatesByTypeName("Disbursal")`.

## Parameters
All four parameters are required.

| Parameter | Type | What it identifies | Where to get it |
|-----------|------|--------------------|-----------------|
| ClaimID | number | The claim the ledger entry belongs to | `SecureApi.SearchClaimsBySystemFieldString` (each result has an ID), or the ID the user already gave you |
| TemplateID | number | The Invoice or Disbursal merge template | `SecureApi.GetMergeTemplatesByTypeName("Invoice")` or `("Disbursal")` (each result has an ID) |
| ItemID | number | The ledger entry to merge | `SecureApi.GetClaimLedgerEntries(ClaimID)` (each entry has an ID) |
| Prompts | list | The values for the prompts the template itself declares | See "Prompts" below. Required: pass an empty list `[]` when the template declares no prompts. Passing nothing is an error |

## Discovering a template's prompts and fields
1. Call `SecureApi.GetMergeTemplatesByTypeName("Invoice")` or `("Disbursal")` and pick the template. This list does not include the template's prompts or fields.
2. Call `SecureApi.GetMergeTemplateByID(TemplateID)`. This returns the full template, including `Prompts` and `Fields`.
3. Read `Prompts`. Each one is a question the template asks before it can merge:
   - `Prefix` - the prompt's name. Your prompt entry must use the same Prefix.
   - `RecordType` - what kind of answer it needs (Staff, Claim, Contact, Claimant, FillIn and so on).
   - `RecordID` - not filled in on the template; you supply it in your entry.
   - `DisplayValue` - not filled in on the template; you supply a readable value in your entry.
   - `CompanyStaffRole` - only for Staff prompts; the staff role the answer is meant to fill.
   - `ID` - the prompt's own identifier; not needed in your entry.
4. Read `Fields`. Each field is one placeholder in the Word document (`Name`, `FieldSource`, `FieldPath`, `MergeColumnName`). Most fields are filled in automatically from the records (the ledger entry, the claim, the claimant, and the records they link to) and need nothing from you. A field that has a `PromptName` and `PromptRecordType` gets its value from the prompt whose Prefix matches that PromptName, which is why every declared prompt must have an entry.

## Prompts
Each entry in Prompts answers one prompt the template declares:

| Property | Meaning |
|----------|---------|
| Prefix | The Prefix of the template prompt being answered |
| RecordType | The template prompt's RecordType, sent exactly as the template declares it. Valid values: `Staff`, `Claim`, `ClaimContact`, `Contact`, `FillIn`, `Request`, `Claimant`, `Ledger`. Any other value is rejected |
| RecordID | The ID of the record that answers the prompt. Use it for every RecordType except FillIn |
| FillInValue | The text to merge. For FillIn prompts this is the answer itself. For the other types, send the record's display name, as the application does |

What to send as RecordID by RecordType:
- `Staff` - the staff member's person ID (`SecureApi.GetClaimStaff(ClaimID)`, matching the prompt's `CompanyStaffRole`).
- `Contact` - the claim contact's own ID from `SecureApi.GetClaimContacts(ClaimID)` (the `ID` of the claim contact, not its `Contact.ID`). Still send the RecordType as `Contact`; the endpoint converts it for you.
- `FillIn` - no RecordID; put the text in FillInValue.

### Entries the endpoint adds automatically - do NOT send these
- Prefix `Claim`, RecordType `Claim`, RecordID = ClaimID
- Prefix `Claimant`, RecordType `Claimant`, RecordID = ClaimID
- Prefix `Ledger`, RecordType `Ledger`, RecordID = ItemID

Prompts carries only what the template itself declares.

## Example
Ledger entry 808 on claim 303, using Invoice template 101, which declares one FillIn prompt (Prefix "Note"):

```
DocumentGenerationApi.GetLedgerMergeDocumentUrl(
  ClaimID: 303,
  TemplateID: 101,
  ItemID: 808,
  Prompts: [ { Prefix: "Note", RecordType: "FillIn", FillInValue: "Reviewed by accounting" } ]
)
```

A template with no prompts: `Prompts: []`.

## Result
A single URL string with authorization already embedded; there is no token to extract and no second call to make. Return the URL to the caller as the script result rather than fetching it yourself. The calling LLM downloads the document into its own environment.

## Limits
The URL expires about 5 minutes (300 seconds) after it is issued. Request a fresh URL each time instead of caching, reusing, or retrying an old one.

Use the URL exactly as returned - do not reorder, add to, or otherwise modify its query string.

## Errors
This endpoint returns an error when Prompts is missing, or when you are not logged in or have no company selected. It does not check the template, ledger entry, or prompt values when it issues the URL. Those are checked when the URL is opened, so a bad value shows up as an error page at fetch time. If the fetched page is not a Word document, read it for the reason, fix the input, and request a new URL.