ComTrack

API reference

Licensing API

Retrieve licenses and appointments, manage oversight, quote and submit non-resident applications.

7 min readUpdated

GEThttps://commissionconnector.com/api/licensing

How to Use the ComTrack Licensing API

The ComTrack Licensing API lets you access and manage licensing functionality outside of ComTrack.

With the API, you can:

  • Retrieve Agent licenses and carrier appointments
  • Add Agents to Licensing
  • Refresh licensing information from NIPR
  • Monitor or manage Agents
  • View state licensing fees
  • Identify states where an Agent is eligible for a non-resident license
  • Get licensing quotes
  • Submit non-resident license applications
  • Enable automatic license renewals
  • Check the status of NIPR filings
  • Manage carrier display-name rules
  • Perform licensing actions on behalf of an Agent

Find Your API Key

Your Licensing API key is already available in ComTrack.

Go to:

Integrations → API Keys

Your API key will look similar to:

cc_live_...

Each API key is associated with a specific ComTrack case. You do not need to include a Case ID in your API requests because ComTrack identifies the case from the API key automatically.

If you work with multiple cases, use the API key associated with the case you want to access.

Authenticate Your Requests

Send your API key with every request using the following header:

x-api-key: YOUR_API_KEY

The base URL for the Licensing API is:

https://commissionconnector.com/api/licensing

Requests containing a body should use JSON:

Content-Type: application/json

Keep your API key secure

Your Licensing API key can perform sensitive actions, including charging the organization's card and submitting license applications to NIPR.

Treat your API key like a password.

If a key is compromised, regenerate it inside ComTrack. The previous key will immediately stop working.

Retrieve Licensing Data

To retrieve licenses and carrier appointments:

GET /api/licensing

Example:

curl 'https://commissionconnector.com/api/licensing' \
  -H 'x-api-key: YOUR_API_KEY'

By default, ComTrack returns the first 50 records.

Each record represents a license + carrier appointment combination.

For example, if an Agent has one Texas license and appointments with three carriers, the API will return three rows.

Filtering Results

You can filter licensing data by:

Filter Example
Agent ?agent=Aaron%20Smith
NPN ?npn=22138232
State ?state=TX
Status ?status=expiring

Available status values are:

  • active
  • expiring
  • expiring_soon
  • expired

Example:

GET /api/licensing?state=TX&status=expiring&limit=100

Pagination

Use page and limit to paginate results.

GET /api/licensing?page=2&limit=200

The maximum page size is 200 records.

Continue requesting additional pages until you have retrieved the number of records shown in total.

Manage Agents

List Agents

GET /api/licensing/agents

This returns Agents participating in Licensing, including information such as:

  • Agent name
  • NPN
  • Oversight level
  • Number of licenses
  • Whether the Agent self-manages licensing
  • Last NIPR sync

Add an Agent

POST /api/licensing/agents

Example body:

{
  "agent_name": "Aaron Smith"
}

New Agents are added with an oversight level of none.

Refresh an Agent From NIPR

POST /api/licensing/agents/refresh

Example:

{
  "agent_name": "Aaron Smith"
}

This tells ComTrack to re-check the Agent's licensing information with NIPR.

The Agent must already be under Licensing oversight and have an NPN.

There is no charge for refreshing an Agent.

Set Licensing Oversight

ComTrack supports three oversight levels:

  • none
  • monitor
  • manage

To change an Agent's oversight:

POST /api/licensing/oversight

Example:

{
  "agent_name": "Aaron Smith",
  "npn": "22138232",
  "mode": "manage"
}

Pricing

Turning an Agent on for either Monitor or Manage costs $1 per month per Agent.

The first month is charged immediately. The subscription renews monthly on the same day.

Switching between Monitor and Manage does not create an additional charge.

Changing the Agent to none stops future monthly charges.

Use an Idempotency Key for Charging Actions

Any API call that can create a charge should include an Idempotency-Key.

Example:

Idempotency-Key: 8c1f4e54-0dd5-4db3-b591-123456789abc

Generate a new key for each new action.

If you need to retry the same action because of a timeout or network problem, reuse the same Idempotency-Key.

This prevents the same action from being charged or submitted twice.

Successful requests using the same key can be safely replayed for up to 24 hours.

Get Eligible Non-Resident States

To see which states an Agent may be eligible to obtain a non-resident license in:

GET /api/licensing/agents/{npn}/eligible-states

Example:

GET /api/licensing/agents/22138232/eligible-states

Example response:

{
  "states": ["AL", "AZ", "TX"]
}

Get State Licensing Questions

Some states require additional questions during licensing or renewal.

Retrieve them using:

GET /api/licensing/renewal-questions?state=TX

These questions should be answered in the non_uniform portion of the application when submitting the filing.

Get a Non-Resident License Quote

Before submitting a non-resident license application, request a quote.

POST /api/licensing/nonresident/quote

Example:

{
  "npn": "22138232",
  "state": "TX",
  "class": "Insurance Producer",
  "loa_codes": ["11", "12"]
}

Requesting a quote does not charge the customer or submit anything to NIPR.

The response includes the expected:

  • State fee
  • NIPR fee
  • ComTrack fee
  • Card processing fee
  • Total
  • State-specific application questions

We recommend quoting an application before submitting it.

Submit a Non-Resident License Application

To submit the application:

POST /api/licensing/nonresident/submit

Because this action creates a charge and submits an application to NIPR, include an Idempotency-Key.

Example:

{
  "npn": "22138232",
  "state": "TX",
  "class": "Insurance Producer",
  "loa_codes": ["11", "12"],
  "ssn": "123456789",
  "first_name": "Aaron",
  "middle_name": "",
  "last_name": "Smith",
  "dob": "19800201",
  "gender": "...",
  "us_citizen": "...",
  "country_code": "1",
  "email_individual": "...",
  "email_business": "...",
  "phone_residence": "...",
  "phone_business": "...",
  "addresses": [],
  "employment": [],
  "background": [],
  "non_uniform": [],
  "attestation": true
}

At minimum, the application requires:

  • NPN
  • State
  • SSN
  • attestation: true

NIPR validates the remaining application information.

Important

Submitting a non-resident application charges the organization's card and sends the application to NIPR.

Once NIPR accepts a filing, it cannot be undone.

The filing cost consists of:

State fee + $5.60 NIPR fee + $5.00 ComTrack fee + 3% card fee

Use the Quote endpoint first to determine the expected total.

Check the Status of a Filing

NIPR filings are asynchronous, which means a filing may initially return as pending.

To check its status:

GET /api/licensing/agents/{npn}/transactions

Example:

GET /api/licensing/agents/22138232/transactions

The response includes the Agent's 50 most recent filings.

Important fields include:

  • outcome
  • status
  • messages
  • action_required
  • stale_pending
  • charge_status
  • submitted_at
  • final_at

If action_required is true, NIPR requires additional action from the Agent.

There are currently no filing webhooks, so integrations should periodically poll this endpoint until the filing receives a final result.

Enable Automatic Renewals

Automatic renewal can be enabled for an individual license using:

POST /api/licensing/licenses/{id}/auto-renew

Example:

{
  "auto_renew": true,
  "profile": {
    "...": "..."
  }
}

The {id} comes from the id field returned by:

GET /api/licensing

The Agent must be under Manage oversight.

The first time auto-renew is enabled, ComTrack may require a renewal profile containing the information needed to submit the future NIPR renewal.

There is no immediate charge for turning on auto-renew.

When the renewal is eventually filed, the organization is charged the applicable filing fees.

Retrieve the State Map

To retrieve license counts by state:

GET /api/licensing/map

Example response:

{
  "AR": 3,
  "TX": 12
}

Retrieve State Fees

To access the state fee information used by ComTrack:

GET /api/licensing/state-fees

Act as an Agent

Organization owners can also use the API to perform licensing actions as an Agent, similar to using Login As inside ComTrack.

The URL format is:

/api/licensing/as-agent/{agent_id}/...

The agent_id is the Agent's ComTrack User ID.

Examples include:

GET /api/licensing/as-agent/{agent_id}/me
GET /api/licensing/as-agent/{agent_id}/eligible-states
POST /api/licensing/as-agent/{agent_id}/nonresident/quote
POST /api/licensing/as-agent/{agent_id}/nonresident/submit

Important difference

Actions performed through as-agent run as the Agent.

Any applicable charges are therefore made to the Agent's own card, rather than the organization's card.

For example, an Agent can enable self-managed licensing:

POST /api/licensing/as-agent/{agent_id}/self-manage
{
  "npn": "22138232"
}

Self-managed licensing costs the Agent $3 per month, with the first month charged immediately.

Common API Errors

Code Meaning
200 / 201 Request succeeded
400 Missing or invalid request information
401 API key is missing or invalid
402 Payment method is missing or the card was declined
403 Access is not permitted
404 Agent, license, or other requested resource was not found
409 The request conflicts with an existing state or business rule
500 Internal ComTrack error
502 / 503 NIPR rejected the request or is temporarily unavailable

Errors generally include a message explaining what caused the request to fail.

For payment errors, you may also receive:

payment_method_required

or:

payment_declined

Update the applicable payment method in ComTrack and retry the request.

Important Things to Know

Before building an integration with the Licensing API:

  • One API key represents one ComTrack case.
  • Your API key is already available under Integrations → API Keys.
  • API keys can perform billing-sensitive actions, so store them securely.
  • Use an Idempotency-Key when performing any charging or filing action.
  • Non-resident license filings cannot be reversed once NIPR accepts them.
  • Filing results are asynchronous. Poll the Agent's Transactions endpoint for the final result.
  • The maximum Licensing API page size is 200 rows.
  • Agent and NPN filters require exact matches.
  • License statuses such as expiring and expired are calculated dynamically from the license expiration date.
  • Licensing requests and responses can contain sensitive personal information, including names, dates of birth, NPNs, license numbers and SSNs.
  • ComTrack does not return an Agent's SSN through the API.

API Access Requirements

Licensing API access requires the organization's ComTrack case to be on a plan that includes API access.

API requests must be made through:

commissionconnector.com

If you receive a 403, verify that:

  1. The organization has API access.
  2. The request is being sent through commissionconnector.com.
  3. When using as-agent, the Agent belongs to your organization and the API key belongs to the organization's main case.

Was this article helpful?