# GetClaimMergeDocumentUrl - Advanced Documentation

## Overview
Returns a ready-to-fetch URL that generates a Word document from a claim merge template, for one claim and one contact on that claim. Use it when the user wants a letter or form built from a claim and a person on it (for example, a letter to a claim contact). 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 `Claim`. Find these templates with `SecureApi.GetMergeTemplatesByTypeName("Claim")`.

## Parameters
All four parameters are required.

| Parameter | Type | What it identifies | Where to get it |
|-----------|------|--------------------|-----------------|
| ClaimID | number | The claim to merge | `SecureApi.SearchClaimsBySystemFieldString` (each result has an ID), or the ID the user already gave you |
| TemplateID | number | The claim merge template | `SecureApi.GetMergeTemplatesByTypeName("Claim")` (each result has an ID) |
| ContactID | number | The contact the document is addressed to or about | `SecureApi.GetClaimContacts(ClaimID)`; use the `Contact.ID` of the claim contact you want (not the claim contact's own 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("Claim")` 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 claim, the contact, 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
The endpoint adds these two entries itself from ClaimID, exactly as the application does when it builds this document:
- Prefix `Claim`, RecordType `Claim`, RecordID = ClaimID
- Prefix `Claimant`, RecordType `Contact`, RecordID = the claim's claimant contact ID

Prompts carries only what the template itself declares. If the claim does not exist or has no claimant, the endpoint returns an error naming the ClaimID.

## Example
Claim 303, template 101, contact 202. The template declares one Staff prompt (Prefix "Attorney") and one FillIn prompt (Prefix "Re"):

```
DocumentGenerationApi.GetClaimMergeDocumentUrl(
  ClaimID: 303,
  TemplateID: 101,
  ContactID: 202,
  Prompts: [
    { Prefix: "Attorney", RecordType: "Staff", RecordID: 55, FillInValue: "Pat Smith" },
    { Prefix: "Re", RecordType: "FillIn", FillInValue: "Status of your case" }
  ]
)
```

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, when you are not logged in or have no company selected, or when the claim or its claimant cannot be found. It does not check the template, contact, or prompt values when it issues the URL. Those are checked when the URL is opened, so a bad template, contact, or prompt 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.