# Diaries



Overview [#overview]

Diaries are a structured, user-driven log of notes in relation to a given entity. For example, a running series of notes relating to management of a policy transaction (such as a cancellation and the reasons for it, or notes of conversations with the insured), could be captured in a series of diary entries.

You can associate diaries with the following entities:

* Policies
* Quotes
* Transactions
* Underwriting flags
* Accounts
* Invoices
* Payments
* FNOLs
* Tasks
* Elements

<Callout>
  Diary entries can be associated with elements within a quote or policy segment using their `staticElementLocator`. This locator remains the same throughout the quote and policy lifecycle, meaning a diary entry associated with a quote element will remain associated with all of its corresponding policy segment elements.
</Callout>

Diary Entries [#diary-entries]

The primary diary element is called a <ApiLink name="DiaryEntryResponse">Diary Entry</ApiLink>. For each of the supported entity types, a series of entries can be created. Each is timestamped and can be given an optional `category` value.

Diary entries are referred to by either a `locator` (which is specific to a given diary entry) or a `referenceLocator` (such as a quote or policy locator) which will indicate all the diary entries for that entity. The endpoints <ApiLink name="fetchLatestDiaryEntryByLocator" /> or <ApiLink name="fetchLatestDiaryEntriesByReference" /> are used for these two types of retrieval. The former will return a single diary entry, and the latter can return multiple entries.

Revisioning [#revisioning]

When a diary entry for an entity is updated with the <ApiLink name="updateDiary" /> endpoint, old entries are not removed. Rather, they remain accessible with the <ApiLink name="fetchAllDiaryEntriesByLocator" /> endpoint. To see only the latest entries, use either the <ApiLink name="fetchLatestDiaryEntryByLocator" /> or <ApiLink name="fetchLatestDiaryEntriesByReference" /> endpoints.

Discard [#discard]

Diary entries may be <ApiLink name="discardDiary">discarded</ApiLink>, which means they will no longer be available except by direct reference by locator.

<Callout>
  The discard function will discard the entry as a whole, including all revisions. To keep the entry, you may want to simply <ApiLink name="updateDiary">update</ApiLink> it, which will exclude the existing entry from the "latest" fetch endpoints.
</Callout>

See Also [#see-also]

* [Diary API](/api/aux-data/diary)