POST /oauth/token

Request Body

{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
}

Response

{
    "access_token": "YOUR_ACCESS_TOKEN",
    "token_type": "bearer",
    "expires_in": 3600
}

Use the returned access token in the Authorization header for all API requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Sample Code

curl -X POST \
  https://api.insurgrid.com/oauth/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
}'

GET /v1/agents

Lists all agents provisioned in the system.

Authentication

OAuth Client Access Token

Query Parameters

Response

Collection of agents with their details and their associated agencies

{
    "data": [
        {
            "id": 123,
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "slug": "john-doe-xyz",
            "phone_number": "555-123-4567",
            "is_admin": true,
            "agency": {
                "id": 456,
                "name": "Example Insurance Agency",
                "color_code": "3A71F8"
            }
        },
        // Additional agents...
    ],
    "links": {
        "first": "https://api.insurgrid.com/v1/agents?page=1",
        "last": "https://api.insurgrid.com/v1/agents?page=5",
        "prev": null,
        "next": "https://api.insurgrid.com/v1/agents?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "path": "https://api.insurgrid.com/v1/agents",
        "per_page": 25,
        "to": 25,
        "total": 125
    }
}

Implementation Notes

• Results are paginated
• Filtered by OAuth Client - only returns agents associated with agencies linked to the authenticated OAuth client

Sample Code

curl -X GET \
  'https://api.insurgrid.com/v1/agents?filterByEmail=john@example.com&includeDeactivated=false&page=1&perPage=25' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/json'

POST /v1/agencies

Creates a new agency and admin agent.

Authentication

OAuth Client Access Token

Request Body

{
    "agency_name": "Agency Name",
    "email": "agent@example.com",
    "first_name": "First",
    "last_name": "Last",
    "referral": "optional-referral-source"
}

Response

{
    "data": {
        "agency": {
            "id": 123,
            "name": "Agency Name",
            "color_code": "3A71F8"
        },
        "agent": {
            "id": 456,
            "first_name": "First",
            "last_name": "Last",
            "email": "agent@example.com",
            "slug": "first-last-xyz",
            "is_admin": true,
            "access_token": "OWNER_ACCESS_TOKEN"
        }
    }
}

Implementation Notes

• The created agency will be automatically associated with the authenticated OAuth client
• An owner agent is automatically created with admin privileges
• The returned access token should be securely stored for the agent

Sample Code

curl -X POST \
  https://api.insurgrid.com/v1/agencies \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "agency_name": "Example Insurance Agency",
    "email": "owner@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "referral": "Partner Program"
}'

POST /v1/agencies/:agency_id/agents

Adds a new agent to an existing agency.

Authentication

OAuth Client Access Token

Path Parameters

Request Body

{
    "first_name": "First",
    "last_name": "Last",
    "email": "agent@example.com",
    "slug_suffix": "custom-suffix",
    "phone_number": "202-555-0192",
    "is_admin": false
}

Response

{
    "data": {
        "id": 789,
        "first_name": "First",
        "last_name": "Last",
        "email": "agent@example.com",
        "slug": "first-last-custom-suffix",
        "phone_number": "202-555-0192",
        "is_admin": false,
        "access_token": "AGENT_ACCESS_TOKEN"
    }
}

Implementation Notes

• The agency must be associated with the authenticated OAuth client
• A unique slug is generated for the agent (can be customized with slug_suffix)
• Profile pictures must be sent using multipart/form-data

DELETE /v1/agencies/:agency_id

Deactivates an agency and all its agents.

Authentication

OAuth Client Access Token

Path Parameters

Response

Empty response with 204 No Content status code

Implementation Notes

• The agency must be associated with the authenticated OAuth client
• This action will deactivate all agents belonging to the agency
• Deactivated agencies can still be queried with the proper includeDeactivated flag

DELETE /v1/agents/:agent_id

Deactivates an agent as OAuth client.

Authentication

OAuth Client Access Token

Path Parameters

Response

Empty response with 204 No Content status code

Implementation Notes

• The agent must belong to an agency associated with the authenticated OAuth client
• Deactivating an owner agent may require reassigning ownership first

POST /v1/agents/:agent_id/reset-access-token

Resets an agent's access token.

Authentication

OAuth Client Access Token

Path Parameters

Response

{
    "data": {
        "agency": {
            "id": 123,
            "name": "Agency Name",
            "color_code": "3A71F8"
        },
        "agent": {
            "id": 456,
            "first_name": "First",
            "last_name": "Last",
            "email": "agent@example.com",
            "slug": "first-last-xyz",
            "access_token": "NEW_ACCESS_TOKEN"
        }
    }
}

Implementation Notes

• The agent must belong to an agency associated with the authenticated OAuth client
• All existing tokens for this agent will be revoked
• The new token should be securely stored as it cannot be retrieved again later

GET /v1/agencies/:agency_id

Retrieves information about an agency.

Authentication

Agent Access Token

Permissions Required

Any agent role

Path Parameters

Response

{
    "data": {
        "id": 123,
        "name": "Agency Name",
        "color_code": "3A71F8",
        "logo_url": "https://example.com/logo.png"
    }
}

Implementation Notes

• The authenticated agent must belong to the requested agency

PATCH /v1/agencies/:agency_id

Updates agency settings.

Authentication

Agent Access Token

Permissions Required

Admin privileges

Path Parameters

Request Body

{
    "color_code": "3A71F8",
    "name": "Updated Agency Name"
}

Response

{
    "data": {
        "id": 123,
        "name": "Updated Agency Name",
        "color_code": "3A71F8",
        "logo_url": "https://example.com/logo.png"
    }
}

Implementation Notes

• The authenticated agent must have admin privileges in the agency
• For uploading a logo, the request must use multipart/form-data
• When using multipart/form-data with a PATCH request, include _method=PATCH in the form data

GET /v1/agencies/:agency_id/agents/:agent_id

Retrieves information about an agent.

PATCH /v1/agencies/:agency_id/agents/:agent_id

Updates agent information.

GET /v1/agents/:agent_id/clients

Retrieves an agent's clients with optional filtering.

GET /v1/agents/:agent_id/clients/:client_uuid

Retrieves detailed information about a specific client.

GET /v1/agents/:agent_id/clients/:client_uuid/submission/:client_submission_uuid/declaration-page/:client_submission_declaration_page_uuid

Generates a download link for a client's declaration page.

POST /v1/agents/:agent_id/clients/:client_uuid/reassign

Transfers a client from one agent to another.

POST /v1/agents/:agent_id/clients/:client_uuid/destroy

Permanently removes a client and all associated data.

DELETE /v1/agencies/:agency_id/agents/:agent_id

Deactivates an agent from the admin/owner account.

PATCH /v1/agents/:agent_id/additional-questions

Enables or disables additional questions for clients.

POST /v1/client

Creates a new client.

POST /v1/webhooks

Creates a new webhook subscription.

GET /v1/webhooks/:webhook_uuid

Retrieves information about a specific webhook subscription.

PATCH /v1/webhooks/:webhook_uuid

Updates an existing webhook subscription.

GET /v1/webhooks

Retrieves all webhook subscriptions for the authenticated agent's agency.

DELETE /v1/webhooks/:webhook_uuid

Removes a webhook subscription.