# SaveClaimDocument - Advanced Documentation

## Model Shape

```javascript
{
  ID: -1,                 // -1 = create, existing ID = update
  Name: "invoice-2026-08.pdf",
  Type: { ID: 42 },       // required, ID > 0
  Parent: { ID: 771360 }, // required, ID > 0 - the claim
  File: {
    StorageName: "<from FileService.GetUploadUrl, after PUT completed>",
    IsURLOnly: false,
    ObjectSize: 482913    // real byte count
  }
}
```

## Traps

- `File.ObjectSize` defaults to `-1`. Non-URL files must set it to the real byte count or the call throws `"Non Url Files must have an object size."` Skipped only when `IsURLOnly: true`.
- File must already exist in S3 (see `FileService.GetUploadUrl`) - save re-checks and throws `"This file no longer exists in storage. Please refresh the page and try again."` if it doesn't.
- `Document.Name` blank falls back to `File.Name`; either way `File.Name` is overwritten to match the final cleaned name after save.
- Same Name/TreePrefix/Type already exists -> `"This folder already contains a document with that name. Please provide a unique name."`

## Script Example

```javascript
async () => {
  const document = {
    ID: -1,
    Name: "invoice-2026-08.pdf",
    Type: { ID: 42 },
    Parent: { ID: 771360 },
    File: { StorageName: "3f2b9a1c-6e3d-4b2a-9c1f-8d7e6a5b4c3d", IsURLOnly: false, ObjectSize: 482913 }
  };
  const result = await SecureApi.SaveClaimDocument(document);
  return { id: result.ID, fileId: result.File?.ID };
}
```

## Cross-References

| Need | Use |
|------|-----|
| Get a presigned upload URL | `FileService.GetUploadUrl(FileName, FileSize)` |
| Add multiple documents in one call | `SecureApi.AddClaimDocuments(ParentID, Documents)` |