# AMS Book Sync

Read and write client records, policies, and activity notes in the agency's AMS (agency management system — the system of record for an insurance agency's book of business) through an org Integration row that injects per-host authentication.

## When to use

- A human needs a client's current policy list, contact details, or recent activity log pulled from the AMS before a call or renewal review.
- A new client, updated contact detail, or activity note needs to be written back into the AMS after a call, email, or meeting.
- A policy record needs a status or detail update (e.g., renewal date, mailing address) that only touches non-coverage fields.
- Someone asks you to interpret coverage, confirm binding, recommend limits/carriers, or discuss a claim's fault or applicability.

## Tools

- `http-get`
- `http-post`
- `http-request`

## Playbook

1. Confirm the org's Integration row for the AMS host is active before making any call; if missing, stop and use send-message to notify a human, naming the service and scopes needed.
2. To look up a client, `http-get` the AMS REST API, e.g. `GET https://api.youragencyams.com/v1/clients?q=<name-or-id>`.
3. To pull a client's policies, `http-get` e.g. `GET https://api.youragencyams.com/v1/clients/{client_id}/policies`.
4. To create a new client record, `http-post` e.g. `POST https://api.youragencyams.com/v1/clients` with the validated contact fields.
5. To log an activity (call summary, email note, meeting recap), `http-post` e.g. `POST https://api.youragencyams.com/v1/clients/{client_id}/activities`.
6. To update non-coverage policy fields (mailing address, renewal reminder date, contact phone), use `http-request` for the PATCH, e.g. `PATCH https://api.youragencyams.com/v1/policies/{policy_id}`.
7. If a request involves issuing a certificate of insurance (COI) for a non-standard holder, adding or changing an endorsement, recommending a limit or carrier, or answering a coverage-applicability question, stop the automated flow and route it as a human handoff via send-message to a licensed agent.
8. If a claim is mentioned, only capture and forward the report details (date, description, parties involved) via `http-post` to the AMS activity log — never discuss fault or whether coverage applies.
9. Confirm each write succeeded by checking the returned status/id before reporting completion; on failure, do not retry silently — surface the error.

## Failure modes

- Integration row missing or expired credentials: every `http-get`/`http-post`/`http-request` call returns 401/403 — stop immediately and message a human naming the AMS and the scopes needed, never ask for or handle credentials directly.
- Ambiguous client match (multiple records for a name): do not guess — surface the candidate list to a human for disambiguation before writing anything.
- Coverage or claims questions arriving disguised as data lookups (e.g., "will this policy cover X"): recognize these as compliance-gated and escalate to a licensed agent rather than answering from AMS data.
- Partial write success (e.g., client created but activity log post fails): report the partial state clearly so a human can complete the missing step manually.

## Done when

- The requested client, policy, or activity data has been retrieved and returned in full, or the requested non-coverage update has been written and confirmed via the AMS API response.
- Any coverage advice, binding confirmation, limit/carrier recommendation, non-standard COI issuance, endorsement, or claims fault discussion has been declined and handed off to a licensed agent instead of attempted.