---
title: "Get license for a specific state"
method: GET
path: "/licenses/{state}"
tags: ["Licenses"]
---

# Get license for a specific state

`GET /licenses/{state}`

## Request

- Base URL: `https://app.payna.com/api/v1`
- URL: `https://app.payna.com/api/v1/licenses/{state}`
- Auth: HTTP bearer

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.

## Path parameters

- `state` string, required

## Response `200`

License found.

- object
  - `data` License
    - `id` string, uuid, required: Unique license record ID.
    - `state_code` string, required: Two-letter US state code.
    - `license_type` string, required
    - `activity_type` 'lending' | 'debt_collection' | 'money_transmission' | 'mortgage' | 'other', required
    - `license_number` string, nullable
    - `nmls_id` string, nullable
    - `regulator` string, nullable
    - `status` 'active' | 'deficient' | 'pending' | 'applying' | 'not_licensed', required: 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 abandoned applications or "pending" for withdrawal-requested licenses; status_detail resolves those correctly.
    - `sub_status` string, nullable: 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).
    - `raw_status` string, nullable: Verbatim status string from the regulator.
    - `issued_date` string, date, nullable
    - `renewal_date` string, date, nullable: 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.
    - `days_until_renewal` integer, nullable: Days until the renewal date from today. Negative means the renewal date has passed without a recorded renewal.
    - `verified` boolean, required: Whether Payna has verified this license record with the regulator.
    - `verified_at` string, date-time, nullable
    - `jurisdiction_level` string, nullable
    - `filing_method` string, nullable
    - `updated_at` string, date-time, required: Last time this record was updated in Payna.
    - `status_detail` StatusDetail, required: Derived, machine-stable descriptor of the license status. Render per-state nuance off `code`/`category` instead of parsing `raw_status`. Always present and well-formed.
      - `code` 'licensed' | 'conditional_approval' | 'surety_bond_only' | 'deficient' | 'revoked' | 'suspended' | 'terminated_for_cause' | 'expired' | 'inactive' | 'application' | 'application_deficient' | 'application_incomplete' | 'under_review' | 'pending' | 'withdrawal_requested' | 'application_abandoned' | 'voluntary_withdrawal' | 'withdrawn' | 'surrendered' | 'terminated' | 'rejected' | 'denied' | 'no_license_needed' | 'in_state_office_required' | 'not_licensed' | 'unknown', required: Stable machine slug — safe to branch on.
      - `label` string, required: Human-readable label.
      - `category` 'active' | 'in_progress' | 'deficient' | 'exited' | 'not_pursued' | 'needs_review', required: Color bucket: active→green, in_progress→blue/amber, deficient→red, exited/not_pursued→gray, needs_review→amber.
      - `intentional` boolean, required: True when the unlicensed posture is deliberate (voluntary withdrawal / no-license-needed / in-state-office / surety-bond-only) — i.e. not a problem.
      - `is_nmls` boolean, required: False for state-portal (non-NMLS) jurisdictions such as TX/DE debt collection.
      - `portal` object, nullable, required: State portal for non-NMLS jurisdictions; null for NMLS or when there is no online portal.
        - `name` string
        - `url` string, nullable
        - `type` string, nullable
      - `source_text` string, nullable, required: Passthrough of the underlying raw_status.
  - `meta` object
    - `total` integer: Number of licenses held in the state; >1 means more are available via the list endpoint.
    - `synced_at` string, date-time

## Other responses

- `400`: Invalid state code.
- `401`: Unauthorized.
- `404`: No license record found for this state.
- `429`: Rate limit exceeded.
- `500`: Internal server error.

---

[API](https://skmtc.dev/payna/apis/payna-compliance-api.md) - [All operations](https://skmtc.dev/payna/apis/payna-compliance-api/llms.txt) - [OpenAPI document](https://skmtc.dev/payna/apis/payna-compliance-api/revisions/11ef1636c05a?raw)