PaynaAPI v1 · 1.8.0

Payna API

Read your company's licensing records, onboard loan officers, and hear when NMLS changes them.

Payna keeps your company's licensing records: every license your company holds, every person it licenses, each of their licenses and your sponsorship of it, their education, and what regulators still want. The API gives your systems the same records your team sees in Payna.

Every request goes to one base URL and carries your API key.

curl https://app.payna.com/api/v1/licenses/summary \
  -H "Authorization: Bearer $PAYNA_API_KEY"
{
  "data": {
    "total": 37,
    "by_status": {
      "active": 13,
      "deficient": 2,
      "pending": 3,
      "applying": 13,
      "not_licensed": 6
    },
    "renewing_soon": 3
  }
}

Where to start

ToCall
List your loan officers, their licenses and sponsorshipsGET /loan-officers
Onboard an officer you hiredPOST /loan-officers
Hear when an officer's record changesPOST /webhooks
See your company's own licensesGET /licenses
Check someone who does not work for youPOST /nmls/verifications

How fresh the data is

Payna updates your records on your company's schedule, once a business day unless you asked for more, and course progress every night. Each record says when it was last updated: last_synced_at on a license, last_synced on an officer, and meta.synced_at on a list, which is the oldest update in the response.

Lists and limits

Lists answer { "data": [...], "meta": { "total", "page", "limit", "synced_at" } }. Pass page and limit to read the next page, until you have meta.total rows. Each key can make 300 requests in any 15 minutes. Over that, Payna answers 429 with a Retry-After header giving the seconds to wait.

Authentication

One API key per integration, sent as a bearer token.

Payna issues API keys. Write to support@payna.com with what the integration does, and Payna sends a key that starts with pk_live_. Send it on every request:

curl https://app.payna.com/api/v1/loan-officers -H "Authorization: Bearer pk_live_..."

A key reads and writes only your company's records. Keep it on your server. A key in a browser or a mobile app can be copied by anyone who uses it.

Capabilities

A key can do only what its capabilities allow. Ask for the ones your integration needs. An endpoint the key cannot use answers 403 and names the missing capability.

CapabilityAllows
licensesYour company's own licenses (/licenses).
individualsLoan officers, individuals, renewals and exports. Also needed to register a webhook.
nmls_verificationCheck the NMLS license record of any broker or loan officer.
nipr_verificationRead the NIPR verifications Payna performed for your agency.
educationSign an officer up at your course provider.
onboardingSend a new loan officer to onboard (POST /loan-officers).
webhooksRegister endpoints for webhook events.

Revoking a key

Write to support@payna.com and Payna revokes it. A revoked key answers 401 at once, and the webhooks it registered stop.

Errors

Every error has the same shape, and the message says what to change.

{
  "error": {
    "code": "INVALID_PARAM",
    "message": "work_phone is required.",
    "status": 400,
    "fields": [
      {
        "field": "work_phone",
        "message": "work_phone is required."
      },
      {
        "field": "start_date",
        "message": "start_date must be a date, like 2026-12-01."
      }
    ]
  }
}

code is stable, so branch on it. message is written for a person and may change. On a 400, fields lists every field that is wrong, so one round trip finds all of them.

StatusCodeMeansRetry
400INVALID_PARAM, INVALID_STATE_CODE, INVALID_STATUS_VALUEA parameter or field is wrong.After fixing it
401UNAUTHORIZED, REVOKEDThe key is missing, malformed or revoked.No
403FORBIDDENThe key lacks a capability, or API access is off for your company.No
404NOT_FOUND, INDIVIDUAL_NOT_FOUND, LICENSE_NOT_FOUNDNothing at your company matches.No
409CONFLICTThe request disagrees with a record Payna holds. The message says which.After resolving it
429RATE_LIMITEDOver the rate limit.After Retry-After seconds
500, 503INTERNAL_ERRORSomething went wrong at Payna.Yes, with backoff

POST /loan-officers and POST /webhooks are safe to retry after a timeout or a 5xx. The first finds the officer it already made. The second answers 409 for a URL the key already registered.

Onboarding a loan officer

Send a hire once. Payna takes it to NMLS and tells you as it moves.

When your company hires a loan officer, send them to POST /loan-officers with what NMLS asks for. Payna adds them to your team and runs their onboarding:

  1. Payna requests access to their NMLS record. The officer accepts in NMLS.
  2. Payna files the relationship with your company, effective on their start date.
  3. Payna requests their first sponsorship, in the states you name or the states your company sponsors every officer in.
  4. Each state approves. can_originate_in lists the states they can originate in for you.

Your company approves steps 2 and 3 the way it already approves filings in Payna. Step 1 starts as soon as the hire arrives when your company has that turned on. Ask Payna to turn it on.

The fields

FieldNMLS asks forRequired
nmls_idThe officer's individual NMLS IDYes
first_name, last_nameTheir nameYes
work_emailWork email on the relationshipYes
work_phoneWork phone on the relationshipYes
titlePosition titleYes
start_dateRelationship effective dateYes
worker_classificationW-2 or 1099Yes
work_arrangementWhether they work remotelyYes
branch_codeThe location they are associated withYes
works_from_homeWhether the remote location is their residenceWhen hybrid or remote
work_addressThe remote location, when it is not their residenceWhen not from home
employee_idNothing at NMLS. Payna matches your systems on itRecommended
start_date_confirmedPayna files only a confirmed dateNo
sponsor_statesWhich states their first sponsorship coversNo

branch_code is your own code for the office, as your company uses it in Payna, or the branch's NMLS ID. The main office counts.

Sending a hire

curl -X POST https://app.payna.com/api/v1/loan-officers \
  -H "Authorization: Bearer $PAYNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "E10442",
    "nmls_id": "1234567",
    "first_name": "Jane",
    "last_name": "Example",
    "work_email": "jane.example@examplemortgage.com",
    "work_phone": "949-555-0142",
    "title": "Loan Officer",
    "start_date": "2026-12-01",
    "start_date_confirmed": true,
    "worker_classification": "W2",
    "work_arrangement": "hybrid",
    "branch_code": "101",
    "works_from_home": true
  }'

A new officer answers 201. The body is the officer as GET /loan-officers/{id} returns them, and Location names them.

Sending the same person again

Payna matches on employee_id, then on nmls_id. Sending someone Payna already has answers 200, so a retry never makes a second officer. For a hire your systems sent, the answers follow the new request, so a changed start date can be sent again, and Payna keeps any answer a person on your team changed in Payna. For an officer already in Payna before your systems sent them, the request keeps their answers and only records their employee_id. An employee_id that belongs to an officer with a different NMLS ID answers 409.

Following along

Sponsorship is for the first one only. sponsor_states sets the states a new hire's first sponsorship covers, filed on their start date. Sponsoring more states later is not available through the API yet: ask Payna. Until that first sponsorship is filed, a new request can change its states. After that, sending a state it does not cover answers 409, and so does sponsor_states for an officer Payna already knew.

onboarding.status says where they are (awaiting_access, sponsoring, sponsored) and onboarding.waiting_on says who acts next. Register a webhook to hear each change instead of polling.

Webhooks

Payna posts to your endpoint when a loan officer is added or their record changes.

Register an https endpoint once:

curl -X POST https://app.payna.com/api/v1/webhooks \
  -H "Authorization: Bearer $PAYNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.examplemortgage.com/payna" }'

The response carries secret once. Store it: every event is signed with it. Then call POST /webhooks/{id}/test to send a signed test event and see what your endpoint answered.

Events

TypeSent when
loan_officer.createdAn officer joins your roster in Payna, from the API, a person in Payna, Okta or NMLS.
loan_officer.updatedAnything in their record changes: a license status, a sponsorship, onboarding, education, contact details.
webhook.testYou call the test endpoint.

An event arrives within an hour of the change. A change you make with POST /loan-officers arrives right away.

The payload

{
  "id": "0b8c6f1e-3d0c-4a51-9f8e-2c7d1a4b5e60",
  "type": "loan_officer.updated",
  "created_at": "2026-12-03T17:02:11Z",
  "data": {
    "object": {
      "id": "c1d2e3f4-0000-0000-0000-aabbccddeeff",
      "nmls_id": "1234567",
      "can_originate_in": ["FL", "TX"],
      "...": "..."
    },
    "previous_attributes": {
      "can_originate_in": ["TX"]
    }
  }
}

data.object is the whole LoanOfficer, the same as the GET returns. previous_attributes holds each top-level field that changed, with its value before.

Verifying a signature

Events are signed to the Standard Webhooks specification, with the headers webhook-id, webhook-timestamp and webhook-signature. Verify the raw body before you parse it.

import { Webhook } from 'standardwebhooks'

const wh = new Webhook(process.env.PAYNA_WEBHOOK_SECRET)

app.post('/payna', express.raw({ type: 'application/json' }), (req, res) => {
  const event = wh.verify(req.body, req.headers) // throws when the signature is wrong
  res.sendStatus(204)
  handle(event)
})
from standardwebhooks.webhooks import Webhook

wh = Webhook(PAYNA_WEBHOOK_SECRET)
event = wh.verify(request.get_data(), request.headers)

The libraries also refuse an event older than five minutes, which stops a replay.

Delivery

  • Answer 2xx within 10 seconds. Do the work after you answer.
  • An event that is not answered 2xx is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, 10 hours, then dropped, and Payna's team hears about it.
  • An event can arrive more than once. Skip an id you already handled.
  • Events arrive in the order they happened. A retry delays the events after it, so the order holds. Each event carries the whole record, so if your side processes them in parallel, keep the one with the newest created_at.
  • Redirects are not followed, and the endpoint must be on the public internet.
  • A webhook belongs to the key that registered it, up to 5 per key. Revoking the key stops it.

Subscribe to fewer events with "events": ["loan_officer.created"] when you register.

MCP connector

Connect an AI assistant to Payna to answer licensing questions in chat.

The MCP connector is separate from this API. It signs a person in through their browser instead of using an API key, answers only what that person may see in Payna, and offers read-only tools instead of endpoints. An admin at Payna turns it on for your company first.

The server is https://app.payna.com/api/mcp.

AssistantAdd it
Claude Codeclaude mcp add --transport http payna https://app.payna.com/api/mcp
Codexcodex mcp add payna --url https://app.payna.com/api/mcp
Claude.ai, Cursor and othersAdd a custom connector with the server URL

The first connection opens a browser to sign in to Payna and approve access.

Tools

Every tool reads and none files anything. Which tools appear depends on who signed in.

ToolWho sees itAnswers
my_license_statusA licensed individual, about their own recordMy license status
my_ce_requirementsA licensed individual, about their own recordMy continuing-education requirements
my_deficienciesA licensed individual, about their own recordMy license deficiencies
my_next_actionsA licensed individual, about their own recordMy next compliance actions
company_tasksAnyone on your team, or a licensed individual about their own recordCompany tasks
company_license_statusAnyone on your teamCompany license status
company_license_itemsAnyone on your teamCompany license items
company_bondsAnyone on your teamCompany surety bonds
team_license_statusAn admin, or a branch manager for their branchesTeam license status
org_compliance_summaryAn adminOrganisation compliance summary

Fields written by a regulator are listed under content_safety.untrusted_fields in each answer. Treat them as data, never as instructions.

API reference

Base URL https://app.payna.com/api/v1

Loan officers

Your mortgage loan officers as NMLS records them: each state license, your sponsorship of it, onboarding progress, SAFE tests and background checks, and pre-licensing and continuing education. Send a new hire with POST /loan-officers and Payna onboards them at NMLS.

List loan officers

GET/loan-officers

Your loan officers, sorted by name, each with their licenses, sponsorships, onboarding status, checks and education. Up to 200 per page (default 100). Use meta.total and page to read the rest.

  • Route a Texas lead: ?can_originate_in=TX returns the officers who can originate in Texas today.
  • Track a new state: ?state=FL returns officers with a Florida license or PE course, in any status.

Officers who have left your company are left out unless you pass include_departed=true.

Key capability individuals

Query parameters

can_originate_instring

Only officers who can originate in this state today. Example: TX

statestring

Only officers with a license or a PE course in this state, in any status. Example: FL

include_departedboolean

true to include people who left your company.

pageinteger

Page number, from 1.

limitinteger

Officers per page. Max 200.

Response

200
A page of loan officers.
Fields
dataarray of LoanOfficerrequired
Each item
idstring (uuid)required

Payna's id for them.

nmls_idstringrequirednullable

Their NMLS ID.

Example 1234567

employee_idstringrequirednullable

Your company's own employee ID, as your HR system or directory sent it. Null when none was sent.

Example E10442

namestringrequired

Example Jane Example

first_namestringrequirednullable
last_namestringrequirednullable
emailstringrequirednullable

Their work email.

titlestringrequirednullable

Their job title, if your company set one.

officestringrequirednullable

The office NMLS lists them at. "(Main Office)" when it is your main office.

Example Irvine, CA

employment_statusenumrequirednullable

terminated means they left. Those are only listed with include_departed=true.

One of active inactive terminated pending

can_originate_inarray of stringsrequired

States where they can originate for you today: the license is approved at NMLS and your company's sponsorship is accepted. Temporary Authority is not counted. Same rule as each license's can_originate, including its one exception.

onboardingLoanOfficerOnboardingrequired

Where they are in joining your company. The same status your team sees on the People page in Payna.

Fields
statusenumrequirednullable

Payna's onboarding status, not an NMLS status. NMLS's own words are on each license: nmls_status and sponsorship.

  • sponsored: done. Every license your company set out to sponsor is accepted.
  • sponsoring: sponsorship is filed or about to be, for some of their licenses.
  • awaiting_access: the officer has to accept your company's access request in NMLS.
  • missing_info: Payna needs details from your company to file.
  • not_started: your company sponsors none of their licenses and nothing is filed.
  • deficient: NMLS marks one of their licenses, or a sponsorship of one, deficient.
  • null: not known yet.

One of deficient missing_info not_started awaiting_access sponsoring sponsored

waiting_onenumrequirednullable

Who has to act next. company is you. state is the regulator. Null when nobody needs to, or when NMLS does not say who: a deficient officer needs action from them or from you.

One of company officer payna state

start_datestring (date)requirednullable

The day they start with your company, while they are onboarding.

start_date_confirmedbooleanrequirednullable

true when the start date is confirmed, false when it is an estimate.

sponsored_inarray of stringsrequired

States where your sponsorship is accepted.

sponsorship_pending_inarray of stringsrequired

States where sponsorship is filed and waiting on the state.

sponsorship_deficient_inarray of stringsrequired

States where NMLS calls the sponsorship Deficient: filed, and waiting on the officer or your company. A state can also be in sponsored_in when another license there is accepted. The officer's onboarding.status is then deficient.

sponsorship_planned_inarray of stringsrequired

States Payna will file sponsorship in next.

licensesarray of LoanOfficerLicenserequired

Every license NMLS lists for them, at any company, sorted by state.

Each item
statestringrequired

Example TX

license_namestringrequirednullable

Example Texas-SML Mortgage Loan Originator License

license_numberstringrequirednullable
nmls_statusstringrequirednullable

The license's status, exactly as NMLS shows it: "Approved", "Approved - Inactive", "Pending - Incomplete", "Terminated - Expired"...

Example Approved

can_originatebooleanrequired

Approved at NMLS and sponsored by your company. Use this for lead routing.

One exception: when Payna does not have an officer's sponsorships yet (sponsorship is null on all their licenses), an approved license counts, because "unknown" is not "not sponsored". To require confirmed sponsorship, also check sponsorship is Accepted.

temporary_authoritybooleanrequired

true while they work under Temporary Authority. Not counted in can_originate.

sponsorshipenumrequirednullable

Your company's sponsorship of this license, in NMLS's own words: Accepted (approved), Requested, Deficient (awaiting action from the officer or your company), Rejected, Removed (withdrawn). Requested also covers a request Payna filed that NMLS does not show yet. Not sponsored by this company when NMLS lists no sponsorship of it by you. Null when NMLS has ended the license, or is ending it, and your company did not sponsor it. Also null when Payna does not have it yet, or cannot tell which of two licenses in a state it belongs to.

One of Accepted Requested Deficient Rejected Removed Not sponsored by this company

sponsorship_nmls_statusstringrequirednullable

That sponsorship's status, exactly as NMLS shows it: "Accepted", "Requested", "Deficient", "Rejected", "Removed". Null when NMLS shows none.

Example Accepted

sponsored_sincestring (date)requirednullable

The day NMLS accepted your sponsorship.

sponsorship_requested_onstring (date)requirednullable

The day sponsorship was requested, kept after it is accepted. Known for sponsorships Payna filed; null for ones filed before Payna, because NMLS does not date them.

open_itemsarray of objectsrequired

What NMLS still wants for this license, oldest first. Empty when nothing is open.

Each item
titlestringrequired

NMLS's own title, e.g. "State Criminal Background Check Required".

sincestring (date)requirednullable

The day NMLS raised it.

renewal_duestring (date)requirednullable

When the license must be renewed.

renewed_throughintegerrequirednullable

The last year it is renewed for.

Example 2026

renewal_statusenumrequirednullable

NMLS's Current Renewal Status for this license this season: submitted (NMLS shows the renewal requested or approved), not_submitted, failed (NMLS shows "Failed to renew"), or unknown (a word NMLS uses that Payna does not know yet; count it as not submitted). Null for a license NMLS holds no record of, and for every license while NMLS states no renewal status for your company at all.

One of submitted not_submitted failed unknown

Example submitted

last_synced_atstring (date-time)requirednullable

When Payna last updated this license.

checksLoanOfficerChecksrequirednullable

Their SAFE tests, criminal background checks and credit reports, as their NMLS record shows them. Null until Payna has them. Within it, a list that is null is not known yet, and an empty list is known to be empty. Newest first.

Fields
safe_testsarray of objectsrequirednullable

Every SAFE test NMLS lists. Results only, never scores.

Each item
teststringrequired
datestring (date)requirednullable
resultstringrequired

Example Passed

background_checksarray of objectsrequirednullable

Every criminal background check NMLS lists.

Each item
statusstringrequired

Example Completed

status_datestring (date)requirednullable
reason_closedstringrequirednullable
methodstringrequirednullable

Example Electronic

fingerprints_takenstring (date)requirednullable
fingerprints_expirestringrequirednullable

When their fingerprint record expires: a date, or expired. Null when NMLS shows none.

Example 2027-01-30

credit_reportsarray of string (date)srequirednullable

When each credit report was pulled.

as_ofstring (date)required

When Payna last updated them.

educationobjectrequired

ce_hours is this year's CE from NMLS. pe_hours is their PE from NMLS. courses is what they are enrolled in at your course provider (Knowledge Coop).

Fields
ce_hoursCeHoursrequirednullable

This year's CE hours from their NMLS transcript. Null when none of their licenses needs CE.

Fields
yearintegerrequired

Example 2026

hours_requirednumberrequired

Example 9

hours_completednumberrequired

Example 7

completebooleanrequired

true when nothing is left.

still_neededarray of objectsrequired

What is left, and by when.

Each item
forstringrequired

Core, Elective, or a state like TX or CA-DFPI.

Example TX

hoursnumberrequired
due_datestring (date)requirednullable
pe_hoursPeHoursrequirednullable

Their pre-licensing education as their NMLS education record shows it: the federal 20 hours, and each license's own state PE. Licenses they no longer hold are left out. Null until Payna has their NMLS education record.

Fields
federalPeFederalrequirednullable

The 20 federal hours, done once. hours_completed is every PE hour NMLS applied, state PE included, so it can be more than 20. Null when NMLS shows no row.

Fields
statusstringrequired

NMLS's own word: Compliant, Pending, Not Required.

Example Compliant

completebooleanrequired

Compliant or Not Required.

hours_requirednumberrequirednullable

Example 20

hours_completednumberrequirednullable

Example 24

status_datestring (date)requirednullable

The date NMLS gives that status.

Example 2019-04-02

statesarray of PeStaterequired

One row per license NMLS lists a state PE requirement for, sorted by jurisdiction.

Each item
statestringrequired

Example FL

jurisdictionstringrequirednullable

Set when NMLS splits the state: CA-DFPI, TX-SML, UT-DRE.

Example CA-DFPI

license_namestringrequired

Example Mortgage Loan Originator License

statusstringrequired

NMLS's own word: Compliant, Pending, Not Required.

Example Pending

completebooleanrequired

Compliant or Not Required.

hours_requirednumberrequirednullable

Example 2

hours_completednumberrequirednullable

Example 0

status_datestring (date)requirednullable

The date NMLS gives that status.

Example 2026-10-12

coursesarray of Courserequired
Each item
typeenumrequired

PE is pre-licensing education, for a state they are getting licensed in. CE is continuing education.

One of PE CE

statestringrequirednullable

Null for the federal 7-hour core.

Example FL

jurisdictionstringrequirednullable

Set when NMLS splits the state: CA-DFPI, TX-SML, UT-DRE.

Example CA-DFPI

yearintegerrequirednullable

The CE year. Null for PE.

titlestringrequired

Example 2 Hour Florida SAFE PE

providerstringrequired

Example Knowledge Coop

statusenumrequired

One of not_started in_progress completed

percent_completeintegerrequirednullable

0 to 100. Null when the provider does not say.

Example 50

due_datestring (date)requirednullable

When the provider says it is due.

overduebooleanrequired

Past due_date and not completed.

completed_onstring (date)requirednullable

The day they passed it.

last_syncedobjectrequired

How fresh their data is.

Fields
nmlsstring (date-time)requirednullable

The oldest update among their licenses, so all of them are at least this fresh. Null when they have no license, or one has no update yet.

educationstring (date-time)requirednullable

When Payna last updated their courses. Null when they have no account at your course provider.

metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404Loan officers are not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/loan-officers \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": [
    {
      "id": "c1d2e3f4-0000-0000-0000-aabbccddeeff",
      "nmls_id": "1234567",
      "employee_id": "E10442",
      "name": "Jane Example",
      "first_name": "Jane",
      "last_name": "Example",
      "email": "jane@examplemortgage.com",
      "title": "Loan Officer",
      "office": "Irvine, CA",
      "employment_status": "active",
      "can_originate_in": ["TX"],
      "onboarding": {
        "status": "sponsoring",
        "waiting_on": "state",
        "start_date": "2026-10-15",
        "start_date_confirmed": true,
        "sponsored_in": ["TX"],
        "sponsorship_pending_in": ["FL"],
        "sponsorship_deficient_in": [],
        "sponsorship_planned_in": []
      },
      "licenses": [
        {
          "state": "FL",
          "license_name": "Florida Loan Originator License",
          "license_number": null,
          "nmls_status": "Pending - Incomplete",
          "can_originate": false,
          "temporary_authority": false,
          "sponsorship": "Requested",
          "sponsorship_nmls_status": "Requested",
          "sponsored_since": null,
          "sponsorship_requested_on": "2026-10-20",
          "open_items": [
            {
              "title": "State Criminal Background Check Required",
              "since": "2026-10-21"
            }
          ],
          "renewal_due": null,
          "renewed_through": null,
          "renewal_status": null,
          "last_synced_at": "2026-10-30T17:17:28Z"
        },
        {
          "state": "TX",
          "license_name": "Texas-SML Mortgage Loan Originator License",
          "license_number": "1234567",
          "nmls_status": "Approved",
          "can_originate": true,
          "temporary_authority": false,
          "sponsorship": "Accepted",
          "sponsorship_nmls_status": "Accepted",
          "sponsored_since": "2026-09-10",
          "sponsorship_requested_on": "2026-09-02",
          "open_items": [],
          "renewal_due": "2026-12-31",
          "renewed_through": 2026,
          "renewal_status": "submitted",
          "last_synced_at": "2026-10-30T17:17:28Z"
        }
      ],
      "checks": {
        "safe_tests": [
          {
            "test": "SAFE MLO Test - National Component with Uniform State Content",
            "date": "2024-03-02",
            "result": "Passed"
          }
        ],
        "background_checks": [
          {
            "status": "Completed",
            "status_date": "2024-02-01",
            "reason_closed": null,
            "method": "Electronic",
            "fingerprints_taken": "2024-01-30"
          }
        ],
        "fingerprints_expire": "2027-01-30",
        "credit_reports": ["2026-02-11"],
        "as_of": "2026-10-30"
      },
      "education": {
        "ce_hours": {
          "year": 2026,
          "hours_required": 9,
          "hours_completed": 7,
          "complete": false,
          "still_needed": [
            {
              "for": "TX",
              "hours": 2,
              "due_date": "2026-12-31"
            }
          ]
        },
        "pe_hours": {
          "federal": {
            "status": "Compliant",
            "complete": true,
            "hours_required": 20,
            "hours_completed": 24,
            "status_date": "2019-04-02"
          },
          "states": [
            {
              "state": "FL",
              "jurisdiction": null,
              "license_name": "Mortgage Loan Originator License",
              "status": "Pending",
              "complete": false,
              "hours_required": 2,
              "hours_completed": 0,
              "status_date": "2026-10-12"
            },
            {
              "state": "TX",
              "jurisdiction": "TX-SML",
              "license_name": "Mortgage Loan Originator",
              "status": "Compliant",
              "complete": true,
              "hours_required": 0,
              "hours_completed": 0,
              "status_date": "2019-05-01"
            }
          ]
        },
        "courses": [
          {
            "type": "PE",
            "state": "FL",
            "jurisdiction": null,
            "year": null,
            "title": "2 Hour Florida SAFE PE",
            "provider": "Knowledge Coop",
            "status": "in_progress",
            "percent_complete": 50,
            "due_date": "2026-11-07",
            "overdue": false,
            "completed_on": null
          },
          {
            "type": "CE",
            "state": "TX",
            "jurisdiction": "TX-SML",
            "year": 2026,
            "title": "2 Hour Texas SML SAFE CE",
            "provider": "Knowledge Coop",
            "status": "not_started",
            "percent_complete": 0,
            "due_date": "2026-12-31",
            "overdue": false,
            "completed_on": null
          }
        ]
      },
      "last_synced": {
        "nmls": "2026-10-30T17:17:28Z",
        "education": "2026-10-30T07:00:00Z"
      }
    }
  ],
  "meta": {
    "total": 104,
    "page": 1,
    "limit": 100,
    "synced_at": "2026-10-30T17:17:28Z"
  }
}

Onboard a loan officer

POST/loan-officers

Send a loan officer your company has hired. Payna adds them to your team, requests access to their NMLS record, files the relationship once they accept, and sponsors their licenses. The response is the same LoanOfficer the GET returns; follow onboarding.status, or subscribe to webhooks to hear each change.

Safe to retry. Payna matches your roster on employee_id, then nmls_id, and answers 200 for a person it already has. A hire your systems sent takes the new answers, except any a person on your team changed in Payna. An officer Payna already knew from NMLS or from your team keeps their answers: only the employee_id is recorded, and sponsor_states answers 409.

Payna requests access to their NMLS record as soon as the hire arrives when your company has that turned on. Ask Payna to turn it on. Your company approves the relationship and sponsorship filings the way it already approves filings in Payna.

See the Onboarding guide for what each field becomes at NMLS.

Key capability onboarding and individuals

Body

employee_idstring

Your own employee ID. Payna matches on it first, stores it, and returns it as employee_id on every read.

Example E10442

nmls_idstringrequired

Their individual NMLS ID.

Example 1234567

first_namestringrequired

Legal first name.

Example Jane

last_namestringrequired

Legal last name.

Example Example

work_emailstring (email)required

Their company email. NMLS shows it on the relationship, and Payna writes to them there.

Example jane.example@examplemortgage.com

work_phonestringrequired

Their work phone. NMLS requires it.

Example 949-555-0142

work_phone_extensionstring

Example 214

titlestringrequired

Their position title, as NMLS will show it.

Example Loan Officer

start_datestring (date)required

Their first day with your company. NMLS calls it the relationship effective date.

Example 2026-12-01

start_date_confirmedboolean

true when the date is settled. Payna files the relationship only on a confirmed date. When false or left out, Payna treats the date as an estimate and asks the officer to confirm it if your company has the start date request turned on.

worker_classificationenumrequired

How you pay them.

One of 1099 W2

work_arrangementenumrequired

Where they work. NMLS asks whether the officer works remotely.

One of office hybrid remote

branch_codestringrequired

The office they work out of: your own branch code, or the branch's NMLS ID. Your main office counts.

Example 101

works_from_homeboolean

Required when work_arrangement is hybrid or remote: whether they work from their home address.

work_addressany

Required when works_from_home is false: the address they work from instead.

sponsor_statesarray of strings

First sponsorship only. The states to sponsor a new hire's licenses in, filed on their start date after the relationship. Left out, Payna sponsors the states your company sponsors every officer in. Sponsoring more states later is not available through the API: ask Payna. A state the filed first sponsorship does not cover, or sponsor_states for an officer already on your team in Payna, answers 409.

Response

200
Payna already had them.
Fields
dataLoanOfficerrequired

One loan officer and everything Payna knows about them.

Fields
idstring (uuid)required

Payna's id for them.

nmls_idstringrequirednullable

Their NMLS ID.

Example 1234567

employee_idstringrequirednullable

Your company's own employee ID, as your HR system or directory sent it. Null when none was sent.

Example E10442

namestringrequired

Example Jane Example

first_namestringrequirednullable
last_namestringrequirednullable
emailstringrequirednullable

Their work email.

titlestringrequirednullable

Their job title, if your company set one.

officestringrequirednullable

The office NMLS lists them at. "(Main Office)" when it is your main office.

Example Irvine, CA

employment_statusenumrequirednullable

terminated means they left. Those are only listed with include_departed=true.

One of active inactive terminated pending

can_originate_inarray of stringsrequired

States where they can originate for you today: the license is approved at NMLS and your company's sponsorship is accepted. Temporary Authority is not counted. Same rule as each license's can_originate, including its one exception.

onboardingLoanOfficerOnboardingrequired

Where they are in joining your company. The same status your team sees on the People page in Payna.

Fields
statusenumrequirednullable

Payna's onboarding status, not an NMLS status. NMLS's own words are on each license: nmls_status and sponsorship.

  • sponsored: done. Every license your company set out to sponsor is accepted.
  • sponsoring: sponsorship is filed or about to be, for some of their licenses.
  • awaiting_access: the officer has to accept your company's access request in NMLS.
  • missing_info: Payna needs details from your company to file.
  • not_started: your company sponsors none of their licenses and nothing is filed.
  • deficient: NMLS marks one of their licenses, or a sponsorship of one, deficient.
  • null: not known yet.

One of deficient missing_info not_started awaiting_access sponsoring sponsored

waiting_onenumrequirednullable

Who has to act next. company is you. state is the regulator. Null when nobody needs to, or when NMLS does not say who: a deficient officer needs action from them or from you.

One of company officer payna state

start_datestring (date)requirednullable

The day they start with your company, while they are onboarding.

start_date_confirmedbooleanrequirednullable

true when the start date is confirmed, false when it is an estimate.

sponsored_inarray of stringsrequired

States where your sponsorship is accepted.

sponsorship_pending_inarray of stringsrequired

States where sponsorship is filed and waiting on the state.

sponsorship_deficient_inarray of stringsrequired

States where NMLS calls the sponsorship Deficient: filed, and waiting on the officer or your company. A state can also be in sponsored_in when another license there is accepted. The officer's onboarding.status is then deficient.

sponsorship_planned_inarray of stringsrequired

States Payna will file sponsorship in next.

licensesarray of LoanOfficerLicenserequired

Every license NMLS lists for them, at any company, sorted by state.

Each item
statestringrequired

Example TX

license_namestringrequirednullable

Example Texas-SML Mortgage Loan Originator License

license_numberstringrequirednullable
nmls_statusstringrequirednullable

The license's status, exactly as NMLS shows it: "Approved", "Approved - Inactive", "Pending - Incomplete", "Terminated - Expired"...

Example Approved

can_originatebooleanrequired

Approved at NMLS and sponsored by your company. Use this for lead routing.

One exception: when Payna does not have an officer's sponsorships yet (sponsorship is null on all their licenses), an approved license counts, because "unknown" is not "not sponsored". To require confirmed sponsorship, also check sponsorship is Accepted.

temporary_authoritybooleanrequired

true while they work under Temporary Authority. Not counted in can_originate.

sponsorshipenumrequirednullable

Your company's sponsorship of this license, in NMLS's own words: Accepted (approved), Requested, Deficient (awaiting action from the officer or your company), Rejected, Removed (withdrawn). Requested also covers a request Payna filed that NMLS does not show yet. Not sponsored by this company when NMLS lists no sponsorship of it by you. Null when NMLS has ended the license, or is ending it, and your company did not sponsor it. Also null when Payna does not have it yet, or cannot tell which of two licenses in a state it belongs to.

One of Accepted Requested Deficient Rejected Removed Not sponsored by this company

sponsorship_nmls_statusstringrequirednullable

That sponsorship's status, exactly as NMLS shows it: "Accepted", "Requested", "Deficient", "Rejected", "Removed". Null when NMLS shows none.

Example Accepted

sponsored_sincestring (date)requirednullable

The day NMLS accepted your sponsorship.

sponsorship_requested_onstring (date)requirednullable

The day sponsorship was requested, kept after it is accepted. Known for sponsorships Payna filed; null for ones filed before Payna, because NMLS does not date them.

open_itemsarray of objectsrequired

What NMLS still wants for this license, oldest first. Empty when nothing is open.

Each item
titlestringrequired

NMLS's own title, e.g. "State Criminal Background Check Required".

sincestring (date)requirednullable

The day NMLS raised it.

renewal_duestring (date)requirednullable

When the license must be renewed.

renewed_throughintegerrequirednullable

The last year it is renewed for.

Example 2026

renewal_statusenumrequirednullable

NMLS's Current Renewal Status for this license this season: submitted (NMLS shows the renewal requested or approved), not_submitted, failed (NMLS shows "Failed to renew"), or unknown (a word NMLS uses that Payna does not know yet; count it as not submitted). Null for a license NMLS holds no record of, and for every license while NMLS states no renewal status for your company at all.

One of submitted not_submitted failed unknown

Example submitted

last_synced_atstring (date-time)requirednullable

When Payna last updated this license.

checksLoanOfficerChecksrequirednullable

Their SAFE tests, criminal background checks and credit reports, as their NMLS record shows them. Null until Payna has them. Within it, a list that is null is not known yet, and an empty list is known to be empty. Newest first.

Fields
safe_testsarray of objectsrequirednullable

Every SAFE test NMLS lists. Results only, never scores.

Each item
teststringrequired
datestring (date)requirednullable
resultstringrequired

Example Passed

background_checksarray of objectsrequirednullable

Every criminal background check NMLS lists.

Each item
statusstringrequired

Example Completed

status_datestring (date)requirednullable
reason_closedstringrequirednullable
methodstringrequirednullable

Example Electronic

fingerprints_takenstring (date)requirednullable
fingerprints_expirestringrequirednullable

When their fingerprint record expires: a date, or expired. Null when NMLS shows none.

Example 2027-01-30

credit_reportsarray of string (date)srequirednullable

When each credit report was pulled.

as_ofstring (date)required

When Payna last updated them.

educationobjectrequired

ce_hours is this year's CE from NMLS. pe_hours is their PE from NMLS. courses is what they are enrolled in at your course provider (Knowledge Coop).

Fields
ce_hoursCeHoursrequirednullable

This year's CE hours from their NMLS transcript. Null when none of their licenses needs CE.

Fields
yearintegerrequired

Example 2026

hours_requirednumberrequired

Example 9

hours_completednumberrequired

Example 7

completebooleanrequired

true when nothing is left.

still_neededarray of objectsrequired

What is left, and by when.

Each item
forstringrequired

Core, Elective, or a state like TX or CA-DFPI.

Example TX

hoursnumberrequired
due_datestring (date)requirednullable
pe_hoursPeHoursrequirednullable

Their pre-licensing education as their NMLS education record shows it: the federal 20 hours, and each license's own state PE. Licenses they no longer hold are left out. Null until Payna has their NMLS education record.

Fields
federalPeFederalrequirednullable

The 20 federal hours, done once. hours_completed is every PE hour NMLS applied, state PE included, so it can be more than 20. Null when NMLS shows no row.

Fields
statusstringrequired

NMLS's own word: Compliant, Pending, Not Required.

Example Compliant

completebooleanrequired

Compliant or Not Required.

hours_requirednumberrequirednullable

Example 20

hours_completednumberrequirednullable

Example 24

status_datestring (date)requirednullable

The date NMLS gives that status.

Example 2019-04-02

statesarray of PeStaterequired

One row per license NMLS lists a state PE requirement for, sorted by jurisdiction.

Each item
statestringrequired

Example FL

jurisdictionstringrequirednullable

Set when NMLS splits the state: CA-DFPI, TX-SML, UT-DRE.

Example CA-DFPI

license_namestringrequired

Example Mortgage Loan Originator License

statusstringrequired

NMLS's own word: Compliant, Pending, Not Required.

Example Pending

completebooleanrequired

Compliant or Not Required.

hours_requirednumberrequirednullable

Example 2

hours_completednumberrequirednullable

Example 0

status_datestring (date)requirednullable

The date NMLS gives that status.

Example 2026-10-12

coursesarray of Courserequired
Each item
typeenumrequired

PE is pre-licensing education, for a state they are getting licensed in. CE is continuing education.

One of PE CE

statestringrequirednullable

Null for the federal 7-hour core.

Example FL

jurisdictionstringrequirednullable

Set when NMLS splits the state: CA-DFPI, TX-SML, UT-DRE.

Example CA-DFPI

yearintegerrequirednullable

The CE year. Null for PE.

titlestringrequired

Example 2 Hour Florida SAFE PE

providerstringrequired

Example Knowledge Coop

statusenumrequired

One of not_started in_progress completed

percent_completeintegerrequirednullable

0 to 100. Null when the provider does not say.

Example 50

due_datestring (date)requirednullable

When the provider says it is due.

overduebooleanrequired

Past due_date and not completed.

completed_onstring (date)requirednullable

The day they passed it.

last_syncedobjectrequired

How fresh their data is.

Fields
nmlsstring (date-time)requirednullable

The oldest update among their licenses, so all of them are at least this fresh. Null when they have no license, or one has no update yet.

educationstring (date-time)requirednullable

When Payna last updated their courses. Null when they have no account at your course provider.

201
A new loan officer. Location names them.
Fields
dataLoanOfficerrequired

One loan officer and everything Payna knows about them.

Fields
idstring (uuid)required

Payna's id for them.

nmls_idstringrequirednullable

Their NMLS ID.

Example 1234567

employee_idstringrequirednullable

Your company's own employee ID, as your HR system or directory sent it. Null when none was sent.

Example E10442

namestringrequired

Example Jane Example

first_namestringrequirednullable
last_namestringrequirednullable
emailstringrequirednullable

Their work email.

titlestringrequirednullable

Their job title, if your company set one.

officestringrequirednullable

The office NMLS lists them at. "(Main Office)" when it is your main office.

Example Irvine, CA

employment_statusenumrequirednullable

terminated means they left. Those are only listed with include_departed=true.

One of active inactive terminated pending

can_originate_inarray of stringsrequired

States where they can originate for you today: the license is approved at NMLS and your company's sponsorship is accepted. Temporary Authority is not counted. Same rule as each license's can_originate, including its one exception.

onboardingLoanOfficerOnboardingrequired

Where they are in joining your company. The same status your team sees on the People page in Payna.

Fields
statusenumrequirednullable

Payna's onboarding status, not an NMLS status. NMLS's own words are on each license: nmls_status and sponsorship.

  • sponsored: done. Every license your company set out to sponsor is accepted.
  • sponsoring: sponsorship is filed or about to be, for some of their licenses.
  • awaiting_access: the officer has to accept your company's access request in NMLS.
  • missing_info: Payna needs details from your company to file.
  • not_started: your company sponsors none of their licenses and nothing is filed.
  • deficient: NMLS marks one of their licenses, or a sponsorship of one, deficient.
  • null: not known yet.

One of deficient missing_info not_started awaiting_access sponsoring sponsored

waiting_onenumrequirednullable

Who has to act next. company is you. state is the regulator. Null when nobody needs to, or when NMLS does not say who: a deficient officer needs action from them or from you.

One of company officer payna state

start_datestring (date)requirednullable

The day they start with your company, while they are onboarding.

start_date_confirmedbooleanrequirednullable

true when the start date is confirmed, false when it is an estimate.

sponsored_inarray of stringsrequired

States where your sponsorship is accepted.

sponsorship_pending_inarray of stringsrequired

States where sponsorship is filed and waiting on the state.

sponsorship_deficient_inarray of stringsrequired

States where NMLS calls the sponsorship Deficient: filed, and waiting on the officer or your company. A state can also be in sponsored_in when another license there is accepted. The officer's onboarding.status is then deficient.

sponsorship_planned_inarray of stringsrequired

States Payna will file sponsorship in next.

licensesarray of LoanOfficerLicenserequired

Every license NMLS lists for them, at any company, sorted by state.

Each item
statestringrequired

Example TX

license_namestringrequirednullable

Example Texas-SML Mortgage Loan Originator License

license_numberstringrequirednullable
nmls_statusstringrequirednullable

The license's status, exactly as NMLS shows it: "Approved", "Approved - Inactive", "Pending - Incomplete", "Terminated - Expired"...

Example Approved

can_originatebooleanrequired

Approved at NMLS and sponsored by your company. Use this for lead routing.

One exception: when Payna does not have an officer's sponsorships yet (sponsorship is null on all their licenses), an approved license counts, because "unknown" is not "not sponsored". To require confirmed sponsorship, also check sponsorship is Accepted.

temporary_authoritybooleanrequired

true while they work under Temporary Authority. Not counted in can_originate.

sponsorshipenumrequirednullable

Your company's sponsorship of this license, in NMLS's own words: Accepted (approved), Requested, Deficient (awaiting action from the officer or your company), Rejected, Removed (withdrawn). Requested also covers a request Payna filed that NMLS does not show yet. Not sponsored by this company when NMLS lists no sponsorship of it by you. Null when NMLS has ended the license, or is ending it, and your company did not sponsor it. Also null when Payna does not have it yet, or cannot tell which of two licenses in a state it belongs to.

One of Accepted Requested Deficient Rejected Removed Not sponsored by this company

sponsorship_nmls_statusstringrequirednullable

That sponsorship's status, exactly as NMLS shows it: "Accepted", "Requested", "Deficient", "Rejected", "Removed". Null when NMLS shows none.

Example Accepted

sponsored_sincestring (date)requirednullable

The day NMLS accepted your sponsorship.

sponsorship_requested_onstring (date)requirednullable

The day sponsorship was requested, kept after it is accepted. Known for sponsorships Payna filed; null for ones filed before Payna, because NMLS does not date them.

open_itemsarray of objectsrequired

What NMLS still wants for this license, oldest first. Empty when nothing is open.

Each item
titlestringrequired

NMLS's own title, e.g. "State Criminal Background Check Required".

sincestring (date)requirednullable

The day NMLS raised it.

renewal_duestring (date)requirednullable

When the license must be renewed.

renewed_throughintegerrequirednullable

The last year it is renewed for.

Example 2026

renewal_statusenumrequirednullable

NMLS's Current Renewal Status for this license this season: submitted (NMLS shows the renewal requested or approved), not_submitted, failed (NMLS shows "Failed to renew"), or unknown (a word NMLS uses that Payna does not know yet; count it as not submitted). Null for a license NMLS holds no record of, and for every license while NMLS states no renewal status for your company at all.

One of submitted not_submitted failed unknown

Example submitted

last_synced_atstring (date-time)requirednullable

When Payna last updated this license.

checksLoanOfficerChecksrequirednullable

Their SAFE tests, criminal background checks and credit reports, as their NMLS record shows them. Null until Payna has them. Within it, a list that is null is not known yet, and an empty list is known to be empty. Newest first.

Fields
safe_testsarray of objectsrequirednullable

Every SAFE test NMLS lists. Results only, never scores.

Each item
teststringrequired
datestring (date)requirednullable
resultstringrequired

Example Passed

background_checksarray of objectsrequirednullable

Every criminal background check NMLS lists.

Each item
statusstringrequired

Example Completed

status_datestring (date)requirednullable
reason_closedstringrequirednullable
methodstringrequirednullable

Example Electronic

fingerprints_takenstring (date)requirednullable
fingerprints_expirestringrequirednullable

When their fingerprint record expires: a date, or expired. Null when NMLS shows none.

Example 2027-01-30

credit_reportsarray of string (date)srequirednullable

When each credit report was pulled.

as_ofstring (date)required

When Payna last updated them.

educationobjectrequired

ce_hours is this year's CE from NMLS. pe_hours is their PE from NMLS. courses is what they are enrolled in at your course provider (Knowledge Coop).

Fields
ce_hoursCeHoursrequirednullable

This year's CE hours from their NMLS transcript. Null when none of their licenses needs CE.

Fields
yearintegerrequired

Example 2026

hours_requirednumberrequired

Example 9

hours_completednumberrequired

Example 7

completebooleanrequired

true when nothing is left.

still_neededarray of objectsrequired

What is left, and by when.

Each item
forstringrequired

Core, Elective, or a state like TX or CA-DFPI.

Example TX

hoursnumberrequired
due_datestring (date)requirednullable
pe_hoursPeHoursrequirednullable

Their pre-licensing education as their NMLS education record shows it: the federal 20 hours, and each license's own state PE. Licenses they no longer hold are left out. Null until Payna has their NMLS education record.

Fields
federalPeFederalrequirednullable

The 20 federal hours, done once. hours_completed is every PE hour NMLS applied, state PE included, so it can be more than 20. Null when NMLS shows no row.

Fields
statusstringrequired

NMLS's own word: Compliant, Pending, Not Required.

Example Compliant

completebooleanrequired

Compliant or Not Required.

hours_requirednumberrequirednullable

Example 20

hours_completednumberrequirednullable

Example 24

status_datestring (date)requirednullable

The date NMLS gives that status.

Example 2019-04-02

statesarray of PeStaterequired

One row per license NMLS lists a state PE requirement for, sorted by jurisdiction.

Each item
statestringrequired

Example FL

jurisdictionstringrequirednullable

Set when NMLS splits the state: CA-DFPI, TX-SML, UT-DRE.

Example CA-DFPI

license_namestringrequired

Example Mortgage Loan Originator License

statusstringrequired

NMLS's own word: Compliant, Pending, Not Required.

Example Pending

completebooleanrequired

Compliant or Not Required.

hours_requirednumberrequirednullable

Example 2

hours_completednumberrequirednullable

Example 0

status_datestring (date)requirednullable

The date NMLS gives that status.

Example 2026-10-12

coursesarray of Courserequired
Each item
typeenumrequired

PE is pre-licensing education, for a state they are getting licensed in. CE is continuing education.

One of PE CE

statestringrequirednullable

Null for the federal 7-hour core.

Example FL

jurisdictionstringrequirednullable

Set when NMLS splits the state: CA-DFPI, TX-SML, UT-DRE.

Example CA-DFPI

yearintegerrequirednullable

The CE year. Null for PE.

titlestringrequired

Example 2 Hour Florida SAFE PE

providerstringrequired

Example Knowledge Coop

statusenumrequired

One of not_started in_progress completed

percent_completeintegerrequirednullable

0 to 100. Null when the provider does not say.

Example 50

due_datestring (date)requirednullable

When the provider says it is due.

overduebooleanrequired

Past due_date and not completed.

completed_onstring (date)requirednullable

The day they passed it.

last_syncedobjectrequired

How fresh their data is.

Fields
nmlsstring (date-time)requirednullable

The oldest update among their licenses, so all of them are at least this fresh. Null when they have no license, or one has no update yet.

educationstring (date-time)requirednullable

When Payna last updated their courses. Null when they have no account at your course provider.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404Loan officers are not turned on for your account.
409employee_id and nmls_id belong to two different officers at your company, the person they name is not one of your officers in Payna, the officer is listed under Left in Payna, or sponsor_states names a state their filed first sponsorship does not cover.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl -X POST https://app.payna.com/api/v1/loan-officers \
  -H "Authorization: Bearer $PAYNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "E10442",
    "nmls_id": "1234567",
    "first_name": "Jane",
    "last_name": "Example",
    "work_email": "jane.example@examplemortgage.com",
    "work_phone": "949-555-0142",
    "title": "Loan Officer",
    "start_date": "2026-12-01",
    "start_date_confirmed": true,
    "worker_classification": "W2",
    "work_arrangement": "hybrid",
    "branch_code": "101",
    "works_from_home": true
  }'
201 Created 200 OK
{
  "data": {
    "id": "c1d2e3f4-0000-0000-0000-aabbccddeeff",
    "nmls_id": "1234567",
    "employee_id": "E10442",
    "name": "Jane Example",
    "first_name": "Jane",
    "last_name": "Example",
    "email": "jane@examplemortgage.com",
    "title": "Loan Officer",
    "office": "Irvine, CA",
    "employment_status": "active",
    "can_originate_in": ["TX"],
    "onboarding": {
      "status": "sponsoring",
      "waiting_on": "state",
      "start_date": "2026-10-15",
      "start_date_confirmed": true,
      "sponsored_in": ["TX"],
      "sponsorship_pending_in": ["FL"],
      "sponsorship_deficient_in": [],
      "sponsorship_planned_in": []
    },
    "licenses": [
      {
        "state": "FL",
        "license_name": "Florida Loan Originator License",
        "license_number": null,
        "nmls_status": "Pending - Incomplete",
        "can_originate": false,
        "temporary_authority": false,
        "sponsorship": "Requested",
        "sponsorship_nmls_status": "Requested",
        "sponsored_since": null,
        "sponsorship_requested_on": "2026-10-20",
        "open_items": [
          {
            "title": "State Criminal Background Check Required",
            "since": "2026-10-21"
          }
        ],
        "renewal_due": null,
        "renewed_through": null,
        "renewal_status": null,
        "last_synced_at": "2026-10-30T17:17:28Z"
      },
      {
        "state": "TX",
        "license_name": "Texas-SML Mortgage Loan Originator License",
        "license_number": "1234567",
        "nmls_status": "Approved",
        "can_originate": true,
        "temporary_authority": false,
        "sponsorship": "Accepted",
        "sponsorship_nmls_status": "Accepted",
        "sponsored_since": "2026-09-10",
        "sponsorship_requested_on": "2026-09-02",
        "open_items": [],
        "renewal_due": "2026-12-31",
        "renewed_through": 2026,
        "renewal_status": "submitted",
        "last_synced_at": "2026-10-30T17:17:28Z"
      }
    ],
    "checks": {
      "safe_tests": [
        {
          "test": "SAFE MLO Test - National Component with Uniform State Content",
          "date": "2024-03-02",
          "result": "Passed"
        }
      ],
      "background_checks": [
        {
          "status": "Completed",
          "status_date": "2024-02-01",
          "reason_closed": null,
          "method": "Electronic",
          "fingerprints_taken": "2024-01-30"
        }
      ],
      "fingerprints_expire": "2027-01-30",
      "credit_reports": ["2026-02-11"],
      "as_of": "2026-10-30"
    },
    "education": {
      "ce_hours": {
        "year": 2026,
        "hours_required": 9,
        "hours_completed": 7,
        "complete": false,
        "still_needed": [
          {
            "for": "TX",
            "hours": 2,
            "due_date": "2026-12-31"
          }
        ]
      },
      "pe_hours": {
        "federal": {
          "status": "Compliant",
          "complete": true,
          "hours_required": 20,
          "hours_completed": 24,
          "status_date": "2019-04-02"
        },
        "states": [
          {
            "state": "FL",
            "jurisdiction": null,
            "license_name": "Mortgage Loan Originator License",
            "status": "Pending",
            "complete": false,
            "hours_required": 2,
            "hours_completed": 0,
            "status_date": "2026-10-12"
          },
          {
            "state": "TX",
            "jurisdiction": "TX-SML",
            "license_name": "Mortgage Loan Originator",
            "status": "Compliant",
            "complete": true,
            "hours_required": 0,
            "hours_completed": 0,
            "status_date": "2019-05-01"
          }
        ]
      },
      "courses": [
        {
          "type": "PE",
          "state": "FL",
          "jurisdiction": null,
          "year": null,
          "title": "2 Hour Florida SAFE PE",
          "provider": "Knowledge Coop",
          "status": "in_progress",
          "percent_complete": 50,
          "due_date": "2026-11-07",
          "overdue": false,
          "completed_on": null
        },
        {
          "type": "CE",
          "state": "TX",
          "jurisdiction": "TX-SML",
          "year": 2026,
          "title": "2 Hour Texas SML SAFE CE",
          "provider": "Knowledge Coop",
          "status": "not_started",
          "percent_complete": 0,
          "due_date": "2026-12-31",
          "overdue": false,
          "completed_on": null
        }
      ]
    },
    "last_synced": {
      "nmls": "2026-10-30T17:17:28Z",
      "education": "2026-10-30T07:00:00Z"
    }
  }
}

Get one loan officer

GET/loan-officers/{id}

One loan officer, by NMLS ID or by the id the list returns. Officers who have left your company are included.

Key capability individuals

Path parameters

idstringrequired

Their NMLS ID, like 1234567, or Payna's id.

Example 1234567

Response

200
The loan officer.
Fields
dataLoanOfficerrequired

One loan officer and everything Payna knows about them.

Fields
idstring (uuid)required

Payna's id for them.

nmls_idstringrequirednullable

Their NMLS ID.

Example 1234567

employee_idstringrequirednullable

Your company's own employee ID, as your HR system or directory sent it. Null when none was sent.

Example E10442

namestringrequired

Example Jane Example

first_namestringrequirednullable
last_namestringrequirednullable
emailstringrequirednullable

Their work email.

titlestringrequirednullable

Their job title, if your company set one.

officestringrequirednullable

The office NMLS lists them at. "(Main Office)" when it is your main office.

Example Irvine, CA

employment_statusenumrequirednullable

terminated means they left. Those are only listed with include_departed=true.

One of active inactive terminated pending

can_originate_inarray of stringsrequired

States where they can originate for you today: the license is approved at NMLS and your company's sponsorship is accepted. Temporary Authority is not counted. Same rule as each license's can_originate, including its one exception.

onboardingLoanOfficerOnboardingrequired

Where they are in joining your company. The same status your team sees on the People page in Payna.

Fields
statusenumrequirednullable

Payna's onboarding status, not an NMLS status. NMLS's own words are on each license: nmls_status and sponsorship.

  • sponsored: done. Every license your company set out to sponsor is accepted.
  • sponsoring: sponsorship is filed or about to be, for some of their licenses.
  • awaiting_access: the officer has to accept your company's access request in NMLS.
  • missing_info: Payna needs details from your company to file.
  • not_started: your company sponsors none of their licenses and nothing is filed.
  • deficient: NMLS marks one of their licenses, or a sponsorship of one, deficient.
  • null: not known yet.

One of deficient missing_info not_started awaiting_access sponsoring sponsored

waiting_onenumrequirednullable

Who has to act next. company is you. state is the regulator. Null when nobody needs to, or when NMLS does not say who: a deficient officer needs action from them or from you.

One of company officer payna state

start_datestring (date)requirednullable

The day they start with your company, while they are onboarding.

start_date_confirmedbooleanrequirednullable

true when the start date is confirmed, false when it is an estimate.

sponsored_inarray of stringsrequired

States where your sponsorship is accepted.

sponsorship_pending_inarray of stringsrequired

States where sponsorship is filed and waiting on the state.

sponsorship_deficient_inarray of stringsrequired

States where NMLS calls the sponsorship Deficient: filed, and waiting on the officer or your company. A state can also be in sponsored_in when another license there is accepted. The officer's onboarding.status is then deficient.

sponsorship_planned_inarray of stringsrequired

States Payna will file sponsorship in next.

licensesarray of LoanOfficerLicenserequired

Every license NMLS lists for them, at any company, sorted by state.

Each item
statestringrequired

Example TX

license_namestringrequirednullable

Example Texas-SML Mortgage Loan Originator License

license_numberstringrequirednullable
nmls_statusstringrequirednullable

The license's status, exactly as NMLS shows it: "Approved", "Approved - Inactive", "Pending - Incomplete", "Terminated - Expired"...

Example Approved

can_originatebooleanrequired

Approved at NMLS and sponsored by your company. Use this for lead routing.

One exception: when Payna does not have an officer's sponsorships yet (sponsorship is null on all their licenses), an approved license counts, because "unknown" is not "not sponsored". To require confirmed sponsorship, also check sponsorship is Accepted.

temporary_authoritybooleanrequired

true while they work under Temporary Authority. Not counted in can_originate.

sponsorshipenumrequirednullable

Your company's sponsorship of this license, in NMLS's own words: Accepted (approved), Requested, Deficient (awaiting action from the officer or your company), Rejected, Removed (withdrawn). Requested also covers a request Payna filed that NMLS does not show yet. Not sponsored by this company when NMLS lists no sponsorship of it by you. Null when NMLS has ended the license, or is ending it, and your company did not sponsor it. Also null when Payna does not have it yet, or cannot tell which of two licenses in a state it belongs to.

One of Accepted Requested Deficient Rejected Removed Not sponsored by this company

sponsorship_nmls_statusstringrequirednullable

That sponsorship's status, exactly as NMLS shows it: "Accepted", "Requested", "Deficient", "Rejected", "Removed". Null when NMLS shows none.

Example Accepted

sponsored_sincestring (date)requirednullable

The day NMLS accepted your sponsorship.

sponsorship_requested_onstring (date)requirednullable

The day sponsorship was requested, kept after it is accepted. Known for sponsorships Payna filed; null for ones filed before Payna, because NMLS does not date them.

open_itemsarray of objectsrequired

What NMLS still wants for this license, oldest first. Empty when nothing is open.

Each item
titlestringrequired

NMLS's own title, e.g. "State Criminal Background Check Required".

sincestring (date)requirednullable

The day NMLS raised it.

renewal_duestring (date)requirednullable

When the license must be renewed.

renewed_throughintegerrequirednullable

The last year it is renewed for.

Example 2026

renewal_statusenumrequirednullable

NMLS's Current Renewal Status for this license this season: submitted (NMLS shows the renewal requested or approved), not_submitted, failed (NMLS shows "Failed to renew"), or unknown (a word NMLS uses that Payna does not know yet; count it as not submitted). Null for a license NMLS holds no record of, and for every license while NMLS states no renewal status for your company at all.

One of submitted not_submitted failed unknown

Example submitted

last_synced_atstring (date-time)requirednullable

When Payna last updated this license.

checksLoanOfficerChecksrequirednullable

Their SAFE tests, criminal background checks and credit reports, as their NMLS record shows them. Null until Payna has them. Within it, a list that is null is not known yet, and an empty list is known to be empty. Newest first.

Fields
safe_testsarray of objectsrequirednullable

Every SAFE test NMLS lists. Results only, never scores.

Each item
teststringrequired
datestring (date)requirednullable
resultstringrequired

Example Passed

background_checksarray of objectsrequirednullable

Every criminal background check NMLS lists.

Each item
statusstringrequired

Example Completed

status_datestring (date)requirednullable
reason_closedstringrequirednullable
methodstringrequirednullable

Example Electronic

fingerprints_takenstring (date)requirednullable
fingerprints_expirestringrequirednullable

When their fingerprint record expires: a date, or expired. Null when NMLS shows none.

Example 2027-01-30

credit_reportsarray of string (date)srequirednullable

When each credit report was pulled.

as_ofstring (date)required

When Payna last updated them.

educationobjectrequired

ce_hours is this year's CE from NMLS. pe_hours is their PE from NMLS. courses is what they are enrolled in at your course provider (Knowledge Coop).

Fields
ce_hoursCeHoursrequirednullable

This year's CE hours from their NMLS transcript. Null when none of their licenses needs CE.

Fields
yearintegerrequired

Example 2026

hours_requirednumberrequired

Example 9

hours_completednumberrequired

Example 7

completebooleanrequired

true when nothing is left.

still_neededarray of objectsrequired

What is left, and by when.

Each item
forstringrequired

Core, Elective, or a state like TX or CA-DFPI.

Example TX

hoursnumberrequired
due_datestring (date)requirednullable
pe_hoursPeHoursrequirednullable

Their pre-licensing education as their NMLS education record shows it: the federal 20 hours, and each license's own state PE. Licenses they no longer hold are left out. Null until Payna has their NMLS education record.

Fields
federalPeFederalrequirednullable

The 20 federal hours, done once. hours_completed is every PE hour NMLS applied, state PE included, so it can be more than 20. Null when NMLS shows no row.

Fields
statusstringrequired

NMLS's own word: Compliant, Pending, Not Required.

Example Compliant

completebooleanrequired

Compliant or Not Required.

hours_requirednumberrequirednullable

Example 20

hours_completednumberrequirednullable

Example 24

status_datestring (date)requirednullable

The date NMLS gives that status.

Example 2019-04-02

statesarray of PeStaterequired

One row per license NMLS lists a state PE requirement for, sorted by jurisdiction.

Each item
statestringrequired

Example FL

jurisdictionstringrequirednullable

Set when NMLS splits the state: CA-DFPI, TX-SML, UT-DRE.

Example CA-DFPI

license_namestringrequired

Example Mortgage Loan Originator License

statusstringrequired

NMLS's own word: Compliant, Pending, Not Required.

Example Pending

completebooleanrequired

Compliant or Not Required.

hours_requirednumberrequirednullable

Example 2

hours_completednumberrequirednullable

Example 0

status_datestring (date)requirednullable

The date NMLS gives that status.

Example 2026-10-12

coursesarray of Courserequired
Each item
typeenumrequired

PE is pre-licensing education, for a state they are getting licensed in. CE is continuing education.

One of PE CE

statestringrequirednullable

Null for the federal 7-hour core.

Example FL

jurisdictionstringrequirednullable

Set when NMLS splits the state: CA-DFPI, TX-SML, UT-DRE.

Example CA-DFPI

yearintegerrequirednullable

The CE year. Null for PE.

titlestringrequired

Example 2 Hour Florida SAFE PE

providerstringrequired

Example Knowledge Coop

statusenumrequired

One of not_started in_progress completed

percent_completeintegerrequirednullable

0 to 100. Null when the provider does not say.

Example 50

due_datestring (date)requirednullable

When the provider says it is due.

overduebooleanrequired

Past due_date and not completed.

completed_onstring (date)requirednullable

The day they passed it.

last_syncedobjectrequired

How fresh their data is.

Fields
nmlsstring (date-time)requirednullable

The oldest update among their licenses, so all of them are at least this fresh. Null when they have no license, or one has no update yet.

educationstring (date-time)requirednullable

When Payna last updated their courses. Null when they have no account at your course provider.

metaobjectrequired
Fields
synced_atstring (date-time)requirednullable

The same as last_synced.nmls.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404No loan officer with that NMLS ID or id at your company, or loan officers are not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/loan-officers/1234567 \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": {
    "id": "c1d2e3f4-0000-0000-0000-aabbccddeeff",
    "nmls_id": "1234567",
    "employee_id": "E10442",
    "name": "Jane Example",
    "first_name": "Jane",
    "last_name": "Example",
    "email": "jane@examplemortgage.com",
    "title": "Loan Officer",
    "office": "Irvine, CA",
    "employment_status": "active",
    "can_originate_in": ["TX"],
    "onboarding": {
      "status": "sponsoring",
      "waiting_on": "state",
      "start_date": "2026-10-15",
      "start_date_confirmed": true,
      "sponsored_in": ["TX"],
      "sponsorship_pending_in": ["FL"],
      "sponsorship_deficient_in": [],
      "sponsorship_planned_in": []
    },
    "licenses": [
      {
        "state": "FL",
        "license_name": "Florida Loan Originator License",
        "license_number": null,
        "nmls_status": "Pending - Incomplete",
        "can_originate": false,
        "temporary_authority": false,
        "sponsorship": "Requested",
        "sponsorship_nmls_status": "Requested",
        "sponsored_since": null,
        "sponsorship_requested_on": "2026-10-20",
        "open_items": [
          {
            "title": "State Criminal Background Check Required",
            "since": "2026-10-21"
          }
        ],
        "renewal_due": null,
        "renewed_through": null,
        "renewal_status": null,
        "last_synced_at": "2026-10-30T17:17:28Z"
      },
      {
        "state": "TX",
        "license_name": "Texas-SML Mortgage Loan Originator License",
        "license_number": "1234567",
        "nmls_status": "Approved",
        "can_originate": true,
        "temporary_authority": false,
        "sponsorship": "Accepted",
        "sponsorship_nmls_status": "Accepted",
        "sponsored_since": "2026-09-10",
        "sponsorship_requested_on": "2026-09-02",
        "open_items": [],
        "renewal_due": "2026-12-31",
        "renewed_through": 2026,
        "renewal_status": "submitted",
        "last_synced_at": "2026-10-30T17:17:28Z"
      }
    ],
    "checks": {
      "safe_tests": [
        {
          "test": "SAFE MLO Test - National Component with Uniform State Content",
          "date": "2024-03-02",
          "result": "Passed"
        }
      ],
      "background_checks": [
        {
          "status": "Completed",
          "status_date": "2024-02-01",
          "reason_closed": null,
          "method": "Electronic",
          "fingerprints_taken": "2024-01-30"
        }
      ],
      "fingerprints_expire": "2027-01-30",
      "credit_reports": ["2026-02-11"],
      "as_of": "2026-10-30"
    },
    "education": {
      "ce_hours": {
        "year": 2026,
        "hours_required": 9,
        "hours_completed": 7,
        "complete": false,
        "still_needed": [
          {
            "for": "TX",
            "hours": 2,
            "due_date": "2026-12-31"
          }
        ]
      },
      "pe_hours": {
        "federal": {
          "status": "Compliant",
          "complete": true,
          "hours_required": 20,
          "hours_completed": 24,
          "status_date": "2019-04-02"
        },
        "states": [
          {
            "state": "FL",
            "jurisdiction": null,
            "license_name": "Mortgage Loan Originator License",
            "status": "Pending",
            "complete": false,
            "hours_required": 2,
            "hours_completed": 0,
            "status_date": "2026-10-12"
          },
          {
            "state": "TX",
            "jurisdiction": "TX-SML",
            "license_name": "Mortgage Loan Originator",
            "status": "Compliant",
            "complete": true,
            "hours_required": 0,
            "hours_completed": 0,
            "status_date": "2019-05-01"
          }
        ]
      },
      "courses": [
        {
          "type": "PE",
          "state": "FL",
          "jurisdiction": null,
          "year": null,
          "title": "2 Hour Florida SAFE PE",
          "provider": "Knowledge Coop",
          "status": "in_progress",
          "percent_complete": 50,
          "due_date": "2026-11-07",
          "overdue": false,
          "completed_on": null
        },
        {
          "type": "CE",
          "state": "TX",
          "jurisdiction": "TX-SML",
          "year": 2026,
          "title": "2 Hour Texas SML SAFE CE",
          "provider": "Knowledge Coop",
          "status": "not_started",
          "percent_complete": 0,
          "due_date": "2026-12-31",
          "overdue": false,
          "completed_on": null
        }
      ]
    },
    "last_synced": {
      "nmls": "2026-10-30T17:17:28Z",
      "education": "2026-10-30T07:00:00Z"
    }
  },
  "meta": {
    "synced_at": "2026-10-30T17:17:28Z"
  }
}

List licenses, one row each

GET/loan-officers/licenses

Every loan officer license as a flat row that includes the officer, for a spreadsheet or BI tool. Not paginated: one call returns every row. Pass format=csv for a CSV file instead of JSON.

Key capability individuals

Query parameters

statestring

Only licenses in this state. Example: TX

can_originateboolean

true for licenses they can originate on today, false for the rest.

include_departedboolean

true to include people who left your company.

formatenum

csv for a CSV file.

One of json csv

Response

200
Every license row.
Fields
dataarray of LoanOfficerLicenseRowrequired
Each item
officer_idstring (uuid)required
officer_nmls_idstringrequirednullable
officer_namestringrequired
officer_emailstringrequirednullable
employment_statusstringrequirednullable
statestringrequired
license_namestringrequirednullable
license_numberstringrequirednullable
nmls_statusstringrequirednullable
can_originatebooleanrequired
temporary_authoritybooleanrequired
sponsorshipstringrequirednullable
sponsorship_nmls_statusstringrequirednullable
sponsored_sincestring (date)requirednullable
sponsorship_requested_onstring (date)requirednullable
open_itemsintegerrequired

How many items NMLS still wants for this license.

renewal_duestring (date)requirednullable
renewal_statusenumrequirednullable

As on LoanOfficerLicense.

One of submitted not_submitted failed unknown

Example submitted

last_synced_atstring (date-time)requirednullable

When Payna last updated this license.

metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404Loan officers are not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/loan-officers/licenses \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": [
    {
      "officer_id": "c1d2e3f4-0000-0000-0000-aabbccddeeff",
      "officer_nmls_id": "1234567",
      "officer_name": "Jane Example",
      "officer_email": "jane@examplemortgage.com",
      "employment_status": "active",
      "state": "TX",
      "license_name": "Texas-SML Mortgage Loan Originator License",
      "license_number": "1234567",
      "nmls_status": "Approved",
      "can_originate": true,
      "temporary_authority": false,
      "sponsorship": "Accepted",
      "sponsorship_nmls_status": "Accepted",
      "sponsored_since": "2026-09-10",
      "sponsorship_requested_on": "2026-09-02",
      "open_items": 0,
      "renewal_due": "2026-12-31",
      "renewal_status": "submitted",
      "last_synced_at": "2026-10-30T17:17:28Z"
    }
  ],
  "meta": {
    "total": 1376,
    "page": 1,
    "limit": 1376,
    "synced_at": "2026-10-30T17:17:28Z"
  }
}
officer_id,officer_nmls_id,officer_name,...

Webhooks

Payna posts to your endpoint when a loan officer is added or their record changes, so you do not have to poll. See the Webhooks guide for the payload and how to verify a signature.

List webhooks

GET/webhooks

The webhooks this key registered.

Key capability webhooks

Response

200
The webhooks.
Fields
dataarray of Webhookrequired
Each item
idstring (uuid)required

Example 5b0e6a52-7c1d-4b8e-9a51-0f1c2d3e4f50

urlstringrequired

Example https://hooks.examplemortgage.com/payna

eventsarray of enumsrequired

One of loan_officer.created loan_officer.updated

created_atstring (date-time)required
last_success_atstring (date-time)requirednullable

The last time your endpoint answered 2xx.

last_failure_atstring (date-time)requirednullable

The last time it did not.

Errors

401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/webhooks \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": [
    {
      "id": "5b0e6a52-7c1d-4b8e-9a51-0f1c2d3e4f50",
      "url": "https://hooks.examplemortgage.com/payna",
      "events": ["loan_officer.created", "loan_officer.updated"],
      "created_at": "2026-11-17T18:00:00Z",
      "last_success_at": "2026-11-17T18:05:12Z",
      "last_failure_at": null
    }
  ]
}

Register a webhook

POST/webhooks

Payna posts each event to url as JSON. The response includes secret once: store it, because every event is signed with it and Payna cannot show it again. A webhook belongs to the key that registered it, and stops when that key is revoked. Up to 5 per key.

Key capability webhooks and individuals

Body

urlstringrequired

An https URL on the public internet.

Example https://hooks.examplemortgage.com/payna

eventsarray of enums

The events to send. Every event when left out.

One of loan_officer.created loan_officer.updated

Response

201
The webhook, with its signing secret.
Fields
dataobjectrequired
Fields
idstring (uuid)required

Example 5b0e6a52-7c1d-4b8e-9a51-0f1c2d3e4f50

urlstringrequired

Example https://hooks.examplemortgage.com/payna

eventsarray of enumsrequired

One of loan_officer.created loan_officer.updated

created_atstring (date-time)required
last_success_atstring (date-time)requirednullable

The last time your endpoint answered 2xx.

last_failure_atstring (date-time)requirednullable

The last time it did not.

secretstringrequired

Shown once. Verify signatures with it.

Example whsec_dGhpcyBpcyBhbiBleGFtcGxlIHNlY3JldA==

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404Loan officers are not turned on for your account.
409This key already has a webhook for that URL, or already has 5.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl -X POST https://app.payna.com/api/v1/webhooks \
  -H "Authorization: Bearer $PAYNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.examplemortgage.com/payna"
  }'
201 Created
{
  "data": {
    "id": "5b0e6a52-7c1d-4b8e-9a51-0f1c2d3e4f50",
    "url": "https://hooks.examplemortgage.com/payna",
    "events": ["loan_officer.created", "loan_officer.updated"],
    "created_at": "2026-11-17T18:00:00Z",
    "last_success_at": null,
    "last_failure_at": null,
    "secret": "whsec_dGhpcyBpcyBhbiBleGFtcGxlIHNlY3JldA=="
  }
}

Delete a webhook

DELETE/webhooks/{id}

Payna stops sending to it at once, including retries already queued.

Key capability webhooks

Path parameters

idstring (uuid)required

The webhook's id.

Example 5b0e6a52-7c1d-4b8e-9a51-0f1c2d3e4f50

Response

204
Deleted.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404This key has no webhook with that id.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl -X DELETE https://app.payna.com/api/v1/webhooks/5b0e6a52-7c1d-4b8e-9a51-0f1c2d3e4f50 \
  -H "Authorization: Bearer $PAYNA_API_KEY"
204 No content

Send a test event

POST/webhooks/{id}/test

Posts a signed webhook.test event to the endpoint now and reports what it answered. Use it to check your signature verification. It is not retried.

Key capability webhooks

Path parameters

idstring (uuid)required

The webhook's id.

Example 5b0e6a52-7c1d-4b8e-9a51-0f1c2d3e4f50

Response

200
What your endpoint answered.
Fields
dataobjectrequired
Fields
deliveredbooleanrequired

true when it answered 2xx within 10 seconds.

statusintegerrequirednullable

The HTTP status it answered. Null when it did not answer.

Example 200

errorstringrequirednullable

Why it was not delivered.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404This key has no webhook with that id.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl -X POST https://app.payna.com/api/v1/webhooks/5b0e6a52-7c1d-4b8e-9a51-0f1c2d3e4f50/test \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": {
    "delivered": true,
    "status": 200,
    "error": null
  }
}

Renewals

This renewal season for your company and your loan officers: what is renewed, what is still owed, and what it costs.

Get the renewal season summary

GET/renewals

Returns the season in one object: totals, the company's own licenses, branch licenses, the officers' licenses, and each deadline, earliest first. A deadline is printed as CSBS prints it (12/31, which recurs every year), or as the license stores it (2027-02-28). due_date is the date it falls on this season.

The figures are the ones on the Renewals page, from each license's Current Renewal Status at NMLS. Reminders Payna sends are not counted.

When NMLS states no status. A holder NMLS states no renewal status for has status_known false and its counts null, never zero.

Needs the licenses capability and the Renewals feature.

Key capability licenses

Response

200
The season.
Fields
dataRenewalSummaryrequired

The renewal season for every holder and every deadline.

Fields
as_ofstring (date-time)required

When these figures were last updated.

status_knownobjectrequired

Whether NMLS states a renewal status for each holder. False means it states none, and that holder's counts are null.

Fields
companybooleanrequired
branchesbooleanrequired
loan_officersbooleanrequired
totalsobjectrequired

Counts are null while status_known is false for this holder.

Fields
licensesintegerrequired

Licenses to renew this season.

Example 105

submittedintegerrequirednullable

Licenses NMLS shows submitted.

Example 84

failedintegerrequirednullable

Licenses NMLS shows "Failed to renew". Included in not_submitted.

Example 1

not_submittedintegerrequirednullable

Licenses still to submit, failed ones included.

Example 21

percent_submittedintegerrequirednullable

Share submitted, rounded down, so it reads 100 only when every license is submitted.

Example 80

companyobjectrequired

Counts are null while status_known is false for this holder.

Fields
licensesintegerrequired

Licenses to renew this season.

Example 105

submittedintegerrequirednullable

Licenses NMLS shows submitted.

Example 84

failedintegerrequirednullable

Licenses NMLS shows "Failed to renew". Included in not_submitted.

Example 1

not_submittedintegerrequirednullable

Licenses still to submit, failed ones included.

Example 21

percent_submittedintegerrequirednullable

Share submitted, rounded down, so it reads 100 only when every license is submitted.

Example 80

branchesobjectrequired

Counts are null while status_known is false for this holder.

Fields
licensesintegerrequired

Licenses to renew this season.

Example 105

submittedintegerrequirednullable

Licenses NMLS shows submitted.

Example 84

failedintegerrequirednullable

Licenses NMLS shows "Failed to renew". Included in not_submitted.

Example 1

not_submittedintegerrequirednullable

Licenses still to submit, failed ones included.

Example 21

percent_submittedintegerrequirednullable

Share submitted, rounded down, so it reads 100 only when every license is submitted.

Example 80

branchesintegerrequired

Branches with a license to renew.

Example 14

branches_fully_submittedintegerrequirednullable

Branches with every license submitted.

Example 9

loan_officersobjectrequired

Counts are null while status_known is false for this holder.

Fields
licensesintegerrequired

Licenses to renew this season.

Example 105

submittedintegerrequirednullable

Licenses NMLS shows submitted.

Example 84

failedintegerrequirednullable

Licenses NMLS shows "Failed to renew". Included in not_submitted.

Example 1

not_submittedintegerrequirednullable

Licenses still to submit, failed ones included.

Example 21

percent_submittedintegerrequirednullable

Share submitted, rounded down, so it reads 100 only when every license is submitted.

Example 80

loan_officersintegerrequired

Officers with a license to renew.

Example 675

loan_officers_fully_submittedintegerrequirednullable

Officers with every license submitted.

Example 402

deadlinesarray of objectsrequired

Each deadline, earliest first, over every holder.

Each item
duestringrequirednullable

As CSBS prints it (MM/DD), or as the license stores it (YYYY-MM-DD). Null where neither states one.

Example 12/31

due_datestring (date)requirednullable

The date it falls on this season.

Example 2026-12-31

passedbooleanrequired

true once the deadline has gone.

statesarray of stringsrequired
licensesintegerrequired

Licenses to renew this season.

Example 105

submittedintegerrequirednullable

Licenses NMLS shows submitted.

Example 84

failedintegerrequirednullable

Licenses NMLS shows "Failed to renew". Included in not_submitted.

Example 1

not_submittedintegerrequirednullable

Licenses still to submit, failed ones included.

Example 21

percent_submittedintegerrequirednullable

Share submitted, rounded down, so it reads 100 only when every license is submitted.

Example 80

feesobjectrequired

State and NMLS processing fees, in dollars, whoever pays them.

Fields
companyobjectrequired
Fields
statenumberrequired

State fees, in dollars.

nmlsnumberrequired

NMLS processing fees, in dollars.

not_pricedintegerrequired

Licenses no CSBS fee chart row prices. Their state fees are unknown and not counted in state.

Example 0

branchesobjectrequired
Fields
statenumberrequired

State fees, in dollars.

nmlsnumberrequired

NMLS processing fees, in dollars.

not_pricedintegerrequired

Licenses no CSBS fee chart row prices. Their state fees are unknown and not counted in state.

Example 0

loan_officersobjectrequired
Fields
statenumberrequired

State fees, in dollars.

nmlsnumberrequired

NMLS processing fees, in dollars.

not_pricedintegerrequired

Licenses no CSBS fee chart row prices. Their state fees are unknown and not counted in state.

Example 0

metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404Renewals are not turned on for your account. Contact support@payna.com.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/renewals \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": {
    "as_of": "2026-11-16T19:30:00Z",
    "status_known": {
      "company": true,
      "branches": true,
      "loan_officers": true
    },
    "totals": {
      "licenses": 1250,
      "submitted": 1000,
      "failed": 3,
      "not_submitted": 250,
      "percent_submitted": 80
    },
    "company": {
      "licenses": 40,
      "submitted": 30,
      "failed": 0,
      "not_submitted": 10,
      "percent_submitted": 75
    },
    "branches": {
      "licenses": 110,
      "submitted": 90,
      "failed": 1,
      "not_submitted": 20,
      "percent_submitted": 81,
      "branches": 12,
      "branches_fully_submitted": 8
    },
    "loan_officers": {
      "licenses": 1100,
      "submitted": 880,
      "failed": 2,
      "not_submitted": 220,
      "percent_submitted": 80,
      "loan_officers": 150,
      "loan_officers_fully_submitted": 96
    },
    "deadlines": [
      {
        "due": "11/30",
        "due_date": "2026-11-30",
        "passed": false,
        "states": ["NM"],
        "licenses": 20,
        "submitted": 20,
        "failed": 0,
        "not_submitted": 0,
        "percent_submitted": 100
      },
      {
        "due": "12/31",
        "due_date": "2026-12-31",
        "passed": false,
        "states": ["AZ", "FL", "TX"],
        "licenses": 900,
        "submitted": 720,
        "failed": 2,
        "not_submitted": 180,
        "percent_submitted": 80
      }
    ],
    "fees": {
      "company": {
        "state": 24000,
        "nmls": 4800,
        "not_priced": 0
      },
      "branches": {
        "state": 30000,
        "nmls": 2750,
        "not_priced": 0
      },
      "loan_officers": {
        "state": 165000,
        "nmls": 38500,
        "not_priced": 0
      }
    }
  },
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 1,
    "synced_at": "2026-11-16T19:30:00Z"
  }
}

List loan officer renewals

GET/renewals/loan-officers

Returns one row per officer with a license to renew, soonest deadline still to submit first. Not paginated: one call returns every officer. Officers who left your company are not included.

Add status=outstanding for the list to chase. Pass format=csv for a CSV file. license_list is JSON only.

While NMLS states no renewal status for your officers, meta.status_known is false and every count is null rather than zero.

This list names people, so it needs the individuals capability as well as licenses, and both the Loan officers and Renewals features.

Key capability individuals and licenses

Query parameters

statusenum

outstanding is everyone with something left: not_submitted, partially_submitted and failed together.

One of all outstanding not_submitted partially_submitted failed submitted

statestring

Only licenses in this state. Each officer's counts are then that state's alone.

include_licensesboolean

true to add license_list, each license with its own status.

formatenum

csv for a CSV file.

One of json csv

Response

200
Every officer with a license to renew.
Fields
dataarray of LoanOfficerRenewalrequired
Each item
idstring (uuid)required

The same id as on GET /loan-officers.

nmls_idstringrequirednullable

Example 1234567

namestringrequired

Example Jane Example

statusenumrequired

submitted when every license is, partially_submitted when some are, not_submitted when none are, failed when NMLS shows any "Failed to renew". unknown while NMLS states no status.

One of submitted partially_submitted not_submitted failed unknown

licensesintegerrequired

Licenses to renew this season.

Example 105

submittedintegerrequirednullable

Licenses NMLS shows submitted.

Example 84

failedintegerrequirednullable

Licenses NMLS shows "Failed to renew". Included in not_submitted.

Example 1

not_submittedintegerrequirednullable

Licenses still to submit, failed ones included.

Example 21

percent_submittedintegerrequirednullable

Share submitted, rounded down, so it reads 100 only when every license is submitted.

Example 80

next_due_datestring (date)requirednullable

The soonest deadline among licenses not yet submitted. Null when nothing is left.

Example 2026-12-01

license_listarray of objects

With include_licenses=true only.

Each item
statestringrequired

Example TX

licensestringrequired
duestringrequirednullable

Example 12/31

due_datestring (date)requirednullable
renewal_statusenumrequirednullable

NMLS's Current Renewal Status for this license this season: submitted (NMLS shows the renewal requested or approved), not_submitted, failed (NMLS shows "Failed to renew"), or unknown (a word NMLS uses that Payna does not know yet; count it as not submitted). Null for a license NMLS holds no record of, and for every license while NMLS states no renewal status for your company at all.

One of submitted not_submitted failed unknown

Example submitted

metaobjectrequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

status_knownbooleanrequired

False while NMLS states no renewal status for your officers. Every count is then null.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404Loan officers or Renewals are not turned on for your account. Contact support@payna.com.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/renewals/loan-officers \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": [
    {
      "id": "c1d2e3f4-0000-0000-0000-aabbccddeeff",
      "nmls_id": "1234567",
      "name": "Jane Example",
      "status": "partially_submitted",
      "licenses": 3,
      "submitted": 1,
      "failed": 0,
      "not_submitted": 2,
      "percent_submitted": 33,
      "next_due_date": "2026-12-01",
      "license_list": [
        {
          "state": "CA",
          "license": "California-DFPI Mortgage Loan Originator License",
          "due": "12/01",
          "due_date": "2026-12-01",
          "renewal_status": "not_submitted"
        },
        {
          "state": "TX",
          "license": "Texas-SML Mortgage Loan Originator License",
          "due": "12/31",
          "due_date": "2026-12-31",
          "renewal_status": "submitted"
        },
        {
          "state": "WA",
          "license": "Washington Mortgage Loan Originator License",
          "due": "12/15",
          "due_date": "2026-12-15",
          "renewal_status": "not_submitted"
        }
      ]
    }
  ],
  "meta": {
    "total": 54,
    "page": 1,
    "limit": 54,
    "synced_at": "2026-11-16T19:30:00Z",
    "status_known": true
  }
}
id,nmls_id,name,status,licenses,submitted,failed,not_submitted,percent_submitted,next_due_date
c1d2e3f4-0000-0000-0000-aabbccddeeff,1234567,Jane Example,partially_submitted,3,1,0,2,33,2026-12-01

NMLS Verification

Check the NMLS license record of a broker company or a loan officer, whether or not they work for you. A check runs in the background, so you create it and then read it back.

Start a license verification

POST/nmls/verifications

Starts a license check for one loan officer or one broker/TPO company. Payna answers 202 at once and the check finishes in the background, usually in 10 to 40 seconds. Poll GET /nmls/verifications/{id} for the answer.

Send exactly one of nmls_id or name. A name never resolves by itself. It returns needs_identification with candidates, and you post the chosen nmls_id to /nmls/verifications/{id}/select.

The answer is the license record as NMLS states it. There is no pass or fail and no sponsorship verdict, so your system owns that decision. Every check is fresh and billed as one verification. The key needs the nmls_verification capability, which Payna grants per key. Write to support@payna.com for it.

**Send an Idempotency-Key header** with a unique value per verification. Replaying one returns the original verification instead of checking again.

  • Loan officer by NMLS ID: {"nmls_id": "2287431", "loan_id": "loan-456"}
  • Broker/TPO company by NMLS ID: {"subject_type": "company", "nmls_id": "1000001", "loan_id": "loan-456"}
  • By name, narrowed by state: {"name": "Jane Example", "state": "CA"}

Key capability nmls_verification

Headers

Idempotency-Keystringrequired

A unique value per verification. Replaying one returns the original verification instead of checking again.

Example loan-456-check-1

Body

subject_typeenum

The subject of this verification: individual (a loan officer) or company (a broker/TPO company). Defaults to individual.

One of individual company

nmls_idstring

The person's or company's NMLS ID. NMLS numbers people and companies separately, so the same digits name a different entity under each subject_type.

Example 2287431

namestring

A name to search for. It returns candidates, never a record.

Example Jane Example

statestring

Narrows a name search. Not allowed with nmls_id.

Example CA

external_account_idstring

Your own ID for this account or broker. Payna echoes it back and stores it nowhere else.

loan_idstring

Your own loan reference. Payna echoes it back and stores it nowhere else. Use it to match a broker check and a loan officer check for the same loan.

Response

202
Accepted. The check runs after this response. The Location header names where to poll for the answer.
Fields
verification_idstringrequired

Example ver_7b1f3c2e-0000-4000-8000-aabbccddeeff

statusenumrequired

The verification's current status. A replayed Idempotency-Key answers with the original's.

One of pending reading complete needs_identification not_found failed

Errors

400No Idempotency-Key header, both or neither of nmls_id and name, or an unknown subject_type.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404The nmls_verification API is not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
503Temporarily unable to verify account entitlements. Please retry.
curl -X POST https://app.payna.com/api/v1/nmls/verifications \
  -H "Authorization: Bearer $PAYNA_API_KEY" \
  -H "Idempotency-Key: loan-456-check-1" \
  -H "Content-Type: application/json" \
  -d '{
    "nmls_id": "2287431",
    "loan_id": "loan-456"
  }'
202 Accepted
{
  "verification_id": "ver_7b1f3c2e-0000-4000-8000-aabbccddeeff",
  "status": "pending"
}

Poll a verification

GET/nmls/verifications/{id}

Returns the stored answer. It never starts or repeats a check, so polling costs nothing extra.

Key capability nmls_verification

Path parameters

idstringrequired

The verification_id that POST /nmls/verifications returned.

Example ver_7b1f3c2e-0000-4000-8000-aabbccddeeff

Response

200
The verification, in whatever status it is in now.
Fields
verification_idstringrequired

Example ver_7b1f3c2e-0000-4000-8000-aabbccddeeff

statusenumrequired

One of pending reading complete needs_identification not_found failed

subject_typeenumrequired

One of individual company

external_account_idstringrequirednullable
loan_idstringrequirednullable
requestedobjectrequired
Fields
nmls_idstring
namestring
statestring
selected_nmls_idstring

Present once a name search is resolved with /nmls/verifications/{id}/select.

retrieved_atstring (date-time)requirednullable
sourceobjectrequirednullable
Fields
providerstringrequired
urlstringrequired
recordVerificationRecord or VerificationCompanyRecord

Present only when status is complete. An individual record when subject_type is individual, a company record when it is company.

Fields
nmls_idstring
namestring
phonestringnullable
faxstringnullable
other_namesarray of strings
authorized_to_representstringnullable

The sponsor line as NMLS states it, word for word. It is not a sponsorship statement by Payna. Null means NMLS lists none, which some state setups do even when the officer is sponsored.

Example Example Mortgage Co. (1000001)

licensesarray of VerificationLicense
Each item
nmls_license_idstringnullable
regulatorstring
state_codestringnullable

Example CA

license_namestring

Example CA-DFPI CRMLA Mortgage Loan Originator License

license_numberstringnullable
statusstringnullable

Example Approved

status_datestring (date)nullable
original_issue_datestring (date)nullable
renewed_through_yearintegernullable

Example 2026

authorizedbooleannullable

Authorized to conduct business under this license, per NMLS.

office_locationsarray of VerificationOfficeLocation
Each item
company_namestring
nmls_idstring
location_typestring
streetstringnullable
citystringnullable
state_codestringnullable
postal_codestringnullable
start_datestringnullable
employmentarray of VerificationEmployment
Each item
from_datestringnullable

Verbatim from NMLS, at month precision, like "10/2014".

to_datestringnullable

"Present" for a current job, verbatim from NMLS.

employerstring
positionstringnullable
citystringnullable
state_codestringnullable
postal_codestringnullable
financial_servicesbooleannullable
regulatory_actionsarray of VerificationRegulatoryAction
Each item
regulatorstring
state_codestringnullable
action_typestring
date_of_actionstring (date)nullable
multi_state_action_idstringnullable
docket_numberstringnullable
candidatesarray of VerificationCandidate or VerificationCompanyCandidates

Present only when status is needs_identification.

Each item
nmls_idstring
namestring
citystring
state_codestring
errorstring

Present only when status is failed. It describes why the check failed and says nothing about the subject.

created_atstring (date-time)required

Errors

400Invalid verification ID.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404No verification with that ID belongs to your company, or the nmls_verification API is not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
503Temporarily unable to verify account entitlements. Please retry.
curl https://app.payna.com/api/v1/nmls/verifications/ver_7b1f3c2e-0000-4000-8000-aabbccddeeff \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK

Resolve a name search to one candidate

POST/nmls/verifications/{id}/select

Only valid on a verification whose status is needs_identification. Picks one of the candidates it returned and runs the check for it. The verification keeps its ID, loan_id and external_account_id, and requested still shows the name that was asked.

Key capability nmls_verification

Path parameters

idstringrequired

The verification_id that POST /nmls/verifications returned.

Example ver_7b1f3c2e-0000-4000-8000-aabbccddeeff

Body

nmls_idstringrequired

Must be one of the candidates this verification returned.

Example 2287431

Response

202
Accepted. The check runs again after this response.
Fields
verification_idstringrequired

Example ver_7b1f3c2e-0000-4000-8000-aabbccddeeff

statusenumrequired

One of pending reading complete needs_identification not_found failed

subject_typeenumrequired

One of individual company

external_account_idstringrequirednullable
loan_idstringrequirednullable
requestedobjectrequired
Fields
nmls_idstring
namestring
statestring
selected_nmls_idstring

Present once a name search is resolved with /nmls/verifications/{id}/select.

retrieved_atstring (date-time)requirednullable
sourceobjectrequirednullable
Fields
providerstringrequired
urlstringrequired
recordVerificationRecord or VerificationCompanyRecord

Present only when status is complete. An individual record when subject_type is individual, a company record when it is company.

Fields
nmls_idstring
namestring
phonestringnullable
faxstringnullable
other_namesarray of strings
authorized_to_representstringnullable

The sponsor line as NMLS states it, word for word. It is not a sponsorship statement by Payna. Null means NMLS lists none, which some state setups do even when the officer is sponsored.

Example Example Mortgage Co. (1000001)

licensesarray of VerificationLicense
Each item
nmls_license_idstringnullable
regulatorstring
state_codestringnullable

Example CA

license_namestring

Example CA-DFPI CRMLA Mortgage Loan Originator License

license_numberstringnullable
statusstringnullable

Example Approved

status_datestring (date)nullable
original_issue_datestring (date)nullable
renewed_through_yearintegernullable

Example 2026

authorizedbooleannullable

Authorized to conduct business under this license, per NMLS.

office_locationsarray of VerificationOfficeLocation
Each item
company_namestring
nmls_idstring
location_typestring
streetstringnullable
citystringnullable
state_codestringnullable
postal_codestringnullable
start_datestringnullable
employmentarray of VerificationEmployment
Each item
from_datestringnullable

Verbatim from NMLS, at month precision, like "10/2014".

to_datestringnullable

"Present" for a current job, verbatim from NMLS.

employerstring
positionstringnullable
citystringnullable
state_codestringnullable
postal_codestringnullable
financial_servicesbooleannullable
regulatory_actionsarray of VerificationRegulatoryAction
Each item
regulatorstring
state_codestringnullable
action_typestring
date_of_actionstring (date)nullable
multi_state_action_idstringnullable
docket_numberstringnullable
candidatesarray of VerificationCandidate or VerificationCompanyCandidates

Present only when status is needs_identification.

Each item
nmls_idstring
namestring
citystring
state_codestring
errorstring

Present only when status is failed. It describes why the check failed and says nothing about the subject.

created_atstring (date-time)required

Errors

400Invalid verification ID, or a missing or invalid nmls_id.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404No verification with that ID belongs to your company, or the nmls_verification API is not turned on for your account.
409The verification is not awaiting a choice, or that ID is not one of its candidates.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
503Temporarily unable to verify account entitlements. Please retry.
curl -X POST https://app.payna.com/api/v1/nmls/verifications/ver_7b1f3c2e-0000-4000-8000-aabbccddeeff/select \
  -H "Authorization: Bearer $PAYNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nmls_id": "2287431"
  }'
202 Accepted

Licenses

Your company's own licenses, in every state and for every activity it is licensed for. For the licenses your people hold, use Loan officers (mortgage) or Individuals (any vertical).

List all licenses

GET/licenses

Returns a paginated list of all license records for your company. Use the state, status, license_type, and verified query parameters to filter results. Results are ordered by state code ascending.

Key capability licenses

Query parameters

statestring

Comma-separated 2-letter state codes (or ISO 3166-1 alpha-3 country codes). Example: CA,NY,TX

statusstring

Comma-separated status values. Example: active,pending

license_typestring

Filter by license type (partial match). Example: Money Transmission

verifiedboolean

Filter by verification status. true or false.

pageinteger

Page number. Starts at 1.

limitinteger

Results per page. Max 200.

Response

200
A page of licenses.
Fields
dataarray of Licenserequired
Each item
idstring (uuid)required

Unique license record ID.

state_codestringrequired

Two-letter US state code, or an ISO 3166-1 alpha-3 country code for a license outside the US.

Example CA

license_typestringrequired

Example California - DFPI Debt Collection License

activity_typestringrequired

What the license authorizes. Known values: mortgage, insurance, lending, consumer_lending, business_lending, debt_collection, money_transmission, loan_servicing, student_loans, third_party_administration, other. Not a closed set. It grows as Payna adds verticals, so treat an unknown value as a value, not an error.

Example insurance

license_numberstringrequirednullable

Example CCA-2671499

nmls_idstringrequirednullable

Example 2671499

regulatorstringrequirednullable

Example DFPI

statusenumrequired

Core license status (5-value model). For accurate display, prefer status_detail.category and status_detail.code: the top-level status can say "applying" for an abandoned application or "pending" for a license with a withdrawal requested, and status_detail resolves those correctly.

One of active deficient pending applying not_licensed

sub_statusstringrequirednullable

Detailed sub-status within the core status category. Known values: expired, suspended, nmls_deficiency, inactive (licence granted but not usable: no sponsorship / not authorised), no_license_needed, in_state_office_required, withdrawn, rejected (the regulator rejected the request), denied (the regulator denied the licence), surety_bond_only (bond-only states: compliance is a surety bond on file, no license exists).

Example withdrawn

raw_statusstringrequirednullable

Verbatim status string from the regulator.

Example Approved-Active

issued_datestring (date)requirednullable

Example 2023-06-15

renewal_datestring (date)requirednullable

Deadline to file the renewal: the single "act-by" date for the license. NMLS licenses run on a renewal cycle (not a hard expiry). State-portal licenses may use the same field.

Example 2026-12-31

days_until_renewalintegerrequirednullable

Days from today until the renewal date. Negative means the renewal date has passed without a recorded renewal.

Example 168

renewal_statusenumrequirednullable

NMLS's Current Renewal Status for this license this season: submitted (NMLS shows the renewal requested or approved), not_submitted, failed (NMLS shows "Failed to renew"), or unknown (a word NMLS uses that Payna does not know yet; count it as not submitted). Null for a license NMLS holds no record of, and for every license while NMLS states no renewal status for your company at all.

One of submitted not_submitted failed unknown

Example submitted

verifiedbooleanrequired

Whether Payna has verified this license record with the regulator.

verified_atstring (date-time)requirednullable
jurisdiction_levelstringrequirednullable

Example state

filing_methodstringrequirednullable

Example nmls

updated_atstring (date-time)required

Last time this record was updated in Payna.

status_detailStatusDetailrequired

Derived, machine-stable descriptor of the license status. Render per-state nuance off code and category instead of parsing raw_status. Always present and well-formed.

Fields
codeenumrequired

Stable machine slug, safe to branch on.

One of licensed conditional_approval surety_bond_only deficient revoked suspended terminated_for_cause expired inactive application application_deficient application_incomplete under_review pending withdrawal_requested application_abandoned voluntary_withdrawal withdrawn surrendered terminated rejected denied no_license_needed in_state_office_required not_licensed unknown

Example voluntary_withdrawal

labelstringrequired

Human-readable label.

Example Voluntary withdrawal

categoryenumrequired

Color bucket: active is green, in_progress is blue or amber, deficient is red, exited and not_pursued are gray, needs_review is amber.

One of active in_progress deficient exited not_pursued needs_review

intentionalbooleanrequired

True when the unlicensed posture is deliberate (voluntary withdrawal, no license needed, in-state office required, surety bond only), so not a problem.

is_nmlsbooleanrequired

False for state-portal (non-NMLS) jurisdictions such as TX and DE debt collection.

portalobjectrequirednullable

State portal for non-NMLS jurisdictions. Null for NMLS, or when there is no online portal.

Fields
namestringrequired

Example Delaware One Stop

urlstringrequirednullable

Example https://onestop.delaware.gov/Account_SignIn

typestringrequirednullable
source_textstringrequirednullable

Passthrough of the underlying raw_status.

Example Withdrawn - Voluntary Without Licensure

metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter is invalid. INVALID_STATE_CODE when a state code is neither a US state nor an ISO 3166-1 alpha-3 country code.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404The 'licenses' API is not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
503Payna could not check what your account has turned on. Retry.
curl https://app.payna.com/api/v1/licenses \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "state_code": "CA",
      "license_type": "California - DFPI Debt Collection License",
      "activity_type": "debt_collection",
      "license_number": "11622-99",
      "nmls_id": "2671499",
      "regulator": "DFPI",
      "status": "active",
      "sub_status": null,
      "raw_status": "Approved",
      "issued_date": "2025-07-17",
      "renewal_date": "2026-12-31",
      "days_until_renewal": 168,
      "renewal_status": "submitted",
      "verified": false,
      "verified_at": null,
      "jurisdiction_level": null,
      "filing_method": null,
      "updated_at": "2026-07-16T18:36:49Z",
      "status_detail": {
        "code": "licensed",
        "label": "Licensed",
        "category": "active",
        "intentional": false,
        "is_nmls": true,
        "portal": null,
        "source_text": "Approved"
      }
    }
  ],
  "meta": {
    "total": 37,
    "page": 1,
    "limit": 50,
    "synced_at": "2026-07-16T18:36:49Z"
  }
}

Get license summary

GET/licenses/summary

Returns aggregate counts for all licenses. Lightweight endpoint suitable for health checks, dashboards, and startup checks. Use renewing_30_days to drive collection-blocking logic.

Key capability licenses

Response

200
Counts over every license your company holds.
Fields
dataLicenseSummaryrequired

Counts over every license your company holds.

Fields
totalintegerrequired

Example 37

by_statusobjectrequired

Count per core status.

renewing_soonintegerrequired

Active licenses with a renewal date within 90 days.

Example 3

renewing_30_daysintegerrequired

Active licenses with a renewal date within 30 days.

Example 1

expiredintegerrequired

Licenses with status deficient and sub_status expired.

Example 0

verifiedintegerrequired

Licenses that Payna has verified with the regulator.

Example 0

metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404The 'licenses' API is not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
503Payna could not check what your account has turned on. Retry.
curl https://app.payna.com/api/v1/licenses/summary \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": {
    "total": 37,
    "by_status": {
      "active": 13,
      "deficient": 2,
      "pending": 3,
      "applying": 10,
      "not_licensed": 9
    },
    "renewing_soon": 3,
    "renewing_30_days": 1,
    "expired": 0,
    "verified": 0
  },
  "meta": {
    "total": 37,
    "page": 1,
    "limit": 37,
    "synced_at": null
  }
}

Get license for a specific state

GET/licenses/{state}

Returns a single license record for a US state. A state can hold more than one license (different activity types, or state-level plus city-level entries). When that happens this endpoint returns the most recently updated one and reports the count in meta.total. Use GET /licenses?state=XX to retrieve all of them. State codes are case-insensitive.

Key capability licenses

Path parameters

statestringrequired

2-letter US state code (or ISO 3166-1 alpha-3 country code). Example: CA

Response

200
License found.
Fields
dataLicenserequired

One license your company holds.

Fields
idstring (uuid)required

Unique license record ID.

state_codestringrequired

Two-letter US state code, or an ISO 3166-1 alpha-3 country code for a license outside the US.

Example CA

license_typestringrequired

Example California - DFPI Debt Collection License

activity_typestringrequired

What the license authorizes. Known values: mortgage, insurance, lending, consumer_lending, business_lending, debt_collection, money_transmission, loan_servicing, student_loans, third_party_administration, other. Not a closed set. It grows as Payna adds verticals, so treat an unknown value as a value, not an error.

Example insurance

license_numberstringrequirednullable

Example CCA-2671499

nmls_idstringrequirednullable

Example 2671499

regulatorstringrequirednullable

Example DFPI

statusenumrequired

Core license status (5-value model). For accurate display, prefer status_detail.category and status_detail.code: the top-level status can say "applying" for an abandoned application or "pending" for a license with a withdrawal requested, and status_detail resolves those correctly.

One of active deficient pending applying not_licensed

sub_statusstringrequirednullable

Detailed sub-status within the core status category. Known values: expired, suspended, nmls_deficiency, inactive (licence granted but not usable: no sponsorship / not authorised), no_license_needed, in_state_office_required, withdrawn, rejected (the regulator rejected the request), denied (the regulator denied the licence), surety_bond_only (bond-only states: compliance is a surety bond on file, no license exists).

Example withdrawn

raw_statusstringrequirednullable

Verbatim status string from the regulator.

Example Approved-Active

issued_datestring (date)requirednullable

Example 2023-06-15

renewal_datestring (date)requirednullable

Deadline to file the renewal: the single "act-by" date for the license. NMLS licenses run on a renewal cycle (not a hard expiry). State-portal licenses may use the same field.

Example 2026-12-31

days_until_renewalintegerrequirednullable

Days from today until the renewal date. Negative means the renewal date has passed without a recorded renewal.

Example 168

renewal_statusenumrequirednullable

NMLS's Current Renewal Status for this license this season: submitted (NMLS shows the renewal requested or approved), not_submitted, failed (NMLS shows "Failed to renew"), or unknown (a word NMLS uses that Payna does not know yet; count it as not submitted). Null for a license NMLS holds no record of, and for every license while NMLS states no renewal status for your company at all.

One of submitted not_submitted failed unknown

Example submitted

verifiedbooleanrequired

Whether Payna has verified this license record with the regulator.

verified_atstring (date-time)requirednullable
jurisdiction_levelstringrequirednullable

Example state

filing_methodstringrequirednullable

Example nmls

updated_atstring (date-time)required

Last time this record was updated in Payna.

status_detailStatusDetailrequired

Derived, machine-stable descriptor of the license status. Render per-state nuance off code and category instead of parsing raw_status. Always present and well-formed.

Fields
codeenumrequired

Stable machine slug, safe to branch on.

One of licensed conditional_approval surety_bond_only deficient revoked suspended terminated_for_cause expired inactive application application_deficient application_incomplete under_review pending withdrawal_requested application_abandoned voluntary_withdrawal withdrawn surrendered terminated rejected denied no_license_needed in_state_office_required not_licensed unknown

Example voluntary_withdrawal

labelstringrequired

Human-readable label.

Example Voluntary withdrawal

categoryenumrequired

Color bucket: active is green, in_progress is blue or amber, deficient is red, exited and not_pursued are gray, needs_review is amber.

One of active in_progress deficient exited not_pursued needs_review

intentionalbooleanrequired

True when the unlicensed posture is deliberate (voluntary withdrawal, no license needed, in-state office required, surety bond only), so not a problem.

is_nmlsbooleanrequired

False for state-portal (non-NMLS) jurisdictions such as TX and DE debt collection.

portalobjectrequirednullable

State portal for non-NMLS jurisdictions. Null for NMLS, or when there is no online portal.

Fields
namestringrequired

Example Delaware One Stop

urlstringrequirednullable

Example https://onestop.delaware.gov/Account_SignIn

typestringrequirednullable
source_textstringrequirednullable

Passthrough of the underlying raw_status.

Example Withdrawn - Voluntary Without Licensure

metaobjectrequired
Fields
totalintegerrequired

Number of licenses held in the state. More than 1 means more are available from the list endpoint.

Example 1

synced_atstring (date-time)required

When this license was last updated in Payna.

Errors

400INVALID_STATE_CODE: the code is neither a US state nor an ISO 3166-1 alpha-3 country code.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404No license record for this state, or the licenses API is not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
503Payna could not check what your account has turned on. Retry.
curl https://app.payna.com/api/v1/licenses/{state} \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "state_code": "CA",
    "license_type": "California - DFPI Debt Collection License",
    "activity_type": "debt_collection",
    "license_number": "11622-99",
    "nmls_id": "2671499",
    "regulator": "DFPI",
    "status": "active",
    "sub_status": null,
    "raw_status": "Approved",
    "issued_date": "2025-07-17",
    "renewal_date": "2026-12-31",
    "days_until_renewal": 168,
    "renewal_status": "submitted",
    "verified": false,
    "verified_at": null,
    "jurisdiction_level": null,
    "filing_method": null,
    "updated_at": "2026-07-16T18:36:49Z",
    "status_detail": {
      "code": "licensed",
      "label": "Licensed",
      "category": "active",
      "intentional": false,
      "is_nmls": true,
      "portal": null,
      "source_text": "Approved"
    }
  },
  "meta": {
    "total": 1,
    "synced_at": "2026-07-16T18:36:49Z"
  }
}

Individuals

Licensed people at your company in any vertical, one call per person. For mortgage loan officers, the Loan officers endpoints return the same facts in one call.

List regulated individuals

GET/individuals

Returns a paginated list of every licensed person at your company, in any vertical. Use ?type=mlo for mortgage loan officers, ?type=adjuster for insurance producers, or omit type to list everyone regardless of vertical. Filter further by employment_status to surface only active or terminated individuals. People who have left your company are listed only when you ask for them with employment_status=terminated.

Key capability individuals

Query parameters

typestring

Vertical filter. mlo for a mortgage loan officer, adjuster for an insurance producer (the stored slug; Payna labels them Producers). Omit to return all individual types.

employment_statusenum

Filter by employment/sponsorship status.

One of active inactive terminated pending

pageinteger

Page number. Starts at 1.

limitinteger

Results per page. Max 200.

Response

200
Paginated list of individuals.
Fields
dataarray of Individualrequired
Each item
individual_idstring (uuid)required

Payna internal ID for this person. Use it in every sub-resource endpoint.

individual_typestringrequired

Regulated vertical: mlo (a mortgage loan officer, licensed through NMLS), adjuster (an insurance producer, licensed through the state insurance departments), or any future type. adjuster is the stored slug and it means Producer. Not a closed set.

Example mlo

full_namestringrequired

Example Jane Smith

work_emailstring (email)requirednullable

Example jane@company.com

nmls_idstringrequirednullable

NMLS individual identifier. Set for a loan officer. Always null for an insurance producer, whose identifier is an NPN: NMLS holds no record of them.

Example 1234567

employment_statusenumrequirednullable

Employment status at this company, and for a loan officer the sponsorship status too. An individual can be active at one company and terminated at another.

One of active inactive terminated pending

company_idstring (uuid)required
updated_atstring (date-time)required

When Payna last updated this person's record, or added them if it has not been updated yet.

metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404The 'individuals' API is not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
503Payna could not check what your account has turned on. Retry.
curl https://app.payna.com/api/v1/individuals \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": [
    {
      "individual_id": "c1d2e3f4-0000-0000-0000-aabbccddeeff",
      "individual_type": "mlo",
      "full_name": "Jane Smith",
      "work_email": "jane@company.com",
      "nmls_id": "1234567",
      "employment_status": "active",
      "company_id": "f0a1b2c3-0000-0000-0000-112233445566",
      "updated_at": "2026-07-17T10:00:00Z"
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "limit": 50,
    "synced_at": "2026-07-17T10:00:00Z"
  }
}

Get individual's licenses

GET/individuals/{id}/licenses

Returns all state licenses held by a regulated individual, one row per state license. For a mortgage loan officer this is their NMLS individual license record per state. For an insurance producer it comes from NIPR and the state insurance departments, and source says which. A producer's lines of authority, resident-versus-non-resident standing and carrier appointments are not in this shape: those are Producers.

Key capability individuals

Path parameters

idstring (uuid)required

Individual ID from GET /individuals.

Query parameters

pageinteger

Page number. Starts at 1.

limitinteger

Results per page. Max 200.

Response

200
List of licenses.
Fields
dataarray of IndividualLicenserequired
Each item
idstring (uuid)required
statestringrequired

2-letter US state code, or US for federal or national registrations.

Example CA

license_typestringrequired

The license name the regulator uses, verbatim: "Mortgage Loan Originator" for a loan officer, "Resident Insurance Producer" for a producer. Regulators word the same license differently, so never parse it.

Example Mortgage Loan Originator

statusenumrequired

Core license status (5-value model): the same vocabulary as company licenses, in every vertical.

One of active deficient pending applying not_licensed

sub_statusstringrequirednullable

Detailed sub-status within the core status category. Known values: expired, suspended, nmls_deficiency, inactive (licence granted but not usable: no sponsorship / not authorised), no_license_needed, in_state_office_required, withdrawn, rejected (the regulator rejected the request), denied (the regulator denied the licence), surety_bond_only (bond-only states: compliance is a surety bond on file, no license exists).

Example inactive

license_numberstringrequirednullable

Example MLO-12345

effective_datestring (date)requirednullable

Date the license was issued or became effective.

renewal_datestring (date)requirednullable

Date by which the license must be renewed. Null in a state whose licenses do not expire.

sourcestringrequired

Which registry this record came from: nmls for a loan officer, nipr or state_doi for an insurance producer, manual when somebody at your company entered it. Not a closed set.

Example nmls

updated_atstring (date-time)required
metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404Individual not found, or the individuals API is not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
503Payna could not check what your account has turned on. Retry.
curl https://app.payna.com/api/v1/individuals/{id}/licenses \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK

Get outstanding license conditions

GET/individuals/{id}/license-conditions

Returns open conditions and deficiencies on an individual's licenses: the items blocking transfers, causing delays, or requiring action before a state can go active. Filter by ?status=open to see only unresolved items.

Every condition Payna records today comes from NMLS or from somebody at your company, which is what source says. An insurance producer therefore has none here yet, and an empty list is not a statement that their departments have raised nothing.

Key capability individuals

Path parameters

idstring (uuid)required

Individual ID from GET /individuals.

Query parameters

statusenum

Filter by condition status.

One of open in_progress submitted cleared

pageinteger

Page number. Starts at 1.

limitinteger

Results per page. Max 200.

Response

200
List of license conditions.
Fields
dataarray of LicenseConditionrequired
Each item
item_idstring (uuid)required

Unique condition ID.

individual_idstring (uuid)required
statestringrequirednullable

Example TX

condition_typestringrequirednullable

Type of condition (e.g. education, disclosure, background_check). Null when not yet classified.

Example education

descriptionstringrequired

Full condition text from the regulator.

action_requiredstringrequired

Short title describing what needs to happen.

statusenumrequired

One of open in_progress submitted cleared

due_datestring (date)requirednullable
sourceenumrequired

How this condition was recorded.

One of nmls_sync manual

first_seen_atstring (date-time)requirednullable
updated_atstring (date-time)required
metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404Individual not found, or the individuals API is not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
503Payna could not check what your account has turned on. Retry.
curl https://app.payna.com/api/v1/individuals/{id}/license-conditions \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK

Get continuing education status

GET/individuals/{id}/ce-status

Returns CE tracking data for each state license where CE is recorded. One record per state. Use remaining_hours and deadline to drive reminder logic. A license appears once Payna holds any of its CE status, deadline or required hours. Active licenses with none of them are left out of data and counted in meta.active_licenses_without_ce_tracking.

Hours only, in every vertical. An insurance producer also owes an ethics component per state, which this shape does not carry: use GET /producers/{id}/ce-status for that.

Key capability individuals

Path parameters

idstring (uuid)required

Individual ID from GET /individuals.

Query parameters

pageinteger

Page number. Starts at 1.

limitinteger

Results per page. Max 200.

Response

200
CE records per state license.
Fields
dataarray of CeStatusrequired
Each item
statestringrequired

Example CA

license_typestringrequired

The license these hours are owed for, as the regulator names it.

Example Mortgage Loan Originator

yearintegerrequirednullable

CE cycle year, derived from the deadline date. Meaningful on a calendar-year cycle. Read deadline where the cycle is not a calendar year.

Example 2026

required_hoursnumberrequirednullable

Example 8

completed_hoursnumberrequirednullable

Example 5.5

remaining_hoursnumberrequirednullable

Computed: max(0, required - completed). Null when required or completed is unknown.

Example 2.5

statusenumrequirednullable

compliant: CE complete. pending: in progress. deficient: overdue.

One of compliant pending deficient

deadlinestring (date)requirednullable

Date by which CE must be completed for the current cycle.

metaCeStatusMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

active_licenses_without_ce_trackingintegerrequired

Active licenses left out of data because Payna holds no CE facts for them. An untracked active license is a gap to chase, never a pass: an empty data with this above 0 does not mean the person owes no CE.

Example 0

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404Individual not found, or the individuals API is not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
503Payna could not check what your account has turned on. Retry.
curl https://app.payna.com/api/v1/individuals/{id}/ce-status \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK

Get attestation / disclosure status

GET/individuals/{id}/attestations

Returns attestation and disclosure records for an individual. For MLOs, this surfaces MU2 attestation requests. Use last_completed_at to check when they last attested and next_due_at to see pending deadlines. When no formal attestation round has been initiated, a synthetic record derived from NMLS sync data is returned with status: attested and the observed attestation timestamp.

Key capability individuals

Path parameters

idstring (uuid)required

Individual ID from GET /individuals.

Query parameters

pageinteger

Page number. Starts at 1.

limitinteger

Results per page. Max 200.

Response

200
Attestation records.
Fields
dataarray of Attestationrequired
Each item
attestation_idstring (uuid)required

Attestation request ID, or individual_id for a synthetic record derived from NMLS sync data.

attestation_typestringrequired

Type of attestation. Currently: mu2 (NMLS MU2 filing attestation).

Example mu2

statusstringrequired

Current status: pending, paused, attested, cancelled, superseded.

Example pending

last_completed_atstring (date-time)requirednullable

Most recent timestamp this person attested.

next_due_atstring (date)requirednullable

Deadline for the current open attestation request, when applicable.

metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404Individual not found, or the individuals API is not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
503Payna could not check what your account has turned on. Retry.
curl https://app.payna.com/api/v1/individuals/{id}/attestations \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK

Get tasks / action feed

GET/individuals/{id}/tasks

Returns a normalized feed of actionable work assigned to this individual. Use ?status=open to drive a "things to do" view. assignment_status is authoritative for this person's progress, and it can differ from the overall status when a task has multiple assignees. completion_url links the individual to the Payna portal where they can act.

Key capability individuals

Path parameters

idstring (uuid)required

Individual ID from GET /individuals.

Query parameters

statusenum

Filter by assignment status. open: not yet done. completed: finished.

One of open completed

pageinteger

Page number. Starts at 1.

limitinteger

Results per page. Max 200.

Response

200
Task feed.
Fields
dataarray of IndividualTaskrequired
Each item
task_idstring (uuid)required
individual_idstring (uuid)required
titlestringrequired

Example Complete 2026 CE for CA

descriptionstringrequirednullable
categoryenumrequired

people: person-level work. state: license or deficiency work. general: other.

One of people state general

prioritystringrequirednullable

Task priority (pass-through from Payna internal value).

Example high

statusstringrequired

Task-level status (pass-through from Payna internal value).

Example open

assignment_statusenumrequired

This person's assignment status. Authoritative for this individual.

One of open completed

Example open

due_datestring (date)requirednullable
completed_atstring (date-time)requirednullable
completion_urlstringrequirednullable

Deep link to this specific task in the Payna portal. Format: https://app.payna.com/portal?taskId=<uuid>.

metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404Individual not found, or the individuals API is not turned on for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
503Payna could not check what your account has turned on. Retry.
curl https://app.payna.com/api/v1/individuals/{id}/tasks \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK

Exports

The files the dashboard's Export menus produce, for a scheduled job to download. CSV by default, ?format=xlsx for a workbook. Columns are stable: ISO dates, money as a plain number, codes as written.

Download an export file

GET/exports/{file}

Returns one export as a file. renewal-costs-by-branch-code is the AP allocation file: one row per branch cost code with its branches, licenses and total, the blank "no code yet" bucket last. renewals is all four renewal files as one workbook and is xlsx only, since a CSV holds one sheet.

Needs the licenses capability, plus the Renewals feature for a renewal file or Branches for the branch list. A fee that no CSBS chart row prices exports BLANK and the row reads Not in chart, never 0, which would read as free. Submitted is likewise blank while NMLS states no request status for that holder.

Key capability licenses

Path parameters

fileenumrequired

Which file. The name is the downloaded file's own name.

One of renewal-company-licenses renewal-branch-licenses renewal-costs-by-branch-code renewal-officer-licenses renewals branches

Query parameters

formatenum

CSV by default. renewals is xlsx only.

One of csv xlsx

Response

200
The file. Content-Disposition names it.

Errors

400Unknown format, or the workbook asked for as CSV.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404Unknown file, or the feature behind it is not enabled for this account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/exports/{file} \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK

Education

Sign a loan officer up at your company's continuing education provider.

Send a course sign-up

POST/education/assignments

Tell Payna a loan officer signed up at your company's course provider. Payna finds them on your roster by nmls_id, then by email, which can be their email in Payna or their NMLS work email.

Your company's Assign courses setting decides what happens next.

  • Automatically: Payna creates their account at the provider when they have none, then assigns the courses NMLS says they still need. The call answers 200 when that is done, usually within a few seconds.
  • By hand: Payna creates and assigns nothing, and the call answers 202 at once.

Payna also answers 202 when no officer on your roster matches, or when several do. Payna staff hear about every sign-up and finish whatever is left. Only the officer in the call is set up. Nobody else is assigned anything.

Retry on a 500, 502 or 503. A retry does not create a second account or assign a course twice.

Key capability education

Body

first_namestringrequired

Their first name.

Example Jane

last_namestringrequired

Their last name.

Example Example

emailstring (email)required

Their email. Payna matches on it when nmls_id finds nobody, and their provider account uses it.

Example jane.example@examplemortgage.com

nmls_idstring

Their individual NMLS ID. Payna matches on it first.

Example 1234567

titlestring

Their job title, for the provider's Title field.

Example Loan Officer

Response

200
The officer matched and your company assigns courses automatically. status names the step Payna reached.
Fields
statusenumrequired

The step Payna reached.

  • assigned: every course they need is assigned.
  • nothing_to_assign: their account is ready and they need no courses now.
  • partial: some courses are assigned. Payna will finish the rest.
  • failed: their account is ready. Payna will finish assigning their courses.
  • waiting_for_nmls: their account is ready. Payna assigns their courses after their NMLS record next updates.
  • account_refused or account_unlinked: Payna will finish setting up their account.

One of assigned partial failed nothing_to_assign waiting_for_nmls account_refused account_unlinked

individual_idstringrequired

The officer's ID in Payna.

accountenumrequirednullable

created when Payna made their provider account on this call, existed when they had one. Null when their account is not set up yet.

One of created existed

messagestringrequired

One sentence on what Payna did.

Example Created their Knowledge Coop account and assigned 1 course.

assignedarray of objectsrequired

The courses Payna assigned on this call.

Each item
coursestringrequired

Example 1 Hour Washington SAFE CE 2026

due_onstring (date)requirednullable

The course's due date.

failedarray of objectsrequired

The courses Payna could not assign on this call. Payna staff finish them.

Each item
coursestringrequired
202
Received. Payna sets them up by hand because your company assigns courses by hand, or because no single officer on your roster matched.
Fields
statusenumrequired

One of received

individual_idstringrequirednullable

The officer's ID in Payna. Null when no single officer on your roster matched.

messagestringrequired

One sentence on what Payna will do.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404No course provider is connected for your account.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
502Payna could not reach your course provider. Retry.
503Payna could not pass the sign-up to its staff. Retry.
curl -X POST https://app.payna.com/api/v1/education/assignments \
  -H "Authorization: Bearer $PAYNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Example",
    "email": "jane.example@examplemortgage.com",
    "nmls_id": "1234567",
    "title": "Loan Officer"
  }'
200 OK
{
  "status": "assigned",
  "individual_id": "3f2b8c1e-0000-4000-8000-000000000001",
  "account": "created",
  "message": "Created their Knowledge Coop account and assigned 1 course.",
  "assigned": [
    {
      "course": "1 Hour Washington SAFE CE 2026",
      "due_on": "2026-12-31"
    }
  ],
  "failed": []
}
202 Accepted
{
  "status": "received",
  "individual_id": null,
  "message": "Received. Payna will add them, then set up their Knowledge Coop account and courses."
}

Producers

Your insurance producers as NIPR and the state insurance departments record them. NMLS holds no record of an insurance producer.

  • The NPN is the identity, never the name. Every lookup is by NPN. A renamed agency can leave a second, dead NPN with the same legal name and address on several state registers.
  • One license row per jurisdiction. Lines of authority (Property, Casualty, Life, Health, Personal Lines) are an array on the license, because Property and Casualty usually share one number and one expiry.
  • **lines_of_authority: null is not [].** Null means the register publishes no lines for that kind of record. An empty list means it published a list with nothing on it.
  • Resident versus non-resident. A producer holds one resident license, from their home state, and every other license is issued on the strength of it.
  • Surplus lines is its own license class, beside the producer license. New York calls it excess line.
  • Appointments are per carrier per state, with the carrier's NAIC code and whether the carrier is admitted in that state.

List producers

GET/producers

Returns your agency's producers, sorted by name. Each one carries their NPN, their resident state, their standing, the lines of authority they hold anywhere, and every state license with that license's own lines. See the Producer schema.

Results are paginated, up to 200 per page (default 100).

Key capability individuals

Query parameters

statestring

Only producers licensed in this state, in any status. Example: TX

Example TX

linestring

Only producers holding this line of authority somewhere. A producer whose licenses publish no lines matches nothing, so this narrows rather than audits. See the null rule on the Producers tag. Example: Property

Example Property

resident_statestring

Only producers whose resident state is this one. Producers with no resident state on file match nothing. See resident_state_established.

Example GA

standingenum

Only producers whose standing is this one. See Producer.standing, and note dependency_unknown is a gap in Payna's records, not a finding about the producer, so it is filtered apart from impaired and home_impaired.

One of resident non_resident dependency_unknown impaired home_impaired

include_departedboolean

true to include people who left your agency.

pageinteger

Page number, from 1.

limitinteger

Producers per page. Max 200.

Response

200
A page of producers.
Fields
dataarray of Producerrequired
Each item
idstring (uuid)required

Payna's id for them.

npnstringrequirednullable

Their National Producer Number, the only safe match key. Null until Payna has one for them.

Example 18374655

namestringrequired

Example Dana Example

first_namestringrequirednullable
last_namestringrequirednullable
emailstringrequirednullable

Their work email.

titlestringrequirednullable

Their job title, if your agency set one.

employment_statusenumrequirednullable

terminated means they left. Those are only listed with include_departed=true.

One of active inactive terminated pending

resident_statestringrequirednullable

The state that issued their resident license: the root every non-resident license of theirs depends on. Null means not established, which is a real and common answer. It is never defaulted from a mailing address or from your agency's own state: asserting a dependency chain that may not exist is worse than admitting the gap.

Example GA

resident_state_establishedbooleanrequired

true when resident_state came from a source that establishes it (NIPR, NAIC SBS, or somebody at your agency who checked). false when a value is on file but unproven. Do not read an unproven state as a dependency chain.

standingenumrequired

What their authority rests on, in the SAME five words every license of theirs uses. There is no producer-level status and no roll-up verdict here. Payna publishes what it read; whether a producer may transact is the caller's conclusion to draw.

The value is the worst of their per-state standings, reported worst first, and the authoritative per-state answer is standing on each entry of licenses:

  • impaired: a license of theirs is not in good standing.
  • home_impaired: their RESIDENT license is not in good standing, so the non-resident licenses resting on it are exposed. Exposed, not ended: states differ on whether a home-state lapse ends them, and Payna will not assert fifty statutes.
  • dependency_unknown: licensed, but no resident state is established, so Payna cannot say what their non-resident licenses depend on. A gap in Payna's records, not a finding about the producer. Keep it apart from the two above, or a freshly-loaded roster reads as a compliance emergency.
  • resident / non_resident: nothing is impaired, and this says which kind of license their chain rests on.

One of resident non_resident dependency_unknown impaired home_impaired

licensed_statesarray of stringsrequired

Every state they hold a license in, whatever its standing.

lines_of_authorityarray of stringsrequirednullable

Every line they hold SOMEWHERE, de-duplicated and sorted. It is a roll-up for filtering, not an authority. A line here says nothing about which state it is held in; the authoritative list is lines_of_authority on each license.

null when no license of theirs published a lines list at all, so there is nothing to roll up. Not the same as []. See ProducerLicense.lines_of_authority.

responsible_forarray of ProducerResponsibleRolerequired

States where this producer is the agency's designated responsible licensed person. Empty for most producers.

Each item
statestringrequired

Example GA

roleenumrequired

The stable slug. One concept, every state.

One of designated_responsible_licensed_person

state_labelstringrequired

What this state calls the role. A label to display, never to branch on.

Example Responsible Individual

agency_license_numberstringrequirednullable

The agency license they are named on.

Example 1098221

sincestring (date)requirednullable

When they were designated, where the department publishes it.

licensesarray of ProducerLicenserequired

Every license Payna holds for them, sorted by state. One row per jurisdiction, never per line.

Each item
statestringrequired

Example TX

residencyenumrequired

The spine of the data. resident is the keystone license, issued by their home state. non_resident is held on the strength of it and cannot exceed the lines the home state granted. unknown means no resident state is established, so Payna will not guess which this is.

One of resident non_resident unknown

standingenumrequired

What their authority in this state actually rests on, and whether anything is at risk. Reported worst first, so an impaired license reads impaired whatever its residency. Read residency for that fact, always.

  • resident / non_resident: in good standing, and which kind.
  • dependency_unknown: licensed here, no resident state on file.
  • impaired: THIS license is not in good standing. Nothing may be placed through it here.
  • home_impaired: their RESIDENT license is not in good standing, so this one is exposed. It does not say this license has ended: states differ on whether a home-state lapse ends a non-resident license automatically, and Payna will not assert fifty statutes it does not hold. It means go and ask the department.

One of resident non_resident dependency_unknown impaired home_impaired

license_classenumrequired

The class of license, which is NOT a line of authority. surplus_lines is its own license beside the producer license (New York words the same thing "excess line"), and it is what non-admitted business is placed under.

One of producer surplus_lines adjuster other

license_namestringrequirednullable

The license name the department uses, verbatim. Departments word the same license differently, so never parse it.

Example Non-Resident General Lines Agent - Property and Casualty

license_numberstringrequirednullable

Example 2771904

license_number_shared_witharray of stringsrequired

The lines sharing this license number. Spelled out so a reader who expected a row per line can see where the other rows went.

statusenumrequired

Payna's five-status model, the same vocabulary as every other license in this API.

One of active deficient pending applying not_licensed

sub_statusstringrequirednullable

Detail within the status category.

Example expired

raw_statusstringrequirednullable

The department's own word, verbatim.

Example Active

regulatorstringrequirednullable

Example Texas Department of Insurance

lines_of_authorityarray of LineOfAuthorityrequirednullable

The lines this license grants. Authoritative, unlike the roll-up on Producer.

**Three values, and null is not [].** Read them wrong and the API lies.

  • null: this register publishes no lines for this kind of record. It says NOTHING about authority. Fourteen jurisdictions publish none on an agency record at all (DE, FL, IL, ME, MN, MO, MS, NC, NY, OH, SC, VT, WI, WV); Minnesota prints "There are no active qualifications for this license." on an Active license and publishes lines on the person instead. A client that reads null as "no authority" reports a fully licensed agency as unauthorised in all fourteen.
  • []: the register published a lines list and it was empty. That IS a finding.
  • A list: what the register published, verbatim.

Also [] on a surplus_lines license, which carries no lines by construction.

Each item
linestringrequired

The line as the department words it.

Example Property

statusstringrequirednullable

The line's own status. A license in force can carry a line that is not: a lapsed Property line on a live Property and Casualty license is a real finding, which is why a line carries a status at all.

Example active

effective_datestring (date)requirednullable

When this line was added to the license. Often later than the license's own date.

original_license_datestring (date)requirednullable

When this license was first issued, kept across renewals.

effective_datestring (date)requirednullable

When the current term began.

renewal_duestring (date)requirednullable

When this license must be renewed. ONE date for the whole row, however many lines it carries. Null in a state whose licenses do not expire.

last_synced_atstring (date-time)requirednullable

When Payna last read this license.

last_syncedobjectrequired

How fresh their data is, per source.

Fields
niprstring (date-time)requirednullable

When Payna last read NIPR for them.

state_doistring (date-time)requirednullable

When Payna last read a state insurance department for them. Null when none was needed: NIPR carries most of it.

metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404A 404 means the thing the path names is not one of yours.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/producers \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": [
    {
      "id": "d4e5f6a7-0000-0000-0000-bbccddeeff00",
      "npn": "18374655",
      "name": "Dana Example",
      "first_name": "Dana",
      "last_name": "Example",
      "email": "dana@exampleagency.com",
      "title": "Producer",
      "employment_status": "active",
      "resident_state": "GA",
      "resident_state_established": true,
      "standing": "resident",
      "licensed_states": ["GA", "MN", "TX"],
      "lines_of_authority": ["Casualty", "Property"],
      "responsible_for": [
        {
          "state": "GA",
          "role": "designated_responsible_licensed_person",
          "state_label": "Responsible Individual",
          "agency_license_number": "1098221",
          "since": "2024-06-03"
        }
      ],
      "licenses": [
        {
          "state": "GA",
          "residency": "resident",
          "standing": "resident",
          "license_class": "producer",
          "license_name": "Resident Insurance Producer",
          "license_number": "3214889",
          "license_number_shared_with": ["Property", "Casualty"],
          "status": "active",
          "sub_status": null,
          "raw_status": "Active",
          "regulator": "Georgia Office of Commissioner of Insurance",
          "lines_of_authority": [
            {
              "line": "Property",
              "status": "active",
              "effective_date": "2019-04-11"
            },
            {
              "line": "Casualty",
              "status": "active",
              "effective_date": "2019-04-11"
            }
          ],
          "original_license_date": "2019-04-11",
          "effective_date": "2025-04-11",
          "renewal_due": "2027-04-30",
          "last_synced_at": "2026-11-05T07:04:19Z"
        },
        {
          "state": "MN",
          "residency": "non_resident",
          "standing": "non_resident",
          "license_class": "producer",
          "license_name": "Nonresident Insurance Producer",
          "license_number": "41007200",
          "license_number_shared_with": [],
          "status": "active",
          "sub_status": null,
          "raw_status": "Active",
          "regulator": "Minnesota Department of Commerce",
          "lines_of_authority": null,
          "original_license_date": "2021-09-14",
          "effective_date": "2021-09-14",
          "renewal_due": "2027-10-31",
          "last_synced_at": "2026-11-05T07:04:19Z"
        },
        {
          "state": "TX",
          "residency": "non_resident",
          "standing": "non_resident",
          "license_class": "producer",
          "license_name": "Non-Resident General Lines Agent - Property and Casualty",
          "license_number": "2771904",
          "license_number_shared_with": ["Property", "Casualty"],
          "status": "active",
          "sub_status": null,
          "raw_status": "Active",
          "regulator": "Texas Department of Insurance",
          "lines_of_authority": [
            {
              "line": "Property",
              "status": "active",
              "effective_date": "2023-02-02"
            },
            {
              "line": "Casualty",
              "status": "active",
              "effective_date": "2023-02-02"
            }
          ],
          "original_license_date": "2023-02-02",
          "effective_date": "2025-02-02",
          "renewal_due": "2027-01-31",
          "last_synced_at": "2026-11-05T07:04:19Z"
        },
        {
          "state": "TX",
          "residency": "non_resident",
          "standing": "non_resident",
          "license_class": "surplus_lines",
          "license_name": "Non-Resident Surplus Lines Agent",
          "license_number": "2771905",
          "license_number_shared_with": [],
          "status": "active",
          "sub_status": null,
          "raw_status": "Active",
          "regulator": "Texas Department of Insurance",
          "lines_of_authority": [],
          "original_license_date": "2023-05-19",
          "effective_date": "2025-05-19",
          "renewal_due": "2027-04-30",
          "last_synced_at": "2026-11-05T07:04:19Z"
        }
      ],
      "last_synced": {
        "nipr": "2026-11-05T07:04:19Z",
        "state_doi": "2026-11-04T07:02:55Z"
      }
    }
  ],
  "meta": {
    "total": 41,
    "page": 1,
    "limit": 100,
    "synced_at": "2026-11-05T07:04:19Z"
  }
}

Get one producer

GET/producers/{id}

Retrieves one producer by NPN, or by the id returned in the list, with every license and every license's lines of authority. Producers who have left your agency are included.

Look them up by NPN. A name is not an identifier here: see the NPN rule at the top of this section.

Key capability individuals

Path parameters

idstringrequired

Their NPN, like 18374655, or Payna's id for them.

Example 18374655

Response

200
The producer.
Fields
dataProducerrequired

One producer and everything Payna knows about them.

Identity is the NPN. name is a label, not a key. See the NPN rule on the Producers tag.

Fields
idstring (uuid)required

Payna's id for them.

npnstringrequirednullable

Their National Producer Number, the only safe match key. Null until Payna has one for them.

Example 18374655

namestringrequired

Example Dana Example

first_namestringrequirednullable
last_namestringrequirednullable
emailstringrequirednullable

Their work email.

titlestringrequirednullable

Their job title, if your agency set one.

employment_statusenumrequirednullable

terminated means they left. Those are only listed with include_departed=true.

One of active inactive terminated pending

resident_statestringrequirednullable

The state that issued their resident license: the root every non-resident license of theirs depends on. Null means not established, which is a real and common answer. It is never defaulted from a mailing address or from your agency's own state: asserting a dependency chain that may not exist is worse than admitting the gap.

Example GA

resident_state_establishedbooleanrequired

true when resident_state came from a source that establishes it (NIPR, NAIC SBS, or somebody at your agency who checked). false when a value is on file but unproven. Do not read an unproven state as a dependency chain.

standingenumrequired

What their authority rests on, in the SAME five words every license of theirs uses. There is no producer-level status and no roll-up verdict here. Payna publishes what it read; whether a producer may transact is the caller's conclusion to draw.

The value is the worst of their per-state standings, reported worst first, and the authoritative per-state answer is standing on each entry of licenses:

  • impaired: a license of theirs is not in good standing.
  • home_impaired: their RESIDENT license is not in good standing, so the non-resident licenses resting on it are exposed. Exposed, not ended: states differ on whether a home-state lapse ends them, and Payna will not assert fifty statutes.
  • dependency_unknown: licensed, but no resident state is established, so Payna cannot say what their non-resident licenses depend on. A gap in Payna's records, not a finding about the producer. Keep it apart from the two above, or a freshly-loaded roster reads as a compliance emergency.
  • resident / non_resident: nothing is impaired, and this says which kind of license their chain rests on.

One of resident non_resident dependency_unknown impaired home_impaired

licensed_statesarray of stringsrequired

Every state they hold a license in, whatever its standing.

lines_of_authorityarray of stringsrequirednullable

Every line they hold SOMEWHERE, de-duplicated and sorted. It is a roll-up for filtering, not an authority. A line here says nothing about which state it is held in; the authoritative list is lines_of_authority on each license.

null when no license of theirs published a lines list at all, so there is nothing to roll up. Not the same as []. See ProducerLicense.lines_of_authority.

responsible_forarray of ProducerResponsibleRolerequired

States where this producer is the agency's designated responsible licensed person. Empty for most producers.

Each item
statestringrequired

Example GA

roleenumrequired

The stable slug. One concept, every state.

One of designated_responsible_licensed_person

state_labelstringrequired

What this state calls the role. A label to display, never to branch on.

Example Responsible Individual

agency_license_numberstringrequirednullable

The agency license they are named on.

Example 1098221

sincestring (date)requirednullable

When they were designated, where the department publishes it.

licensesarray of ProducerLicenserequired

Every license Payna holds for them, sorted by state. One row per jurisdiction, never per line.

Each item
statestringrequired

Example TX

residencyenumrequired

The spine of the data. resident is the keystone license, issued by their home state. non_resident is held on the strength of it and cannot exceed the lines the home state granted. unknown means no resident state is established, so Payna will not guess which this is.

One of resident non_resident unknown

standingenumrequired

What their authority in this state actually rests on, and whether anything is at risk. Reported worst first, so an impaired license reads impaired whatever its residency. Read residency for that fact, always.

  • resident / non_resident: in good standing, and which kind.
  • dependency_unknown: licensed here, no resident state on file.
  • impaired: THIS license is not in good standing. Nothing may be placed through it here.
  • home_impaired: their RESIDENT license is not in good standing, so this one is exposed. It does not say this license has ended: states differ on whether a home-state lapse ends a non-resident license automatically, and Payna will not assert fifty statutes it does not hold. It means go and ask the department.

One of resident non_resident dependency_unknown impaired home_impaired

license_classenumrequired

The class of license, which is NOT a line of authority. surplus_lines is its own license beside the producer license (New York words the same thing "excess line"), and it is what non-admitted business is placed under.

One of producer surplus_lines adjuster other

license_namestringrequirednullable

The license name the department uses, verbatim. Departments word the same license differently, so never parse it.

Example Non-Resident General Lines Agent - Property and Casualty

license_numberstringrequirednullable

Example 2771904

license_number_shared_witharray of stringsrequired

The lines sharing this license number. Spelled out so a reader who expected a row per line can see where the other rows went.

statusenumrequired

Payna's five-status model, the same vocabulary as every other license in this API.

One of active deficient pending applying not_licensed

sub_statusstringrequirednullable

Detail within the status category.

Example expired

raw_statusstringrequirednullable

The department's own word, verbatim.

Example Active

regulatorstringrequirednullable

Example Texas Department of Insurance

lines_of_authorityarray of LineOfAuthorityrequirednullable

The lines this license grants. Authoritative, unlike the roll-up on Producer.

**Three values, and null is not [].** Read them wrong and the API lies.

  • null: this register publishes no lines for this kind of record. It says NOTHING about authority. Fourteen jurisdictions publish none on an agency record at all (DE, FL, IL, ME, MN, MO, MS, NC, NY, OH, SC, VT, WI, WV); Minnesota prints "There are no active qualifications for this license." on an Active license and publishes lines on the person instead. A client that reads null as "no authority" reports a fully licensed agency as unauthorised in all fourteen.
  • []: the register published a lines list and it was empty. That IS a finding.
  • A list: what the register published, verbatim.

Also [] on a surplus_lines license, which carries no lines by construction.

Each item
linestringrequired

The line as the department words it.

Example Property

statusstringrequirednullable

The line's own status. A license in force can carry a line that is not: a lapsed Property line on a live Property and Casualty license is a real finding, which is why a line carries a status at all.

Example active

effective_datestring (date)requirednullable

When this line was added to the license. Often later than the license's own date.

original_license_datestring (date)requirednullable

When this license was first issued, kept across renewals.

effective_datestring (date)requirednullable

When the current term began.

renewal_duestring (date)requirednullable

When this license must be renewed. ONE date for the whole row, however many lines it carries. Null in a state whose licenses do not expire.

last_synced_atstring (date-time)requirednullable

When Payna last read this license.

last_syncedobjectrequired

How fresh their data is, per source.

Fields
niprstring (date-time)requirednullable

When Payna last read NIPR for them.

state_doistring (date-time)requirednullable

When Payna last read a state insurance department for them. Null when none was needed: NIPR carries most of it.

metaobjectrequired
Fields
synced_atstring (date-time)requirednullable

The same as last_synced.nipr.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404A 404 means the thing the path names is not one of yours.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/producers/18374655 \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": {
    "id": "d4e5f6a7-0000-0000-0000-bbccddeeff00",
    "npn": "18374655",
    "name": "Dana Example",
    "first_name": "Dana",
    "last_name": "Example",
    "email": "dana@exampleagency.com",
    "title": "Producer",
    "employment_status": "active",
    "resident_state": "GA",
    "resident_state_established": true,
    "standing": "resident",
    "licensed_states": ["GA", "MN", "TX"],
    "lines_of_authority": ["Casualty", "Property"],
    "responsible_for": [
      {
        "state": "GA",
        "role": "designated_responsible_licensed_person",
        "state_label": "Responsible Individual",
        "agency_license_number": "1098221",
        "since": "2024-06-03"
      }
    ],
    "licenses": [
      {
        "state": "GA",
        "residency": "resident",
        "standing": "resident",
        "license_class": "producer",
        "license_name": "Resident Insurance Producer",
        "license_number": "3214889",
        "license_number_shared_with": ["Property", "Casualty"],
        "status": "active",
        "sub_status": null,
        "raw_status": "Active",
        "regulator": "Georgia Office of Commissioner of Insurance",
        "lines_of_authority": [
          {
            "line": "Property",
            "status": "active",
            "effective_date": "2019-04-11"
          },
          {
            "line": "Casualty",
            "status": "active",
            "effective_date": "2019-04-11"
          }
        ],
        "original_license_date": "2019-04-11",
        "effective_date": "2025-04-11",
        "renewal_due": "2027-04-30",
        "last_synced_at": "2026-11-05T07:04:19Z"
      },
      {
        "state": "MN",
        "residency": "non_resident",
        "standing": "non_resident",
        "license_class": "producer",
        "license_name": "Nonresident Insurance Producer",
        "license_number": "41007200",
        "license_number_shared_with": [],
        "status": "active",
        "sub_status": null,
        "raw_status": "Active",
        "regulator": "Minnesota Department of Commerce",
        "lines_of_authority": null,
        "original_license_date": "2021-09-14",
        "effective_date": "2021-09-14",
        "renewal_due": "2027-10-31",
        "last_synced_at": "2026-11-05T07:04:19Z"
      },
      {
        "state": "TX",
        "residency": "non_resident",
        "standing": "non_resident",
        "license_class": "producer",
        "license_name": "Non-Resident General Lines Agent - Property and Casualty",
        "license_number": "2771904",
        "license_number_shared_with": ["Property", "Casualty"],
        "status": "active",
        "sub_status": null,
        "raw_status": "Active",
        "regulator": "Texas Department of Insurance",
        "lines_of_authority": [
          {
            "line": "Property",
            "status": "active",
            "effective_date": "2023-02-02"
          },
          {
            "line": "Casualty",
            "status": "active",
            "effective_date": "2023-02-02"
          }
        ],
        "original_license_date": "2023-02-02",
        "effective_date": "2025-02-02",
        "renewal_due": "2027-01-31",
        "last_synced_at": "2026-11-05T07:04:19Z"
      },
      {
        "state": "TX",
        "residency": "non_resident",
        "standing": "non_resident",
        "license_class": "surplus_lines",
        "license_name": "Non-Resident Surplus Lines Agent",
        "license_number": "2771905",
        "license_number_shared_with": [],
        "status": "active",
        "sub_status": null,
        "raw_status": "Active",
        "regulator": "Texas Department of Insurance",
        "lines_of_authority": [],
        "original_license_date": "2023-05-19",
        "effective_date": "2025-05-19",
        "renewal_due": "2027-04-30",
        "last_synced_at": "2026-11-05T07:04:19Z"
      }
    ],
    "last_synced": {
      "nipr": "2026-11-05T07:04:19Z",
      "state_doi": "2026-11-04T07:02:55Z"
    }
  },
  "meta": {
    "synced_at": "2026-11-05T07:04:19Z"
  }
}

List licenses, one row each

GET/producers/licenses

Returns every producer license across the roster as a flat row that includes the producer, for loading into a spreadsheet or a BI tool. Not paginated: one call returns every row.

One row per jurisdiction, not per line. lines_of_authority is a single column holding the license's lines, because Property and Casualty share one number and one expiry. Filtering by line selects the rows that carry it; it does not split them.

Pass format=csv to receive a CSV file instead of JSON.

Key capability individuals

Query parameters

statestring

Only licenses in this state.

Example TX

statusenum

Only licenses in this status.

One of active deficient pending applying not_licensed

linestring

Only licenses carrying this line of authority. The row is returned whole, with all of its lines. A license whose register publishes no lines (lines_of_authority: null) matches nothing here, so this filter EXCLUDES licenses that may well carry the line. Use it to narrow, never to audit coverage.

Example Property

residencyenum

resident returns each producer's keystone license only.

One of resident non_resident unknown

license_classenum

Surplus lines is its own class, not a line.

One of producer surplus_lines adjuster other

include_departedboolean

true to include people who left your agency.

formatenum

csv for a CSV file.

One of json csv

Response

200
Every license row.
Fields
dataarray of ProducerLicenseRowrequired
Each item
producer_idstring (uuid)required
producer_npnstringrequirednullable
producer_namestringrequired
producer_emailstringrequirednullable
employment_statusstringrequirednullable
resident_statestringrequirednullable

Carried on every row so a lapse in the home state is visible beside the license that depends on it.

statestringrequired
residencyenumrequired

One of resident non_resident unknown

standingenumrequired

One of resident non_resident dependency_unknown impaired home_impaired

license_classenumrequired

One of producer surplus_lines adjuster other

license_namestringrequirednullable
license_numberstringrequirednullable
statusenumrequired

One of active deficient pending applying not_licensed

sub_statusstringrequirednullable
raw_statusstringrequirednullable
regulatorstringrequirednullable
lines_of_authoritystringrequirednullable

The license's lines, joined with ; . **null and empty are different facts. See ProducerLicense**.lines_of_authority. JSON keeps the difference. A CSV cell cannot carry both, so the CSV writes the literal not published where the register publishes no lines and leaves the cell empty where it published an empty list.

Example Property; Casualty

original_license_datestring (date)requirednullable
effective_datestring (date)requirednullable
renewal_duestring (date)requirednullable
last_synced_atstring (date-time)requirednullable
metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404A 404 means the thing the path names is not one of yours.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/producers/licenses \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": [
    {
      "producer_id": "d4e5f6a7-0000-0000-0000-bbccddeeff00",
      "producer_npn": "18374655",
      "producer_name": "Dana Example",
      "producer_email": "dana@exampleagency.com",
      "employment_status": "active",
      "resident_state": "GA",
      "state": "TX",
      "residency": "non_resident",
      "standing": "non_resident",
      "license_class": "producer",
      "license_name": "Non-Resident General Lines Agent - Property and Casualty",
      "license_number": "2771904",
      "status": "active",
      "sub_status": null,
      "raw_status": "Active",
      "regulator": "Texas Department of Insurance",
      "lines_of_authority": "Property; Casualty",
      "original_license_date": "2023-02-02",
      "effective_date": "2025-02-02",
      "renewal_due": "2027-01-31",
      "last_synced_at": "2026-11-05T07:04:19Z"
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "limit": 100,
    "synced_at": "2026-11-05T07:04:19Z"
  }
}
producer_id,producer_npn,producer_name,...

Get a producer's carrier appointments

GET/producers/{id}/appointments

Returns the carrier appointments this producer holds: one row per carrier per state, with the carrier's NAIC code, whether the carrier is admitted in that state, the status, and the effective and termination dates.

A license says what they may do; an appointment says whose paper they may write. Both are required to place business, and a terminated appointment is the usual reason a licensed producer cannot.

Match carriers on carrier_naic_code, not on carrier_name: a group writes under many trading names and each state register spells them differently.

Key capability individuals

Path parameters

idstringrequired

Their NPN, or Payna's id for them.

Example 18374655

Query parameters

statestring

Only appointments in this state.

Example GA

statusenum

Only appointments in this status. Terminated ones are returned by default: a termination date is the fact you usually need.

One of active terminated pending

pageinteger
limitinteger

Response

200
The producer's appointments.
Fields
dataarray of Appointmentrequired
Each item
carrier_namestringrequired

The carrier as the state register prints it. A display label: a group writes under many trading names and each register spells them differently.

Example Example Mutual Insurance Company

carrier_naic_codestringrequirednullable

The carrier's NAIC company code, which is the match key. Null only where a register publishes none.

Example 21423

admittedbooleanrequirednullable

Whether the carrier is admitted in this state. It decides how business reaches the carrier: admitted paper is written on an appointment, while non-admitted (surplus lines) business is placed under a surplus_lines license, which most states appoint nobody for. So an appointment row for a non-admitted carrier is the exception. Null when Payna has not established it.

statestringrequired

Example GA

statusenumrequired

Terminated appointments are included rather than hidden: the termination date is usually the fact you need.

One of active terminated pending

lines_of_authorityarray of stringsrequirednullable

The lines this appointment covers, in states that appoint per line. null where the register publishes no lines on an appointment (most states appoint per carrier, not per line), which is not the same as [], an appointment that covers nothing. Same three-valued rule as ProducerLicense.lines_of_authority.

effective_datestring (date)requirednullable

When the appointment took effect.

termination_datestring (date)requirednullable

When it ended. Null while it is in force.

termination_reasonstringrequirednullable

The carrier's stated reason, verbatim, where the register publishes one. A for-cause termination is a reportable event in most states. Never paraphrase it.

last_synced_atstring (date-time)requirednullable
metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404A 404 means the thing the path names is not one of yours.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/producers/18374655/appointments \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": [
    {
      "carrier_name": "Example Mutual Insurance Company",
      "carrier_naic_code": "21423",
      "admitted": true,
      "state": "GA",
      "status": "active",
      "lines_of_authority": ["Property", "Casualty"],
      "effective_date": "2024-07-01",
      "termination_date": null,
      "termination_reason": null,
      "last_synced_at": "2026-11-05T07:04:19Z"
    }
  ],
  "meta": {
    "total": 7,
    "page": 1,
    "limit": 100,
    "synced_at": "2026-11-05T07:04:19Z"
  }
}

Get continuing education status

GET/producers/{id}/ce-status

Returns continuing education per state, one record per state that requires it, including the ethics component that state counts separately.

The CE store is empty, and will stay empty until the insurance CE sync is built. The columns exist; nothing fills them. Measured across every insurance roster Payna holds, not one license row carries an hour figure. So this endpoint returns a record per state with every hour null, and the last record in the example below is what that looks like. Null is not zero: it means unread, and a reminder built on a null remaining_hours would tell a producer they owe nothing.

Insurance CE is nothing like the SAFE Act's. There is no federal core, every hour belongs to a state, the cycle is usually two years rather than a calendar year, and the deadline is set from the license or the producer rather than from 31 December. So read cycle_ends_on and deadline and never derive a year.

Three fields carry the parts of insurance CE that a mortgage shape cannot say, and a caller that ignores them will read a satisfied record where there is work owed:

  • obligation_source says WHOSE rule sets the hours: the resident state under reciprocity, this state because it issued the license, or this state because the resident state has no CE at all and it imposes its own anyway. It is not a boolean: "the resident state satisfies it" and "this state falls back to its own rule" are different answers, and Florida and Texas give the second one.
  • product_training[] is owed BESIDE the hours and survives reciprocity. Long-term care, annuity, flood and crop training is not CE and is not waived with it; California's course binds non-residents and may not be one the resident state approved.
  • provider_reported_at is the compliance event, not the completion. A producer can finish every hour and still lapse where the provider has not reported them by the renewal date, which Illinois says in those words.

Key capability individuals

Path parameters

idstringrequired

Their NPN, or Payna's id for them.

Example 18374655

Query parameters

statestring

Only this state.

Example GA

pageinteger
limitinteger

Response

200
CE per state: the resident state that sets the hours, a non-resident state whose hours the resident state satisfies but whose product training is owed anyway, and (the LAST record) what every state actually returns until the insurance CE sync exists.
Fields
dataarray of ProducerCeStatusrequired
Each item
statestringrequired

Example GA

license_classenumrequired

The license class these hours are owed for. A state can require CE separately for a producer license and an adjuster license.

One of producer surplus_lines adjuster other

obligation_sourceenumrequirednullable

Whose rule sets the hours in this state. Conditional, not a boolean. Read it before reading any hour figure.

  • this_state: this state issued the license and sets the hours. The resident license is always this.
  • resident_state: a non-resident license whose CE the resident state satisfies, which is the general rule (NAIC Model 218 §16.B. It sits in the *Reciprocity* section, not a CE one, so reading a state's CE statute alone gives the wrong answer: Minnesota's exemption is in § 60K.53, not § 60K.56). Hours of 0 here mean nothing is owed BECAUSE of reciprocity.
  • this_state_no_reciprocity: this state imposes its OWN hours on a non-resident license because the resident state requires none. Florida (626.2815(6)) and Texas do exactly this, and a caller that assumed reciprocity misses a real obligation.

null means unread, not "no obligation". A boolean cannot carry this: it would fuse the second and third cases, which are opposite answers about whether work is owed.

One of this_state resident_state this_state_no_reciprocity

required_hoursnumberrequirednullable

Total hours this state requires for the cycle, ethics included.

Example 24

completed_hoursnumberrequirednullable

Example 18

remaining_hoursnumberrequirednullable

max(0, required - completed). Null when either side is unknown. Never 0, which would read as done.

Example 6

ethics_required_hoursnumberrequirednullable

The ethics hours inside required_hours, not on top of them. Most states count them within the total.

Example 3

ethics_completed_hoursnumberrequirednullable

Example 3

ethics_completebooleanrequirednullable

Reported on its own because a producer can satisfy the total and still be refused a renewal on ethics alone.

statusenumrequirednullable

compliant = done; pending = in progress; deficient = past the deadline.

One of compliant pending deficient

deadlinestring (date)requirednullable

The date CE must be done by. Where a state refuses a renewal until CE is complete, this is the earlier of the CE date and the renewal date.

cycle_ends_onstring (date)requirednullable

The end of the current CE cycle, usually two years. The cycle, not a calendar year, is what the hours belong to.

provider_reported_atstring (date-time)requirednullable

When the course provider REPORTED these hours to the state. The compliance event is the report, not the completion: Illinois says courses "not reported by the renewal date… will result in the licensee failing to meet eligibility requirements… and may result in a… lapse in licensure". So a producer can hold remaining_hours: 0 and still lapse while this is null. Null also means unread. It is not proof that nothing was reported.

product_trainingarray of ProducerCeProductTrainingrequirednullable

Product training owed in this state, BESIDE the hours above and not counted in them. It survives CE reciprocity: long-term care, annuity, flood and crop training is not continuing education and is not waived with it, so an obligation_source of resident_state says nothing about these rows.

null means Payna has read no training record for this state, which is every state today. [] means it read one and this state requires none. Same three-valued rule as ProducerLicense.lines_of_authority, and for the same reason.

Each item
trainingstringrequired

The training as the state names it. Not a closed set.

Example Long-term care

required_hoursnumberrequirednullable

Hours owed for the CURRENT cycle.

Example 4

completed_hoursnumberrequirednullable

Example 4

remaining_hoursnumberrequirednullable

max(0, required - completed). Null when either side is unknown. Never 0, which would read as done.

Example 0

initial_hours_requirednumberrequirednullable

A one-off course owed before the first sale, separate from the recurring hours. Long-term care is the common 8-plus-4 shape.

Example 8

resident_state_course_acceptedbooleanrequirednullable

false where this state requires its OWN approved course and will not accept the resident state's. California says so expressly. Null when Payna has not established it. This is the one place a boolean is the right shape, because it is a fact about one course in one state, not about who sets an obligation.

statusenumrequirednullable

compliant = done; pending = in progress; deficient = past the deadline.

One of compliant pending deficient

deadlinestring (date)requirednullable

The date this training must be done by, where the state publishes one.

provider_reported_atstring (date-time)requirednullable

When the provider reported it. The compliance event, exactly as on ProducerCeStatus.

last_synced_atstring (date-time)requirednullable
metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404A 404 means the thing the path names is not one of yours.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/producers/18374655/ce-status \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": [
    {
      "state": "GA",
      "license_class": "producer",
      "obligation_source": "this_state",
      "required_hours": 24,
      "completed_hours": 18,
      "remaining_hours": 6,
      "ethics_required_hours": 3,
      "ethics_completed_hours": 3,
      "ethics_complete": true,
      "status": "pending",
      "deadline": "2027-04-30",
      "cycle_ends_on": "2027-04-30",
      "provider_reported_at": "2026-10-30T14:12:00Z",
      "product_training": [
        {
          "training": "Long-term care",
          "required_hours": 4,
          "completed_hours": 4,
          "remaining_hours": 0,
          "initial_hours_required": 8,
          "resident_state_course_accepted": true,
          "status": "compliant",
          "deadline": "2027-04-30",
          "provider_reported_at": "2026-09-12T09:40:00Z"
        }
      ],
      "last_synced_at": "2026-11-05T07:04:19Z"
    },
    {
      "state": "MN",
      "license_class": "producer",
      "obligation_source": "resident_state",
      "required_hours": 0,
      "completed_hours": 0,
      "remaining_hours": 0,
      "ethics_required_hours": 0,
      "ethics_completed_hours": 0,
      "ethics_complete": true,
      "status": "compliant",
      "deadline": null,
      "cycle_ends_on": "2027-04-30",
      "provider_reported_at": null,
      "product_training": [
        {
          "training": "Long-term care",
          "required_hours": 4,
          "completed_hours": 0,
          "remaining_hours": 4,
          "initial_hours_required": 8,
          "resident_state_course_accepted": true,
          "status": "pending",
          "deadline": "2027-04-30",
          "provider_reported_at": null
        }
      ],
      "last_synced_at": "2026-11-05T07:04:19Z"
    },
    {
      "state": "TX",
      "license_class": "producer",
      "obligation_source": null,
      "required_hours": null,
      "completed_hours": null,
      "remaining_hours": null,
      "ethics_required_hours": null,
      "ethics_completed_hours": null,
      "ethics_complete": null,
      "status": null,
      "deadline": null,
      "cycle_ends_on": null,
      "provider_reported_at": null,
      "product_training": null,
      "last_synced_at": null
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "limit": 100,
    "synced_at": null
  }
}

List the agency's own carrier appointments

GET/appointments

Returns the carrier appointments your agency holds, as distinct from your producers'. Same shape as GET /producers/{id}/appointments: the path says who holds them.

An agency's appointments are a separate fact from its producers'. An agency can be appointed with a carrier no producer of yours is, and the reverse, and in many states business is written on the agency's appointment with the producer's license. Do not derive one from the other.

Key capability individuals

Query parameters

statestring

Only appointments in this state.

Example GA

carrier_naic_codestring

Only appointments with this carrier, matched on its NAIC code.

Example 21423

statusenum

Only appointments in this status.

One of active terminated pending

pageinteger
limitinteger

Response

200
The agency's appointments.
Fields
dataarray of Appointmentrequired
Each item
carrier_namestringrequired

The carrier as the state register prints it. A display label: a group writes under many trading names and each register spells them differently.

Example Example Mutual Insurance Company

carrier_naic_codestringrequirednullable

The carrier's NAIC company code, which is the match key. Null only where a register publishes none.

Example 21423

admittedbooleanrequirednullable

Whether the carrier is admitted in this state. It decides how business reaches the carrier: admitted paper is written on an appointment, while non-admitted (surplus lines) business is placed under a surplus_lines license, which most states appoint nobody for. So an appointment row for a non-admitted carrier is the exception. Null when Payna has not established it.

statestringrequired

Example GA

statusenumrequired

Terminated appointments are included rather than hidden: the termination date is usually the fact you need.

One of active terminated pending

lines_of_authorityarray of stringsrequirednullable

The lines this appointment covers, in states that appoint per line. null where the register publishes no lines on an appointment (most states appoint per carrier, not per line), which is not the same as [], an appointment that covers nothing. Same three-valued rule as ProducerLicense.lines_of_authority.

effective_datestring (date)requirednullable

When the appointment took effect.

termination_datestring (date)requirednullable

When it ended. Null while it is in force.

termination_reasonstringrequirednullable

The carrier's stated reason, verbatim, where the register publishes one. A for-cause termination is a reportable event in most states. Never paraphrase it.

last_synced_atstring (date-time)requirednullable
metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The key lacks a capability this endpoint needs.
404A 404 means the thing the path names is not one of yours.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/appointments \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": [
    {
      "carrier_name": "Example Mutual Insurance Company",
      "carrier_naic_code": "21423",
      "admitted": true,
      "state": "GA",
      "status": "active",
      "lines_of_authority": ["Property", "Casualty"],
      "effective_date": "2024-07-01",
      "termination_date": null,
      "termination_reason": null,
      "last_synced_at": "2026-11-05T07:04:19Z"
    }
  ],
  "meta": {
    "total": 23,
    "page": 1,
    "limit": 100,
    "synced_at": "2026-11-05T07:04:19Z"
  }
}

List the NIPR verifications Payna has performed

GET/nipr/verifications

Returns the NIPR verifications Payna has already performed for your agency, newest first. It is a record of work, not a way to commission it: there is no operation in this API that requests a verification, so nothing a caller does adds a row here.

The collection will be empty until Payna builds the flow that performs them, and an empty collection is not a statement that a producer has no NIPR record. Payna has not settled what performs a verification (a dashboard action, a staff route or a periodic sync are all open), so do not build on a row appearing.

This read is the only entry point to the resource. With no request operation there is no verification_id handed back, so a caller holding only GET /nipr/verifications/{id} could never name one. Mortgage publishes no collection read today; if that stays true, this list is the one place the two halves differ.

Key capability nipr_verification

Query parameters

npnstring

Only verifications of this NPN. The NPN is the key here as everywhere in this section. There is no name filter.

Example 18374655

statusenum

Only verifications in this status.

One of pending reading complete not_found failed

subject_typeenum

Only verifications of a person (individual), or only of an agency (company, the same word the mortgage table uses).

One of individual company

fromstring (date)

Only verifications created on or after this date.

tostring (date)

Only verifications created on or before this date.

pageinteger
limitinteger

Response

200
A page of verifications, newest first.
Fields
dataarray of NiprVerificationrequired
Each item
statusenum

One of complete

metaMetarequired
Fields
totalintegerrequired

Example 18

pageintegerrequired

Example 1

limitintegerrequired

Example 50

synced_atstringrequirednullable

When Payna last updated these records.

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The API key lacks the nipr_verification capability.
404A 404 means the thing the path names is not one of yours.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/nipr/verifications \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "data": [
    {
      "verification_id": "nvr_7b1f3c2e-0000-4000-8000-aabbccddeeff",
      "status": "complete",
      "subject_type": "individual",
      "external_reference": "quote-45812",
      "requested": {
        "npn": "18374655"
      },
      "retrieved_at": "2026-11-05T17:00:04Z",
      "source": {
        "provider": "NIPR Producer Database",
        "retrieved_for": "18374655"
      },
      "record": {
        "npn": "18374655",
        "name": "Dana Example",
        "resident_state": "GA",
        "other_names": [],
        "licenses": [
          {
            "state": "GA",
            "residency": "resident",
            "license_class": "producer",
            "license_name": "Resident Insurance Producer",
            "license_number": "3214889",
            "status": "Active",
            "status_date": "2025-04-11",
            "original_issue_date": "2019-04-11",
            "expiration_date": "2027-04-30",
            "lines_of_authority": [
              {
                "line": "Property",
                "status": "Active",
                "effective_date": "2019-04-11"
              },
              {
                "line": "Casualty",
                "status": "Active",
                "effective_date": "2019-04-11"
              }
            ]
          }
        ],
        "appointments": [
          {
            "carrier_name": "Example Mutual Insurance Company",
            "carrier_naic_code": "21423",
            "admitted": true,
            "state": "GA",
            "status": "active",
            "lines_of_authority": ["Property", "Casualty"],
            "effective_date": "2024-07-01",
            "termination_date": null,
            "termination_reason": null,
            "last_synced_at": "2026-11-05T07:04:19Z"
          }
        ],
        "regulatory_actions": {
          "published": false
        }
      },
      "created_at": "2026-11-05T16:59:41Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 100,
    "synced_at": null
  }
}

Get a NIPR verification result

GET/nipr/verifications/{id}

Returns the verification and, once it is complete, the record NIPR publishes: the NPN, the resident state, every license with its lines of authority, and the carrier appointments.

Read status before anything else, and **keep not_found and failed apart**. not_found means NIPR publishes no record for that NPN, which is a fact about the NPN. failed means Payna could not read, and error names the limit that was hit. Neither returns an empty licenses array: a read that did not happen is not a producer with no licenses, and treating the two as one is how an outage becomes an unlicensed producer.

Reading never starts work. A read that could start a read would let a caller spend a paid NIPR transaction per poll, and a transaction nobody authorised is worse than a slow answer: NIPR operates as a consumer reporting agency for the Producer Database and access needs a permissible purpose on file. So polling is free of side effects, and nothing in this API requests a verification in the first place.

Key capability nipr_verification

Path parameters

idstringrequired

The verification_id of a verification Payna performed for your agency, e.g. nvr_7b1f3c2e-…. GET /nipr/verifications is how you find one: no operation in this API hands an id back.

Response

200
The verification.
Fields
statusenum

One of complete

Errors

400A parameter or field is invalid. error.fields lists each one.
401The key is missing, malformed or revoked.
403The API key lacks the nipr_verification capability.
404No verification with that ID belongs to your agency.
429Over the rate limit. Wait the seconds in Retry-After.
500Payna failed. Retry, and write to support@payna.com if it persists.
curl https://app.payna.com/api/v1/nipr/verifications/{id} \
  -H "Authorization: Bearer $PAYNA_API_KEY"
200 OK
{
  "verification_id": "nvr_7b1f3c2e-0000-4000-8000-aabbccddeeff",
  "status": "complete",
  "subject_type": "individual",
  "external_reference": "quote-45812",
  "requested": {
    "npn": "18374655"
  },
  "retrieved_at": "2026-11-05T17:00:04Z",
  "source": {
    "provider": "NIPR Producer Database",
    "retrieved_for": "18374655"
  },
  "record": {
    "npn": "18374655",
    "name": "Dana Example",
    "resident_state": "GA",
    "other_names": [],
    "licenses": [
      {
        "state": "GA",
        "residency": "resident",
        "license_class": "producer",
        "license_name": "Resident Insurance Producer",
        "license_number": "3214889",
        "status": "Active",
        "status_date": "2025-04-11",
        "original_issue_date": "2019-04-11",
        "expiration_date": "2027-04-30",
        "lines_of_authority": [
          {
            "line": "Property",
            "status": "Active",
            "effective_date": "2019-04-11"
          },
          {
            "line": "Casualty",
            "status": "Active",
            "effective_date": "2019-04-11"
          }
        ]
      }
    ],
    "appointments": [
      {
        "carrier_name": "Example Mutual Insurance Company",
        "carrier_naic_code": "21423",
        "admitted": true,
        "state": "GA",
        "status": "active",
        "lines_of_authority": ["Property", "Casualty"],
        "effective_date": "2024-07-01",
        "termination_date": null,
        "termination_reason": null,
        "last_synced_at": "2026-11-05T07:04:19Z"
      }
    ],
    "regulatory_actions": {
      "published": false
    }
  },
  "created_at": "2026-11-05T16:59:41Z"
}