canonical: https://jentic.com/apis/nextagency.com/nextagency

# NextAgency API

NextAgency is an insurance-agency management platform whose v2 REST API exposes 55 endpoints for managing the data inside an agency book of business. The API covers cases (the platform's term for businesses), addresses, agency benefits, tasks, notes, contacts, sub-agents, carriers, employees, users, and VOIP recordings, with dedicated search endpoints on every major resource. Authentication is OAuth 2.0 - the `/oauth/authorize` and `/oauth/token` endpoints handle the authorization-code grant and the rest of the API uses the resulting access token as a bearer credential.

## For AI agents

Manage insurance-agency cases, contacts, tasks, notes, sub-agents, carriers, and benefits in NextAgency, with OAuth 2.0 authorization-code login and full search on every major resource.

## Scope

Does not handle policy quoting, premium calculation, or carrier rating - use for managing the NextAgency book of business records (cases, contacts, tasks, notes, benefits, carriers, sub-agents) only.

## Capabilities

- Provision an OAuth 2.0 access token through `/oauth/authorize` and `/oauth/token` for downstream API calls
- Create, update, and search cases (the platform's term for businesses) along with their associated addresses
- Track tasks against a case with create, update, and search endpoints scoped under `/api/v2/businesses/{business_id}/tasks`
- Store and search notes attached to a case for activity logging and customer-conversation recall
- Maintain agency benefit records on a case to capture the products and policies the agency placed
- Manage the carrier catalog, sub-agent roster, and contact directory shared across the agency
- Search contacts by phone number to identify a caller before answering or returning a call

## Use cases

### Caller Identification on Inbound Phone Calls

When a phone rings into the agency, hit GET `/api/v2/contacts/search_by_phone_number` with the caller ID to find the matching contact and the case they belong to. The agent can then surface the contact name, last note, and open tasks before the call is answered. Combine with GET `/api/v2/businesses/{business_id}/notes` to pull recent activity into the answering screen.

Example prompt: Call GET `/api/v2/contacts/search_by_phone_number` with phone_number=+15551234567 to identify the caller, then GET `/api/v2/businesses/{business_id}/notes` for the last 5 notes on their case

### New-Business Case Creation

When a prospect submits a quote request, create the case in NextAgency, attach an address, and seed the initial task list. POST `/api/v2/businesses` creates the case (the API name for a business), POST `/api/v2/businesses/{business_id}/tasks` adds the follow-up tasks, and POST `/api/v2/businesses/{business_id}/notes` captures the intake summary. The case becomes the central record for benefits, carriers, and sub-agent assignment.

Example prompt: POST `/api/v2/businesses` with the prospect's name and primary contact, then POST `/api/v2/businesses/{business_id}/tasks` with a follow-up task due in 48 hours

### Renewal Task and Benefit Tracking

Drive policy renewal workflows by listing tasks and benefits per case. GET `/api/v2/businesses/{business_id}/tasks` lists open work, PATCH on a specific task moves it through statuses, and GET `/api/v2/businesses/{business_id}/agency_benefits` surfaces the products in force. Search `/api/v2/businesses/{business_id}/tasks/search` filters tasks by due date or owner so renewal sweeps can be batched per producer.

Example prompt: GET `/api/v2/businesses/{business_id}/tasks/search` with a status filter for open tasks due this week, then PATCH each task to mark it complete after the renewal call

### AI Agent Agency Operations

Through Jentic, an AI agent reads and writes NextAgency records without holding the OAuth client secret. The agent searches Jentic with the intent 'create a NextAgency case', loads the POST `/api/v2/businesses` schema, and executes with structured arguments. Subsequent calls to tasks, notes, and contacts endpoints reuse the same OAuth flow, with the access token handled by Jentic's Jentic One instance.

Example prompt: Use Jentic search query 'create a NextAgency case' to load POST `/api/v2/businesses`, execute with the prospect's details, then chain task and note creation calls under the new business_id

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/oauth/token` | Exchange an authorization code for an access token |
| GET | `/api/v2/businesses` | List cases (businesses) |
| POST | `/api/v2/businesses` | Create a case |
| GET | `/api/v2/businesses/search` | Search cases |
| POST | `/api/v2/businesses/{business_id}/tasks` | Create a task on a case |
| POST | `/api/v2/businesses/{business_id}/notes` | Create a note on a case |
| GET | `/api/v2/contacts/search_by_phone_number` | Search contacts by phone number |
| GET | `/api/v2/carriers/search` | Search the carrier catalog |

## Key resources

- **Cases (Businesses)** — Create, list, search, and update the businesses that anchor every record in NextAgency
- **Tasks** — Track and search follow-up work scoped to a specific case
- **Notes** — Log and search notes attached to a case for activity history
- **Contacts** — Manage the agency contact directory with search by name and phone number
- **Carriers** — Maintain the catalog of insurance carriers the agency works with
- **Sub-Agents** — Manage the producers who can be assigned to cases and benefits
- **Agency Benefits** — Capture the policies and products placed against a case
- **Addresses** — List and update postal addresses linked to cases and contacts

## Why Jentic

- **Setup:** Wiring the NextAgency API by hand means running the OAuth token exchange, refreshing the short-lived access token, and adding it as a bearer header across dozens of book-of-business endpoints. Through Jentic you install once, import the NextAgency API from the API Directory, store the OAuth credentials once, and your agent calls it.
- **Permission scoping:** The NextAgency API puts the business id in the URL path (`/api/v2/businesses/{business_id}/...`), so a rule can pin your agent to one business record: it can add tasks and notes to that business and nothing else. You choose the operations it may call, so creating businesses or contacts is not included unless you add them.
- **Credential handling:** Your NextAgency OAuth client id, client secret, and refresh token are stored once, encrypted, by your own Jentic One instance, which exchanges them for a short-lived access token at execution time. The secret and refresh token never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a NextAgency case' or 'search NextAgency contact by phone' and Jentic returns the matching `/api/v2` operation with its input schema so the agent populates the request without browsing the reference docs.

## Related APIs

- **HubSpot CRM Companies** — General-purpose CRM company records that map to NextAgency's case (business) concept.
- **Salesforce REST API** — Salesforce account and contact records as a generic CRM substitute for the NextAgency case/contact model.
- **Pipedrive API** — Sales-pipeline CRM with deals and contacts as a competitor to NextAgency's case management.

## FAQ

### What authentication does the NextAgency API use?

NextAgency uses OAuth 2.0 with the authorization-code grant. `/oauth/authorize` starts the consent flow and POST `/oauth/token` exchanges the returned code for an access token, which is then sent as Authorization: Bearer on the `/api/v2` endpoints. Jentic stores the OAuth client and refresh token in your Jentic One instance and refreshes the access token automatically.

### How do I create a new case in NextAgency?

POST `/api/v2/businesses` with a JSON body containing the business name and any required contact data. The response returns the business_id, which is then used as the path segment on every nested resource - tasks, notes, agency_benefits - under `/api/v2/businesses/{business_id}.`

### Can I look up a NextAgency contact by their phone number?

Yes. GET `/api/v2/contacts/search_by_phone_number` accepts a phone_number query parameter and returns matching contacts with their associated business_id. Use this for inbound-call screen pops or outbound dialing reconciliation.

### How do I search tasks across an agency's cases?

Tasks are scoped per case in the API. Use GET `/api/v2/businesses/{business_id}/tasks/search` with status, due_date, or owner filters to narrow down within a specific case. To sweep across cases, iterate the businesses list from GET `/api/v2/businesses` and call the per-case task search for each one.

### What resources are available beyond cases, tasks, and contacts?

The API also exposes addresses, agency_benefits, sub_agents, carriers, employees, users, and VOIP recordings, each with list, get, update, and (where applicable) search endpoints under `/api/v2.` This covers the operational data an insurance agency needs alongside the core case record.

### How do I integrate NextAgency through Jentic?

Run pip install jentic, then use the Jentic search query 'create a NextAgency case' to load POST `/api/v2/businesses.` Jentic handles the OAuth token exchange and refresh from your Jentic One instance, so the agent only deals with the business arguments. Run it through Jentic One, the self-hosted execution layer.

### Can I limit what my agent is allowed to do with the NextAgency API?

Yes. Because you run Jentic One yourself, your own rules decide which NextAgency operations and credentials the agent may use. Since the API puts the business id in the URL path (`/api/v2/businesses/{business_id}/...`), you can pin the agent to a single case so it can add tasks and notes to that business and nothing else. You choose the operations it may call, so higher-impact actions like creating businesses or contacts, or searching contacts by phone, are excluded unless you explicitly allow them.