Agents

Registering an agent

POST /agents (scope write:agents) registers a new agent in one call. It also creates the agent's payee, contact and team membership records.

POST /agency-management/acme/agents
Content-Type: application/json

{
  "firstName": "Dana",
  "lastName": "Lopez",
  "commonName": "Dana",
  "email": "dana.lopez@example.com",
  "governmentIdentifier": "123456789",
  "birthDate": "1988-04-12",
  "npn": "17654321",
  "startDate": "2026-09-01T00:00:00Z",
  "status": "Active",
  "teams": {
    "default": { "directUpline": "A1001", "level": 10 }
  },
  "homeAddress": {
    "line1": "100 Main St",
    "city": "Austin",
    "jurisdiction": "US-TX",
    "postalCode": "78701",
    "country": "US"
  },
  "cellPhone": { "areaCode": "512", "phoneNumber": "5550123" },
  "initiator": "jsmith@acme-agency.com"
}

Request fields

Field	Required	Notes
`firstName`, `lastName`	Yes
`middleName`, `commonName`	No	`commonName` is the preferred or display first name.
`agentCode`	No	Leave it out to have a code generated. See Agent codes.
`status`	Yes	The initial pay status. It must be a configured pay status.
`teams`	Yes	A dictionary keyed by team name (currently `default`). Each entry is `{ directUpline, level }`.
`startDate`	No	An ISO 8601 UTC timestamp. Defaults to now. It can't be in the future or before `1900-01-01`.
`governmentIdentifier`	No	SSN/SIN. Also used to find an existing code in the master agency.
`birthDate`, `gender`, `email`, `npn`, `customerId`, `isDedicated`	No
`homeAddress`, `businessAddress`	No	`{ line1, line2, city, jurisdiction, postalCode, country }`
`cellPhone`, `homePhone`, `businessPhone`, `fax`	No	`{ areaCode, phoneNumber, countryCode }`. `countryCode` defaults to `1`.
`directDeposit`	No	Bank details for US or Canadian accounts.
`w9`	No	`{ name, businessName, taxClassification, exemptPayee, address { streetAddress, city, state, zipCode }, accountNumber, taxpayerIdentifier, signature, signatureDate }`
`initiator`	Yes	See Auditing.

The response contains the full agent, including the assigned agentCode.

warning

Not idempotent

POST /agents creates a new agent every time it's called. If a request times out, look for the agent (for example by governmentIdentifier, npn or email) before you retry.

Agent codes

If you leave out agentCode, AgencyMax generates one from the agency's pool of available codes.

If you supply an agentCode, it must not already be in use in the agency.

Finding agents

GET /agents (scope read:agents) returns a paged list.

Parameter	Description
`agentCodes`	A list of agent codes (up to 100).
`isActive`	Filter by active or inactive pay status.
`email`, `firstName`, `lastName`	Filter by these fields.
`jurisdiction`	Filter by jurisdiction, e.g. `US-TX`.
`governmentIdentifier`, `npn`	Look up by identifier.
`modifiedSince`	Only agents changed at or after this UTC timestamp. Ideal for incremental syncs.
`pageIndex`, `pageSize`, `sort`	See Pagination and sorting. Sort fields: `agentCode`, `firstName`, `lastName`, `commonName`, `startDate`, `lastModified`.

GET /agents/{agentCode} returns a single agent, or 404 if it doesn't exist.

An agent as of a date

GET /agents/{agentCode}/on-date/{onDate} returns the agent as it was on onDate (YYYY-MM-DD). That includes the pay status, W9, and the default team's direct upline and level effective that day. Use it for commission calculations or for questions such as "who was this agent's upline on March 1?"

Updating an agent

Agent data is spread across several PATCH operations, all needing write:agents and an initiator:

Operation	Updates
`PATCH /agents/{agentCode}`	Core agent details: names, email, identifiers, dates and so on.
`PATCH /agents/{agentCode}/contact`	Addresses and phone numbers.
`PATCH /agents/{agentCode}/payee`	Current pay status, W9 and direct deposit. See Payees.
`PATCH /teams/{team}/members/{agentCode}`	Current direct upline and level. See Teams and hierarchy.
`PATCH /agents/{agentCode}/tags`	Assign or unassign tags.

All of them follow the partial update rules.

Deleting an agent

DELETE /agents/{agentCode} needs the separate delete:agents scope. It permanently removes the agent and related data.

An agent who has been paid commissions can't be deleted. The request is rejected so the payment history stays intact. Change the agent's pay status instead, for example to a terminated status.

Aliases

An alias is another identifier for an agent, optionally tied to a provider company, such as the writing number a carrier assigns. Aliases let you match inbound carrier data to agents.

POST /agents/{agentCode}/aliases with { identifier, providerCompany, initiator }
GET /agents/{agentCode}/aliases, GET /aliases, GET /aliases/{id}
DELETE /aliases/{id}

Registering an agent​

Request fields​

Agent codes​

Finding agents​

An agent as of a date​

Updating an agent​

Deleting an agent​

Aliases​

Tags​