Ownership model (agency vs agent)

Every form in InsurGrid is owned at one of two scopes: agency or agent. Ownership determines who can manage a form and how its submissions are attributed — get this right before you start creating forms via the API.

The two scopes

Scope	Meaning	Set at create time
Agency	Owned by the agency as a whole; shared across all its agents. Used for standard, agency-wide intake forms.	owner: { "type": "agency", "agency_id": 1201 }
Agent	Owned by one specific agent within the agency.	owner: { "type": "agent", "agency_id": 1201, "agent_id": 88213 }

You set owner when you create a form (POST /v2/forms), and it doesn't change afterward. Every form also records who created it and who last edited it, regardless of scope.

New term — scope: which entity a resource belongs to. Here, a form is scoped either to an entire agency or to one agent inside it — scope controls both who can manage it and who submissions are attributed to.

Who can do what

Role	Create / update / publish / archive forms	Share / embed existing forms	Receive submissions
Owner / admin	Yes (agency-wide)	Yes	Yes
Ordinary agent	No	Yes	Yes

A write call outside the caller's permission returns 403; a form outside the caller's visibility (for example, another agency's form) returns 404. See Errors & status codes.

The public fill link is always per-agent

Regardless of a form's ownership scope, its public fill link is generated per agent — the agentSlug in the embed/share URL determines which agent a submission is attributed to. One agency-owned form can be shared under many different agent slugs, and each submission through it credits the right agent.

https://app.insurgrid.com/f/apartment-intake-acme?agentSlug=jane-smith&embed=1

Two agents sharing the same agency-owned form get different URLs (different agentSlug), and submissions through each are attributed accordingly — even though it's the same underlying form.

Why this matters for your integration

• When you list forms with GET /v2/forms, filter or group by owner if you need to show "my forms" vs. "agency forms" in your UI.

• When you receive a form-submission webhook, the agent object in the payload tells you which agent the submission is attributed to — see Webhook events & payloads.

• If a write call your app makes returns 403, don't retry — the token's role doesn't have permission. Check whether the caller should be using an owner/admin token instead.

Related

• Form structure & conditional logic

• The two embeds (builder vs fill form)

• Errors & status codes

• Quickstart C — Build forms via the API