Insureds

Insureds represent the customers who receive invoices and pay premiums. Creating insured records before creating plans is recommended — it lets you link plans to a single source of truth for customer data, look up a customer's full history in one call, and filter plans and payment requests by insured.

Creating an Insured

POST /v1/insured

Only insured_name is required. Add as much contact and address detail as you have — it populates the invoice automatically when the insured is linked to a plan.

Use customer_external_id to store your own system's identifier for the insured (e.g., your AMS customer ID). This must be unique per tenant and enables a fast lookup without knowing the Advance insured_id. It's the recommended approach when syncing insureds from an external system — set it at creation and you can always retrieve the insured by your own ID.

Finding an Insured

Advance offers multiple lookup strategies depending on what you have available:

By Advance ID

GET /v1/insured/{insured_id}

Use when you've already stored the Advance ID in your system.

By your system's external ID

GET /v1/insured/customer_external_id/{customer_external_id}

The most reliable lookup for integrations — use your AMS or CRM customer code directly, no ID mapping required.

By email

GET /v1/insured/email/{email}

Useful for deduplication checks before creating a new insured — verify whether a customer already exists by their email address.

By exact company name

GET /v1/insured/name/{name}

Requires an exact match (case-insensitive). Best for scripted lookups where you control the input.

Search by partial name

GET /v1/insured?insured_name=acme

Returns all insureds whose name contains the search term. Good for user-facing search or when you only have a partial name.

Updating an Insured

PUT /v1/insured/{insured_id}

All fields are optional — only the fields you include are updated. This is safe to call with partial data; fields you omit are left unchanged.

Integration Pattern: AMS Sync

A common pattern for AMS integrations:

1. When processing a new customer in your AMS, call GET /v1/insured/customer_external_id/{your_ams_id} first.
2. If found (HTTP 200), use the returned insured_id for plan creation.
3. If not found (HTTP 404), call POST /v1/insured with customer_external_id set to your AMS ID, then use the new insured_id.

This keeps Advance in sync with your AMS without maintaining a separate ID-mapping table.