Search
K
Contracting & Hierarchies API

AgentSync Contracting & Hierarchies API

v1.7.6OAS 3.1

The customer-facing surface for the AgentSync Contracting platform: a purpose-built,
read-only API for producers, contracts, contract assignments, and the hierarchies those
assignments form. Every endpoint below is under the /v2 path prefix.

Every endpoint requires an OAuth2 client-credentials token and the scope shown on that
endpoint. See Authentication for how to
request credentials and retrieve a token,
API Base URLs for the sandbox and production
hosts, and Pagination for how page_token
and page_size behave across list endpoints.

Contracting and hierarchy endpoints are documented together because they share one set of
scopes: a token carrying contracting.contractassignments.read reaches both. They are also
entangled by design — a hierarchy node’s key is a contractAssignmentId. Use the sidebar
groups to navigate: hierarchy and upline-discovery endpoints are under Hierarchies.

Webhook events

AgentSync delivers outbound events to your configured endpoint when contracts, contract
assignments, and hierarchy placements change. Each event is an HTTP POST whose body carries a
unique id, a dot-notation type, and a type-specific data payload; respond 2xx to
acknowledge. The event types are declared under webhooks below.

Full payload documentation — every field of every event, delivery semantics, retry behaviour
and signature verification — lives at
Contracting API Webhooks.

API Base URL
  • Server 1:https://api.sandbox.agentsync.io/contracting

    Sandbox

  • Server 2:https://api.agentsync.io/contracting

    Production

Security
oauth2 (oauth2)

OAuth2 client credentials. The tokenUrl below is the SANDBOX token endpoint; for production use https://auth.agentsync.io/oauth2/token. OpenAPI 3.1 permits only one token URL per flow, so both cannot be expressed here - see https://developer.agentsync.io/api-authentication for the full environment table, how to request credentials, and worked token-retrieval examples.

Producers

Read the producers - individuals and firms - in your organization.

List the calling customer's producers

Returns the producers (individuals and firms) in the calling customer’s organization as a
token-paginated collection. Results are scoped to the caller; another customer’s producers are
never returned.

This collection carries each producer’s contracting record only. Phone numbers, the federated
username, and bank accounts are returned by
the by-id endpoint, not here, because each one requires a
per-producer lookup that cannot be performed economically across a full page.

middleName is served here from the contracting record’s own copy, which can lag the
Identity API. The by-id endpoint reads it live and is the accurate source.

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 producers.

ProducerV2Page

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

itemsarray[object]required

A producer in the calling customer’s organization. A producer is either an individual
(type = AGENT, identified by personId) or a firm (type = FIRM, identified by
firmId); fields that do not apply to the other kind are null.

Show Child Parameters
pageobjectrequired

Pagination metadata for a V2 list response.

Show Child Parameters
 
application/json

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.