# Payna

> Payna runs financial licensing compliance for regulated companies: state licenses, per-person licensing, surety bonds, renewals, regulator conditions, and NMLS filings, managed by software with human verification.

## Docs

- [API documentation](https://payna.com/docs): one continuous developer document
- [Quickstart](https://payna.com/docs#quickstart): first authenticated call
- [Authentication](https://payna.com/docs#authentication): API keys, capabilities, rate limits
- [Errors](https://payna.com/docs#errors): the error envelope and every code
- [Licenses](https://payna.com/docs#licenses): company license portfolio endpoints
- [Individuals](https://payna.com/docs#individuals): per-person licensing endpoints
- [NMLS verification](https://payna.com/docs#nmls-verification): live reads of what NMLS publishes about any loan originator
- [MCP server](https://payna.com/docs#mcp): OAuth MCP server for AI assistants, per-person, read only
- [Interactive API reference](https://payna.com/docs/api): generated from the OpenAPI spec
- [OpenAPI spec](https://payna.com/api/v1/openapi.json)

## Payna Compliance API

Base URL: https://app.payna.com/api/v1
Authentication: Bearer token, keys begin pk_live_
Methods: GET, plus two POSTs on the NMLS verification flow (start one, and pick which candidate a name meant). Nothing writes to Payna data
Rate limit: 300 requests per 15 minutes, per API key, sliding window. Retry-After on the 429 is the only rate-limit header. There is no X-RateLimit-* triplet and no RateLimit-* triplet
Entitlements: a key capability AND a company entitlement must both pass. 403 FORBIDDEN means the key lacks the capability or API access is off for the account; 404 FORBIDDEN means that specific API is not switched on for the account; 503 INTERNAL_ERROR means entitlements could not be read and is transient, not a refusal

### Capabilities

- licenses: The company license portfolio endpoints.
- individuals: Per-person licensing, conditions, CE, attestations, and tasks.
- nmls_verification: Live reads of what NMLS publishes about any loan originator.

### License endpoints

- GET /licenses: List all licenses
- GET /licenses/summary: Get license summary
- GET /licenses/{state}: Get license for a state

### Individual endpoints

- GET /individuals: List regulated individuals
- GET /individuals/{id}/licenses: Get a person’s licenses
- GET /individuals/{id}/license-conditions: Get open conditions
- GET /individuals/{id}/ce-status: Get continuing education status
- GET /individuals/{id}/attestations: Get attestations
- GET /individuals/{id}/tasks: Get assigned tasks

### NMLS verification endpoints

Live reads of what NMLS Consumer Access publishes about one loan originator. Payna returns the published record. authorized_to_represent is the raw string NMLS prints, and a null means NMLS prints no listing rather than unsponsored. Nothing is cached. retrieved_at on every response is the moment of that read. Results are not instant, so this is asynchronous: POST returns 202 and you poll the GET. Requires the nmls_verification capability and an Idempotency-Key header on the POST.

- POST /nmls/verifications: Start a verification
- POST /nmls/verifications/{id}/select: Pick which candidate a name meant
- GET /nmls/verifications/{id}: Get a verification

Verification statuses: pending, reading, complete, needs_identification, not_found, failed. not_found means NMLS publishes no page for that person and is a fact about NMLS. failed means Payna could not read and says nothing about the person. They must not be collapsed.

### License statuses

- active: Licensed and in good standing in that state.
- deficient: Licensed but with something outstanding against it, including expired licenses.
- pending: Filed and waiting on the regulator.
- applying: Application in progress on our side, not yet with the regulator.
- not_licensed: No license held. This is often deliberate, so check status_detail.intentional before treating it as a gap.

### Error codes

- UNAUTHORIZED (401): The Authorization header is missing, malformed, or the key does not exist. Keys must be sent as a bearer token and begin with pk_live_. Do not retry. The key will not start working on its own.
- REVOKED (401): The key was valid but has since been revoked in the Payna dashboard. Do not retry. Mint a replacement key.
- FORBIDDEN (403, 404): An entitlement said no. 403 means the key lacks the capability for this endpoint, or API access is off for your account. 404 means your account does not have this particular API, licenses or individuals, switched on. Do not retry. Rotating the key does not help. Contact Payna.
- RATE_LIMITED (429): Budget exhausted for the current window. The Retry-After response header carries the number of seconds to wait. Wait exactly Retry-After seconds, then retry.
- INVALID_PARAM (400): A parameter failed validation. The message names the offending one. This is also what an unrecognised status filter value returns. Do not retry. Fix the request.
- INVALID_STATE_CODE (400): The state path segment or filter is neither a two-letter US state code nor an ISO 3166-1 alpha-3 country code. Do not retry. Fix the request.
- LICENSE_NOT_FOUND (404): No license record exists for the requested state. Usually an answer rather than a failure. Treat as not licensed there. Do not retry.
- INDIVIDUAL_NOT_FOUND (404): No individual exists with that ID at your company. Also returned when the person exists but their vertical is not switched on, deliberately, so the two are not distinguishable from outside. Do not retry. Re-list from GET /individuals.
- INTERNAL_ERROR (500, 503): Something failed on our side. 500 is an unexpected failure. 503 means Payna could not read your account entitlements, which is transient and is specifically not a 403. Retry with exponential backoff.

## Payna MCP server

A separate product from the REST API. Remote Model Context Protocol server so an AI assistant can answer one regulated person's own licensing and continuing-education questions.

Endpoint: https://app.payna.com/api/mcp
Authentication: OAuth 2.1 resource server. The customer's identity provider mints the bearer token; Payna only verifies it. It never accepts a pk_live_ API key on this endpoint.
Scope of data: the person the token identifies, not the whole company. Read only.

### MCP tools

- my_license_status (licenses:read.self): The caller’s own licences, status, and renewal dates.
- my_ce_requirements (ce:read.self): CE required, completed, and owed, per licence.
- my_deficiencies (licenses:read.self): Open licence items the regulator is waiting on.
- my_next_actions (both self scopes): One prioritised list of everything due.
- company_license_status (compliance:read.org): The licences the COMPANY itself holds — state, type, number, status, renewal.
- company_license_items (compliance:read.org): Open regulator items against those company licences.
- team_license_status (licenses:read.team): Every licensed person in the company — or, for a manager, in the branches they manage.
- org_compliance_summary (compliance:read.org): Counts across the individual roster. Never names anybody.

### MCP scopes

- licenses:read.self: The caller’s own license status and deficiencies.
- ce:read.self: The caller’s own continuing-education position.
- licenses:read.team: A branch manager’s view of their branch. Role-gated.
- compliance:read.org: A compliance admin’s org-wide summary. Role-gated.

## Products

- [Apply](https://payna.com/apply)
- [Officers](https://payna.com/officers)
- [Renewals](https://payna.com/renewals)
- [API](https://payna.com/api)
- [Firms](https://payna.com/firms)

## Industries

- [Mortgage](https://payna.com/mortgage)
- [Insurance](https://payna.com/insurance)
- [Lending](https://payna.com/lending)
- [Money Transmitter](https://payna.com/money-transmitter)

## Company

- [FAQ](https://payna.com/faq)
- [Security](https://payna.com/security)
- [Blog](https://payna.com/blog)
- [Contact](https://payna.com/contact)