# GetDisbursalMergeDocumentUrl - Advanced Documentation

## Overview
Returns a ready-to-fetch URL that generates a Word document from a disbursal merge template, for one disbursal on a claim. Use it when the user wants the printed document for a disbursal. 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 template must be of the merge template type named `Disbursal`. Find these templates with `SecureApi.GetMergeTemplatesByTypeName("Disbursal")`.

## Parameters
All four parameters are required.

| Parameter | Type | What it identifies | Where to get it |
|-----------|------|--------------------|-----------------|
| ClaimID | number | The claim the disbursal belongs to | `SecureApi.SearchClaimsBySystemFieldString` (each result has an ID), or the ID the user already gave you |
| TemplateID | number | The disbursal merge template | `SecureApi.GetMergeTemplatesByTypeName("Disbursal")` (each result has an ID). The disbursal also records its own `Template`; use it unless the user asks for a different one |
| ItemID | number | The disbursal to merge | The `Disbursals` list on `SecureApi.GetClaimWithoutNotes(ClaimID)` (each has an ID); `SecureApi.GetDisbursalByID(DisbursalID)` returns one in full |
| Prompts | list | Extra prompt values for the template, if it declares any that the disbursal did not already save | See "Prompts" below. Required: pass an empty list `[]` when there are none. Passing nothing is an error |

## Discovering a template's prompts and fields
1. Call `SecureApi.GetMergeTemplatesByTypeName("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 disbursal, 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.

## Prompts
The prompt values already saved on the disbursal are used automatically. Normally the application sends no extra prompts for a disbursal, so `Prompts: []` is the usual value. Only add an entry for a prompt the template declares that the disbursal did not save. Each entry answers one prompt:

| 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
- Every prompt value already saved on the disbursal

## Example
Disbursal 606 on claim 303, using disbursal template 101, with no extra prompts:

```
DocumentGenerationApi.GetDisbursalMergeDocumentUrl(
  ClaimID: 303,
  TemplateID: 101,
  ItemID: 606,
  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, disbursal, 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.