---
title: "Contracting API: Best Practices"
description: "The Contracting API v2 surface is read-only — /v2/producers, /v2/contracts, /v2/contract-assignments, /v2/contract-assignment-changes, /v2/assigned-*, and the hierarchy endpoint. These notes cover getting a read integration right."
url: "https://developer.agentsync.io/contracting-api-best-practices"
image: "https://developer.agentsync.io/_og/d/c_Ocean.takumi,title_~Q29udHJhY3RpbmcgQVBJOiBCZXN0IFByYWN0aWNlcw,description_~VGhlIENvbnRyYWN0aW5nIEFQSSB2MiBzdXJmYWNlIGlzIHJlYWQtb25seSDigJQgL3YyL3Byb2R1Y2VycywgL3YyL2NvbnRyYWN0cywgL3YyL2NvbnRyYWN0LWFzc2lnbm1lbnRzLCAvdjIvY29udHJhY3QtYXNzaWdubWVudC1jaGFuZ2VzLCAvdjIvYXNzaWduZWQtKiwgYW5kIHRoZSBoaWVyYXJjaHkgZW5kcG9pbnQuIFRoZXNlIG5vdGVzIGNvdmVyIGdldHRpbmcgYSByZWFkIGludGVncmF0aW9uIHJpZ2h0Lg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMxODdFRkYifX19,p_Ii9jb250cmFjdGluZy1hcGktYmVzdC1wcmFjdGljZXMi,s_zHJeD9eQBkt--dhu.png"
---

# Contracting API: Best Practices

The Contracting API v2 surface is read-only — `/v2/producers`, `/v2/contracts`, `/v2/contract-assignments`, `/v2/contract-assignment-changes`, `/v2/assigned-*`, and the hierarchy endpoint. These notes cover getting a read integration right.

## [Sync with `updated_since`, Don't Requery Everything](#sync-with-updated_since-dont-requery-everything)

Instead of re-fetching all records on a schedule, use `updated_since` to get only what changed:

```bash
GET /contracting/v2/contract-assignments?updated_since=2026-06-01T00:00:00Z
```

-   `updated_since` is an RFC3339 UTC timestamp, inclusive, available on `/v2/producers`, `/v2/contracts`, `/v2/contract-assignments`, `/v2/contract-assignment-changes`, `/v2/assigned-carriers`, `/v2/assigned-products`, and `/v2/assigned-commission-levels`.
-   Store the time you started each sync run and use it as the next run's `updated_since` — a high-water mark.
-   Modified time tracks any column change, so a returned record is not necessarily a business-meaningful change; diff against your stored state.
-   A pagination run is not a point-in-time snapshot: records updated mid-run may first appear on a later poll. Overlap your windows slightly rather than assuming exactly-once delivery.

## [Paginate All List Responses](#paginate-all-list-responses)

Always paginate — don't assume a single response contains all records. See [Pagination](https://developer.agentsync.io/api-pagination) for the response envelope, query parameters, and a reusable Python paginator.

Two things to get right:

-   The query parameter is `page_token`, but the response field is `page.nextToken`. An unrecognized parameter name is ignored rather than rejected, so a misspelling silently returns the first page forever.
-   `page_size` must be `1–250`. Out-of-range values are rejected with a `400` rather than clamped, on Contracting and Identity alike.

## [Identify Uplines by ID, Not by Name](#identify-uplines-by-id-not-by-name)

The v2 surface has no upline _name_ field. A hierarchy node inlines `producerName` for the producer at that position and links upward with `uplineContractAssignmentId` — to name a node's upline, resolve that ID against the node it points to.

> If you are migrating from v1, the `uplineName` / `uplineFirmName` / `uplinePersonName` fields you may have used there do not exist in v2. Key on `uplineContractAssignmentId` instead; it is stable across amendments and matches the `contractAssignmentId` in `hierarchy.producer.*` webhook events.

## [Let the Inlined Names Save You a Round Trip](#let-the-inlined-names-save-you-a-round-trip)

v2 responses inline reference names next to their IDs — `productName` beside `productId`, `commissionLevelName` beside `commissionLevelId`, `assignmentStatusName` beside `assignmentStatusId`. You do not need a second call, or a cached lookup table, to render a row.

## [Reliability](#reliability)

-   **Implement exponential backoff** for `429 Too Many Requests` and `5xx` errors. See [Rate Limits](https://developer.agentsync.io/api-rate-limits).
-   **Reuse your access token** — it is valid for 60 minutes, and fetching a new one per request is the most common way integrations hit the token endpoint limit.
-   **Capture the `DD-Trace-ID` response header on failures** and include it in support tickets. See [Traceability](https://developer.agentsync.io/api-traceability).

## [Performance](#performance)

-   Rate limits are counted per credential, so parallel workers sharing a `client_id` share one budget rather than each getting their own.
-   Filter server-side with `updated_since` rather than fetching everything and filtering locally.
-   Prefer paged bulk reads over per-record polling.

## [Integration Patterns](#integration-patterns)

### [Initial Data Load](#initial-data-load)

When setting up a new integration:

1.  Read your account configuration — `GET /v2/assigned-carriers`, `/v2/assigned-products`, `/v2/assigned-commission-levels`
2.  Page through `GET /v2/producers` for your producer population
3.  Page through `GET /v2/contract-assignments` for their placements
4.  Fetch the hierarchy with `GET /v2/organizations/{organizationId}/hierarchies`, fetching every page before reconstructing the tree — a child can appear on a later page than its parent
5.  Record the start time of the run as your first high-water mark

### [Ongoing Sync](#ongoing-sync)

For keeping a downstream system in sync:

1.  Poll `GET /v2/contract-assignments` with `updated_since` set to your last sync timestamp — each row already carries the full current state with names inlined
2.  Update your local records and advance your stored sync timestamp
3.  Subscribe to [webhook events](https://developer.agentsync.io/contracting-api-webhooks) for near-real-time updates, and keep the `updated_since` poll as a reconciliation safety net

### [Resolving Producer Contact Details](#resolving-producer-contact-details)

Contracting holds placement; addresses, phones, bank accounts, and E&O policies live in the Identity API. A producer's `personId` and `firmId` are Identity identifiers and resolve directly, with no mapping step — see [Joining with the Contracting API](https://developer.agentsync.io/identity-api-overview#joining-with-the-contracting-api).