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.
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 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.
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:
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.
Capability
Allows
licenses
Your company's own licenses (/licenses).
individuals
Loan officers, individuals, renewals and exports. Also needed to register a webhook.
nmls_verification
Check the NMLS license record of any broker or loan officer.
nipr_verification
Read the NIPR verifications Payna performed for your agency.
education
Sign an officer up at your course provider.
onboarding
Send a new loan officer to onboard (POST /loan-officers).
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.
The request disagrees with a record Payna holds. The message says which.
After resolving it
429
RATE_LIMITED
Over the rate limit.
After Retry-After seconds
500, 503
INTERNAL_ERROR
Something 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.
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:
Payna requests access to their NMLS record. The officer accepts in NMLS.
Payna files the relationship with your company, effective on their start date.
Payna requests their first sponsorship, in the states you name or the states your company sponsors every officer in.
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.
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.
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.
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 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)
})
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.
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.
Assistant
Add it
Claude Code
claude mcp add --transport http payna https://app.payna.com/api/mcp
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.
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 activeinactiveterminatedpending
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 deficientmissing_infonot_startedawaiting_accesssponsoringsponsored
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 companyofficerpaynastate
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 AcceptedRequestedDeficientRejectedRemovedNot 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.
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 submittednot_submittedfailedunknown
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 PECE
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_startedin_progresscompleted
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
Loan officers are not turned on for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
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 1099W2
work_arrangementenumrequired
Where they work. NMLS asks whether the officer works remotely.
One of officehybridremote
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 activeinactiveterminatedpending
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 deficientmissing_infonot_startedawaiting_accesssponsoringsponsored
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 companyofficerpaynastate
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 AcceptedRequestedDeficientRejectedRemovedNot 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.
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 submittednot_submittedfailedunknown
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 PECE
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_startedin_progresscompleted
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 activeinactiveterminatedpending
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 deficientmissing_infonot_startedawaiting_accesssponsoringsponsored
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 companyofficerpaynastate
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 AcceptedRequestedDeficientRejectedRemovedNot 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.
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 submittednot_submittedfailedunknown
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 PECE
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_startedin_progresscompleted
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
Loan officers are not turned on for your account.
409
employee_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.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
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 activeinactiveterminatedpending
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 deficientmissing_infonot_startedawaiting_accesssponsoringsponsored
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 companyofficerpaynastate
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 AcceptedRequestedDeficientRejectedRemovedNot 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.
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 submittednot_submittedfailedunknown
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 PECE
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_startedin_progresscompleted
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
No loan officer with that NMLS ID or id at your company, or loan officers are not turned on for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
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.
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.
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.createdloan_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.createdloan_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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
Loan officers are not turned on for your account.
409
This key already has a webhook for that URL, or already has 5.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
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.
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 alloutstandingnot_submittedpartially_submittedfailedsubmitted
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 jsoncsv
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 submittedpartially_submittednot_submittedfailedunknown
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 submittednot_submittedfailedunknown
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
Loan officers or Renewals are not turned on for your account. Contact support@payna.com.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
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.
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 individualcompany
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 pendingreadingcompleteneeds_identificationnot_foundfailed
Errors
400
No Idempotency-Key header, both or neither of nmls_id and name, or an unknown subject_type.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
The nmls_verification API is not turned on for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
503
Temporarily unable to verify account entitlements. Please retry.
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 pendingreadingcompleteneeds_identificationnot_foundfailed
subject_typeenumrequired
One of individualcompany
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
400
Invalid verification ID.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
No verification with that ID belongs to your company, or the nmls_verification API is not turned on for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
503
Temporarily unable to verify account entitlements. Please retry.
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 pendingreadingcompleteneeds_identificationnot_foundfailed
subject_typeenumrequired
One of individualcompany
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
400
Invalid verification ID, or a missing or invalid nmls_id.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
No verification with that ID belongs to your company, or the nmls_verification API is not turned on for your account.
409
The verification is not awaiting a choice, or that ID is not one of its candidates.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
503
Temporarily unable to verify account entitlements. Please retry.
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).
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 activedeficientpendingapplyingnot_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 submittednot_submittedfailedunknown
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 licensedconditional_approvalsurety_bond_onlydeficientrevokedsuspendedterminated_for_causeexpiredinactiveapplicationapplication_deficientapplication_incompleteunder_reviewpendingwithdrawal_requestedapplication_abandonedvoluntary_withdrawalwithdrawnsurrenderedterminatedrejecteddeniedno_license_neededin_state_office_requirednot_licensedunknown
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 activein_progressdeficientexitednot_pursuedneeds_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
400
A parameter is invalid. INVALID_STATE_CODE when a state code is neither a US state nor an ISO 3166-1 alpha-3 country code.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
The 'licenses' API is not turned on for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
503
Payna could not check what your account has turned on. Retry.
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
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
The 'licenses' API is not turned on for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
503
Payna could not check what your account has turned on. Retry.
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 activedeficientpendingapplyingnot_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 submittednot_submittedfailedunknown
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 licensedconditional_approvalsurety_bond_onlydeficientrevokedsuspendedterminated_for_causeexpiredinactiveapplicationapplication_deficientapplication_incompleteunder_reviewpendingwithdrawal_requestedapplication_abandonedvoluntary_withdrawalwithdrawnsurrenderedterminatedrejecteddeniedno_license_neededin_state_office_requirednot_licensedunknown
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 activein_progressdeficientexitednot_pursuedneeds_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
400
INVALID_STATE_CODE: the code is neither a US state nor an ISO 3166-1 alpha-3 country code.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
No license record for this state, or the licenses API is not turned on for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
503
Payna could not check what your account has turned on. Retry.
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.
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 activeinactiveterminatedpending
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 activeinactiveterminatedpending
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
The 'individuals' API is not turned on for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
503
Payna could not check what your account has turned on. Retry.
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 activedeficientpendingapplyingnot_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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
Individual not found, or the individuals API is not turned on for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
503
Payna could not check what your account has turned on. Retry.
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 openin_progresssubmittedcleared
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 openin_progresssubmittedcleared
due_datestring (date)requirednullable
sourceenumrequired
How this condition was recorded.
One of nmls_syncmanual
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
Individual not found, or the individuals API is not turned on for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
503
Payna could not check what your account has turned on. Retry.
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 compliantpendingdeficient
deadlinestring (date)requirednullable
Date by which CE must be completed for the current cycle.
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
Individual not found, or the individuals API is not turned on for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
503
Payna could not check what your account has turned on. Retry.
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.
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 opencompleted
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 peoplestategeneral
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 opencompleted
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
Individual not found, or the individuals API is not turned on for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
503
Payna could not check what your account has turned on. Retry.
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.
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-licensesrenewal-branch-licensesrenewal-costs-by-branch-coderenewal-officer-licensesrenewalsbranches
Query parameters
formatenum
CSV by default. renewals is xlsx only.
One of csvxlsx
Response
200
The file. Content-Disposition names it.
Errors
400
Unknown format, or the workbook asked for as CSV.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
Unknown file, or the feature behind it is not enabled for this account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
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 assignedpartialfailednothing_to_assignwaiting_for_nmlsaccount_refusedaccount_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 createdexisted
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
No course provider is connected for your account.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
502
Payna could not reach your course provider. Retry.
503
Payna could not pass the sign-up to its staff. Retry.
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.
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 residentnon_residentdependency_unknownimpairedhome_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 activeinactiveterminatedpending
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 residentnon_residentdependency_unknownimpairedhome_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 residentnon_residentunknown
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 residentnon_residentdependency_unknownimpairedhome_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 producersurplus_linesadjusterother
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 activedeficientpendingapplyingnot_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.
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 activeinactiveterminatedpending
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 residentnon_residentdependency_unknownimpairedhome_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 residentnon_residentunknown
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 residentnon_residentdependency_unknownimpairedhome_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 producersurplus_linesadjusterother
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 activedeficientpendingapplyingnot_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.
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 activedeficientpendingapplyingnot_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 residentnon_residentunknown
license_classenum
Surplus lines is its own class, not a line.
One of producersurplus_linesadjusterother
include_departedboolean
true to include people who left your agency.
formatenum
csv for a CSV file.
One of jsoncsv
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 residentnon_residentunknown
standingenumrequired
One of residentnon_residentdependency_unknownimpairedhome_impaired
license_classenumrequired
One of producersurplus_linesadjusterother
license_namestringrequirednullable
license_numberstringrequirednullable
statusenumrequired
One of activedeficientpendingapplyingnot_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.
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 activeterminatedpending
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 activeterminatedpending
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
A 404 means the thing the path names is not one of yours.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
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 producersurplus_linesadjusterother
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_stateresident_statethis_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 compliantpendingdeficient
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.
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.
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 compliantpendingdeficient
deadlinestring (date)requirednullable
The date this training must be done by, where the state publishes one.
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 activeterminatedpending
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 activeterminatedpending
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The key lacks a capability this endpoint needs.
404
A 404 means the thing the path names is not one of yours.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
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 pendingreadingcompletenot_foundfailed
subject_typeenum
Only verifications of a person (individual), or only of an agency (company, the same word the mortgage table uses).
One of individualcompany
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The API key lacks the nipr_verification capability.
404
A 404 means the thing the path names is not one of yours.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.
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
400
A parameter or field is invalid. error.fields lists each one.
401
The key is missing, malformed or revoked.
403
The API key lacks the nipr_verification capability.
404
No verification with that ID belongs to your agency.
429
Over the rate limit. Wait the seconds in Retry-After.
500
Payna failed. Retry, and write to support@payna.com if it persists.