Search
K

Contracting API Overview

AgentSync's Contracting API enables insurance carriers and MGAs to automate the full producer contracting lifecycle — from carrier setup and product configuration to commission assignment and producer onboarding. It provides programmatic access to:

  • Carriers - Create and manage the carriers in your contracting network
  • Products - Configure the products offered under each carrier
  • Commission Levels - Define and assign compensation structures to products
  • Contract Assignments - Manage producer-to-product contracting relationships
  • Producer Invitations - Invite producers into your contracting workflow

What is the Contracting API?

The Contracting API gives your systems direct control over AgentSync's contracting data model. Rather than managing contracting relationships through a UI, you can automate carrier setup, keep commission structures synchronized with your internal systems, and trigger producer onboarding flows programmatically.

The API is organized around a hierarchy: Carriers have Products, Products have Commission Levels, and Contract Assignments link producers to specific products at specific commission levels. This hierarchy maps directly to how contracting works in the insurance industry — a carrier offers products in various lines of business, and producers are contracted to sell those products at negotiated commission rates.

All responses follow the HAL+JSON standard, which means collections are returned with _links and page metadata. When results exist, they are in _embedded; when a collection is empty, _embedded is absent from the response entirely. Note that _links.self on individual resources currently points to an internal /organizations/ path — use the id field to construct resource URLs.

Key Features

Full Contracting Lifecycle Management

  • Create and configure carriers with their NAIC codes and appointment details
  • Define products per carrier with lines of business and submission methods
  • Set up tiered commission levels (Percent, Dollar, or Number) per product
  • Assign producers to products via contract assignments
  • Track assignment changes over time via the contractAssignmentChanges audit trail

Bulk Operations

High-volume scenarios are supported with dedicated bulk endpoints that minimize API calls:

  • Bulk-create commission levels for a product
  • Bulk-update commission levels
  • Bulk-update contract assignments

Producer Invitations

Trigger the producer invitation flow directly from your system. When you POST /v1/invitation, AgentSync sends the producer an invitation to complete their contracting onboarding — no manual steps required.

Lookup Data

Reference endpoints provide the valid values for fields like lines of business, annualizations, assignment statuses, administrative divisions, and contract submission methods. Use these to build compliant payloads and populate dropdowns in your UI.

Use Cases

Insurance Carriers

  • Synchronize your internal product catalog with AgentSync so contract assignments always reflect current offerings
  • Automate producer onboarding by triggering invitations when a new agent appointment is approved
  • Track commission structure changes over time using the contractAssignmentChanges endpoint

Managing General Agents (MGAs)

  • Maintain accurate commission levels across your distribution hierarchy
  • Bulk-update contract assignments when onboarding a new producer cohort
  • Query producer contracting status in real time to power downstream appointment workflows

Technology Partners

  • Integrate contracting data into agency management systems or producer portals
  • Sync carrier and product data bidirectionally between AgentSync and partner platforms
  • Build automated compliance checkpoints using contract assignment status

Entity Relationships

Carrier (name, naic, tin)
  |
  |-- Product (name, lineOfBusinessId, submissionMethodId)
        |
        |-- CommissionLevel (name, type, firstYearValue, level)

Contract (personId + fromOrganizationId + toOrganizationId)
  |-- assignmentStatusId -> AssignmentStatus
  |-- displayNumber
  |
  |-- ContractAssignment (contract + product + commissionLevel)
        |-- assignmentStatusId -> AssignmentStatus
        |-- commissionLevelId -> CommissionLevel
        |-- annualizationId -> Annualization
        |-- uplineContractAssignmentId (self-referencing hierarchy)
        |-- writingNumber, referralCodes[]
        |-- responsiblePartyId (person who manages this assignment)
        |-- 10x userDefined fields
        |
        |-- ContractAssignmentChange (versioned snapshot of a CA change)
              |-- assignmentStatusId (status at time of snapshot)
              |-- newAssignmentStatusId, newCommissionLevelId, newAnnualizationId
              |-- taskTypeId -> TaskType, taskId
              |-- uplineContractAssignmentChangeId (parent change in hierarchy)
              |-- assigneeId (org manager for portal submissions)
              |-- isAgencyInitiated, isSignedByProducer (booleans)
              |-- startDate, endDate
              |-- 10x userDefined fields

Invitation
  |-- personId (producer being invited)
  |-- inviterId (person sending the invite)
  |-- fromOrganizationId (agency initiating the invite)
  |-- toOrganizationIds[] (carrier organization IDs — array)
  |-- loginUrl (Okta activation or SSO URL)
  |-- expirationDate
  |-- isAccepted (boolean)

Getting Started

Start here: The Contracting API Quick Start Guide walks through every step — authentication, carrier setup, product and commission configuration, contract assignment, and producer invitation — with curl and Python examples throughout.

For a full list of endpoints, request/response schemas, and field constraints, see the interactive API Reference.

Support

Need help? Contact us at support@agentsync.io