Search
K
Contracting & Hierarchies API

Get one of the calling customer's producers by personId or firmId

Returns a single producer owned by the calling customer. A producer that does not exist or
belongs to another customer returns 404 (never 403), so the endpoint does not reveal the
existence of out-of-scope producers.

Beyond the fields on the list item, this response adds:

  • phones — the producer’s phone numbers, in full. Empty when none are on file.
  • bankAccounts — with both the account number and the routingNumber masked to
    ****<last4>. The unmasked values are never returned.
  • federatedUsername — the producer’s federated login, as issued for the calling customer.
    Null for firms, and null where the producer has no federated login with you.
  • middleName — read live from the Identity API here, so it is current even when the
    contracting record’s own copy (served by the list endpoint) has not caught up.

Details this endpoint does not return

This endpoint returns a producer’s contracting record. Personal and demographic details are
owned by the Identity API (https://api.agentsync.io/identity) and retrieved there using
the personId or firmId from this response:

What you need Where to retrieve it
dateOfBirth, gender, preferredFirstName, citizenshipCountry, residentState, finraCrdNumber, ssnLast4 GET /v2/persons/{personId}
Full, unmasked ssn GET /v2/persons/{personId}/ssn
Firm fein GET /v2/firms/{firmId}/fein
Mailing and business addresses GET /v2/persons/{personId}/addresses, GET /v2/firms/{firmId}/addresses
Insurance policies (E&O) GET /v2/persons/{personId}/insurance-policies

The full SSN is deliberately a separate call rather than a field on this response: it is
released only on an explicit request for it, and every access is recorded.

get

Path Parameters

producerIdstring(uuid)required

The producer’s personId (for individuals) or firmId (for firms), as returned by the list endpoint.

Response

application/json

The producer.

ProducerDetailV2

A single producer in the calling customer’s organization. Carries the same fields as the list
item plus phones, federatedUsername, and bankAccounts, and serves a live middleName.
Personal and demographic details such as date of birth, SSN, and addresses are not part of a
contracting record and are retrieved from the Identity API.

typestringrequired

The producer kind.

Allowed values:AGENTFIRM

personIdstring(uuid)

The individual’s id (null for firms).

firmIdstring(uuid)

The firm’s id (null for individuals).

firstNamestring

The individual’s first name (null for firms).

middleNamestring

The individual’s middle name (null for firms), read live from the Identity API so it
is current even when the contracting record’s own copy has not caught up.

lastNamestring

The individual’s last name (null for firms).

suffixstring
firmNamestring

The firm’s name (null for individuals).

npnstring

National Producer Number.

emailstring

The individual’s email (null for firms).

organizationIdstring(uuid)
organizationNamestring
roleNamestring
statusIdstring(uuid)
statusNamestring

The human-readable producer status (inlined). Null for firms, which carry no status.

activeboolean

Whether the producer is active. Always true for firms.

divisionsarray[string]
userDefined1string
userDefined2string
userDefined3string
userDefined4string
userDefined5string
userDefined6string
userDefined7string
userDefined8string
userDefined9string
userDefined10string
createdAtstring(date-time)

RFC3339 UTC creation timestamp.

updatedAtstring(date-time)

RFC3339 UTC last-modified timestamp.

bankAccountsarray[object]

A producer’s bank account. The account and routing numbers are masked to ****<last4>.

Show Child Parameters
phonesarray[object]

A producer’s phone number.

Show Child Parameters
federatedUsernamestring

The producer’s federated login username for the calling customer. Null when the
producer has no federated login, and always null for firms.

 
application/json

Contracts

Read the contracts sent from your organization.

List the calling customer's contracts

Returns the contracts sent from the calling customer’s organization as a token-paginated
collection. Results are scoped to the caller; another customer’s contracts are never returned.

get

Query Parameters

page_tokenstring

Opaque continuation token from a previous response’s page.nextToken. Omit for the first
page.

page_sizeinteger

Maximum number of items to return. Defaults to 25; values outside [1, 250] are rejected
with 400 (not clamped).

Default:25

>= 1<= 250

updated_sincestring(date-time)

Return only contracts modified at or after this RFC3339 UTC timestamp (inclusive). Modified
time tracks any column change, so “modified” does not necessarily mean a
business-meaningful change. Best used as a high-water mark for incremental sync: a pagination
run is not a point-in-time snapshot, so records updated mid-run may first appear on a later poll.

Example:2026-06-01T00:00:00Z

Response

application/json

A page of contracts.

ContractV2Page

A token-paginated page of contracts (plain envelope, no HAL wrappers).

itemsarray[object]required

A contract sent from an agency to a carrier on behalf of a producer.

Show Child Parameters
pageobjectrequired

Pagination metadata for a V2 list response.

Show Child Parameters
 
application/json

Get one of the calling customer's contracts by id

Returns a single contract owned by the calling customer. A contract that does not exist or
belongs to another customer returns 404 (never 403), so the endpoint does not reveal the
existence of out-of-scope contracts.

get

Path Parameters

idstring(uuid)required

The contract id.

Response

application/json

The contract.

ContractV2

A contract sent from an agency to a carrier on behalf of a producer.

idstring(uuid)required

The contract id.

agencyOrganizationIdstring(uuid)required

The agency organization the contract is sent from.

carrierOrganizationIdstring(uuid)required

The carrier organization the contract is sent to.

personIdstring(uuid)required

The individual producer the contract is on behalf of.

firmIdstring(uuid)

The firm the contract is on behalf of, if any.

responsibleUplineFirmIdstring(uuid)

The upline firm responsible for the contract, if any.

assignmentStatusIdstring(uuid)

The contract’s assignment status id.

assignmentStatusNamestring

The human-readable assignment status (inlined so no follow-up lookup is needed).

activebooleanrequired

Whether the contract is currently active based on its assignments.

effectiveDatestring(date)

The effective date of the contract (yyyy-MM-dd).

endDatestring(date)

The end date of the contract (yyyy-MM-dd).

displayNumberstringrequired

The human-readable contract number.

parentContractIdstring(uuid)

The parent contract id, if this is a subsidiary contract.

contractResponsiblePartiesarray[object]required

One responsible-party window on a contract. Both bounds are inclusive. Windows do not overlap, with
two exceptions: two windows may meet on a single shared day (one window’s endDate equal to the
next window’s startDate), and a window whose startDate equals its endDate is a retired record
rather than a live one-day assignment. To resolve who is responsible on a given day, ignore windows
where startDate equals endDate, and on a shared boundary day prefer the window that starts that
day over the one that ends it. The current window is the one with no endDate; there is at most one
per contract.

Show Child Parameters
createdAtstring(date-time)

RFC3339 UTC creation timestamp.

updatedAtstring(date-time)

RFC3339 UTC last-modified timestamp.

userDefined1string
userDefined2string
userDefined3string
userDefined4string
userDefined5string
userDefined6string
userDefined7string
userDefined8string
userDefined9string
userDefined10string
 
application/json

Contract Assignments

Read contract assignments: a producer’s placement against a carrier’s product.