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. insured_name is limited to 100 characters. 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.

Dedicated Account Number

Every insured gets its own account number for incoming payments, returned as virtual_account on the insured. Payments the insured sends there by ACH or wire land in your collection account and are attributed to that insured automatically.

The account is set up automatically shortly after the insured is created. Until then virtual_account is null.

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.