Agency Management API
The Agency Management API is the system of record for an agency's agents and the data around them: contact details, certifications (licenses and appointments), payee information (pay status, W9, direct deposit), team hierarchy, tags, aliases and the reference data behind them.
| Current version | v2 |
| Base path | /agency-management/{tenantIdentifier} |
| Scopes | read:agents, write:agents, delete:agents |
| Reference | API Portal |
Resources
| Resource | Operations | Guide |
|---|---|---|
| Agents | GET/POST /agents, GET/PATCH/DELETE /agents/{agentCode}, GET /agents/{agentCode}/on-date/{onDate} | Agents |
| Contact | PATCH /agents/{agentCode}/contact | Agents |
| Aliases | GET /aliases, GET/POST /agents/{agentCode}/aliases, GET/DELETE /aliases/{id} | Agents |
| Tags | PATCH /agents/{agentCode}/tags, GET /tags/assigned | Agents |
| Certifications | GET/POST /certifications, GET /certifications/history, GET/PATCH/DELETE /certifications/{id}, POST /certifications/{id}/history | Certifications |
| Teams | /teams/{team}/... (members, assigned uplines, assigned levels, upline and downline members, agent levels) | Teams and hierarchy |
| Payees | PATCH /agents/{agentCode}/payee, GET/POST /payees/assigned-statuses, GET/POST /payees/w9s | Payees |
| Reference data | /certification-types, /jurisdictions, /pay-statuses, /tags, /teams/{team}/agent-levels | Reference data |
| Events | Integration events published when agents change | Events |
Key concepts
Agent code
Every agent has an agent code that is unique within the agency. The code identifies the agent in URLs and in every related resource. You can supply one when you register an agent, or let AgencyMax generate it. See Agent codes.
Effective-dated history
Much of the agent data is effective-dated: it records both the current value and a history of what was true over time. This applies to:
- Certification status
- Pay status
- W9 information
- Assigned direct upline
- Assigned agent level
Each history entry has effectiveFrom and an optional effectiveThrough, both inclusive. When you add a period, AgencyMax adjusts the neighbouring periods so they never overlap. The newest change wins. The rules are the same for every effective-dated resource and are explained with examples under Certifications: how status history is applied.
To see the whole picture as of a particular date, use GET /agents/{agentCode}/on-date/{onDate}.
Initiator
Nearly every write operation requires an initiator for auditing.
Partial updates
PATCH operations follow the partial update rules: an omitted property is left unchanged and an explicit null clears it.