Technical Reference

Neut Widget Customer Reference

Use this reference after the quickstart is working. It lists supported widget IDs, query variables, subject values, status filters, colorways, and bootstrap URL parameters.

Start with Customer Widget Quickstart if you have not set up the iframe and backend endpoint yet.

Widget IDs And Paths

Widget	`widget_id`	Hosted path
Bill Preview	`bill-preview`	`/bill-preview-embed.html`
Vote Ledger	`vote-ledger`	`/vote-ledger-embed.html`
Legislation Log	`legislation-log`	`/legislation-log-embed.html`

The production widget origin is:

https://widgets.neut.us

Common Variables

Every widget request uses these fields:

`widget_id`

Type: string
Required: Yes

Must match one of the supported widget IDs.

`instance_id`

Type: string
Required: Yes

Unique per widget instance on the page. Use only letters, numbers, dot, underscore, colon, or hyphen. Maximum 128 characters.

`article_id`

Type: string
Required: No

Useful for customer analytics or tracing.

`colorway`

Type: string
Required: No

Defaults to Default.

Do not include tenant_key in the browser payload. The customer backend should read the tenant from server configuration.

Bill Preview

Use this widget when the page is about a specific bill. Bill preview supports two sources:

congress (default when source is omitted)
state

Shared Bill Preview Fields

`widget_id`

Type: string
Required: Yes
Example: bill-preview

Fixed value.

`instance_id`

Type: string
Required: Yes
Example: bill-preview-article-123-main

Unique widget placement ID.

`article_id`

Type: string
Required: No
Example: article-123

Customer tracing value.

`source`

Type: string
Required: No
Example: congress

Omit or send congress for federal bills. Send state for state bills.

`colorway`

Type: string
Required: No
Example: Default

Optional style selection.

Congress Bill Preview Fields

Required when source is omitted or source=congress:

`bill_type`

Type: string
Required: Yes
Example: HR

Supported values: HR, S, HRES, SRES, SCONRES, HCONRES, HJRES, SJRES.

`bill_number`

Type: integer
Required: Yes
Example: 1

Positive bill number.

`congress`

Type: integer
Required: Yes
Example: 119

Positive Congress number. Currently only the 119th Congress is supported.

`temp_text_url`

Type: string
Required: No
Example: https://www.congress.gov/119/bills/hr1/BILLS-119hr1ih.pdf

Congress-only HTTPS fallback bill text URL for same-day coverage.

`temp_title`

Type: string
Required: No
Example: Sample Bill Title

Congress-only fallback title for same-day coverage.

Example hosted URL query string:

source=congress&bill_type=HR&bill_number=1&congress=119

temp_text_url and temp_title are fallback values for newly introduced Congress bills. Use them when a story embeds a bill on the same day it is introduced and official Congress data may not be available to Neut yet. They are not used for state bill previews.

State Bill Preview Fields

Required when source=state:

`source`

Type: string
Required: Yes
Example: state

Enables state bill preview mode.

`state`

Type: string
Required: Yes
Example: CA

Two-letter state or territory code.

`bill_identifier`

Type: string
Required: Yes
Example: AB 123

Full visible bill identifier. URL-encode spaces in the final iframe URL, for example AB%20123.

`session`

Type: string
Required: No
Example: 2025

Legislative session identifier. Omit to let the backend resolve the latest known session.

Example hosted URL query string:

source=state&state=CA&bill_identifier=AB%20123&session=2025

State bill previews render the public state preview card: title or bill label, optional subject or subject-list chips, summary, latest action, sponsor, official state link when available, optional bill text link when pdfTextUrl is present, and paginated cosponsors when the live widget loads them. No additional customer embed params are required for state cosponsors; the host reuses the state code from the bill-preview embed URL.

Vote Ledger

Use this widget to show House roll call votes for a representative, or a general House roll call feed when you do not want to target a single member.

`widget_id`

Type: string
Required: Yes
Example: vote-ledger

Fixed value.

`instance_id`

Type: string
Required: Yes
Example: vote-ledger-lofgren-ca-18

Unique widget placement ID.

`article_id`

Type: string
Required: No
Example: member-votes-001

Customer tracing value.

`member_type`

Type: string
Required: Conditional
Example: Representative

Must currently be Representative when targeting a single member. Omit together with the other member fields for a general House roll call feed request.

`last_name`

Type: string
Required: Conditional
Example: Lofgren

Member last name. Required only when targeting a single member.

`state_code`

Type: string
Required: Conditional
Example: CA

Two-letter state code. Required only when targeting a single member.

`district`

Type: integer
Required: Conditional
Example: 18

Optional disambiguation for House members. Only valid with member_type=Representative. Use null for at-large representatives.

`congress`

Type: integer
Required: Yes
Example: 119

Positive Congress number. Currently only the 119th Congress is supported.

`page`

Type: integer
Required: No
Example: 1

Defaults to 1 in the browser/backend examples. Final iframe URL should include it.

`limit`

Type: integer
Required: No
Example: 5

Defaults to 10 in the browser/backend examples. Final iframe URL should include it.

`colorway`

Type: string
Required: No
Example: Paper

Optional style selection.

If you provide any member targeting fields, provide the full set: member_type, last_name, and state_code. Do not send partial member filters.

vote-ledger currently supports House roll call votes only. Senate recorded votes are not available in this widget yet.

Legislation Log

Use this widget on an issue or policy page. It supports three backend-backed modes:

congress (default when source is omitted): Congress parent-subject ledger or Congress saved custom subject filter
state: statewide state bill ledger

Existing Congress embeds may continue omitting source. New generated examples should include source=congress for clarity.

Shared Fields

`widget_id`

Type: string
Required: Yes
Example: legislation-log

Fixed value.

`instance_id`

Type: string
Required: Yes
Example: legislation-lofgren-health

Unique widget placement ID.

`article_id`

Type: string
Required: No
Example: health-legislation-001

Customer tracing value.

`source`

Type: string
Required: No
Example: congress

Omit or send congress for Congress mode. Send state for the state bill ledger.

`page`

Type: integer
Required: Yes
Example: 1

Positive page number.

`limit`

Type: integer
Required: Yes
Example: 10

Positive page size.

`colorway`

Type: string
Required: No
Example: WashedSage

Optional style selection.

Congress Parent Subject Fields

Required when source is omitted or source=congress and you are using a supported parent subject:

`congress`

Type: integer
Required: Yes
Example: 119

Positive Congress number.

`subject`

Type: string
Required: Yes
Example: Health & Social Welfare

Must match a supported parent subject, including All.

`status_filter`

Type: string
Required: Yes
Example: All

Must match a supported status filter.

Send exactly one of subject or custom_subject_filter_id. Do not send both.

Congress parent-subject URL example:

source=congress&congress=119&subject=Health+%26+Social+Welfare&status_filter=All&page=1&limit=10

Congress Custom Filter Fields

Required when source is omitted or source=congress and you are using a saved tenant custom subject filter:

`congress`

Type: integer
Required: Yes
Example: 119

Positive Congress number.

`custom_subject_filter_id`

Type: string
Required: Yes
Example: 550e8400-e29b-41d4-a716-446655440000

Tenant custom Congress subject filter UUID.

`status_filter`

Type: string
Required: Yes
Example: All

Must match a supported status filter.

Do not send subject with custom_subject_filter_id.

Congress custom-filter URL example:

source=congress&congress=119&custom_subject_filter_id=550e8400-e29b-41d4-a716-446655440000&status_filter=All&page=1&limit=10

Arbitrary free-text custom subjects are still not supported. custom_subject_filter_id refers only to saved tenant filters configured in Neut.

Optional Congress Member Targeting

Optional for Congress parent-subject and custom-filter requests:

`member_type`

Type: string
Required: Conditional
Example: Representative

Must be Representative or Senator when targeting a single member.

`last_name`

Type: string
Required: Conditional
Example: Lofgren

Member last name. Required only when targeting a single member.

`state_code`

Type: string
Required: Conditional
Example: CA

Two-letter state code. Required only when targeting a single member.

`district`

Type: integer
Required: Conditional
Example: 18

Optional disambiguation for House members. Only valid with member_type=Representative.

`show_subject_filter`

Type: boolean
Required: No
Example: false

Defaults to true for Congress parent-subject requests. Forced off for custom-filter and state requests.

`show_status_filter`

Type: boolean
Required: No
Example: false

Defaults to true for Congress requests. Forced off for state requests.

`show_member_hero`

Type: boolean
Required: No
Example: true

Optional display flag. Forced off for state requests.

If you provide any member targeting fields, provide the full set: member_type, last_name, and state_code. Do not send partial member filters.

State Bill Ledger Fields

Required when source=state:

`source`

Type: string
Required: Yes
Example: state

Enables state bill ledger mode.

`state`

Type: string
Required: Yes
Example: CA

Two-letter state code for the monitored state.

`subject`

Type: string
Required: Yes
Example: All

State mode does not support true subject filtering. Must be All.

`status_filter`

Type: string
Required: Yes
Example: All

State mode does not support status filtering. Must be All.

State mode must not include congress, member_type, last_name, state_code, district, or custom_subject_filter_id.

State mode hides subject/status filter controls in the widget UI. The backend ignores those filters and returns the most recent non-future state session with bill action data.

State bill ledger URL example:

source=state&state=CA&subject=All&status_filter=All&page=1&limit=10

Supported Subjects

Use one of these values for Congress subject:

All
Animals & Agriculture
Business & Trade
Crime
Culture and Society
Education
Energy & Conservation
Finance & Taxes
Geopolitics
Government Operations
Health & Social Welfare
Human, Civil, & Immigration Rights
Infrastructure & Housing
Labor & Employment
National Security & International Affairs
STEM

Supported Status Filters

Use one of these values for status_filter:

All
Introduced
With First Chamber
With Second Chamber
Presented to President
Became Law
Vetoed by President
Passed Resolutions

Supported Colorways

Use one of these values for colorway:

Default
Dark
Paper
WashedSage
Slate
MonoLight

Common aliases accepted by the hosted widgets include:

dark-mode
washed-sage
mono-light

Bootstrap URL Parameters

Your backend builds the final iframe URL. In addition to widget variables, the URL must include:

`tenant_key`

Source: Server config
Notes: WIDGET_TENANT_KEY.

`widget_id`

Source: Validated request
Notes: Must match the hosted path.

`customer_origin`

Source: Server config
Notes: HOST_ORIGIN; scheme and host only.

`bootstrap_timestamp`

Source: Server generated
Notes: Base-10 Unix timestamp in whole seconds.

`bootstrap_nonce`

Source: Server generated
Notes: Fresh random nonce for each embed URL.

`bootstrap_key_id`

Source: Server config
Notes: NEUT_MINT_KEY_ID.

`bootstrap_assertion`

Source: Server generated
Notes: HMAC assertion signed with NEUT_MINT_SECRET.

The hosted widget exchanges these bootstrap parameters with Neut. Do not put access_token, origin, timestamp, nonce, key_id, or signature legacy params in the iframe URL.

Parent Refresh Message

If the hosted widget detects an expired Neut widget session, it now sends a postMessage request to the parent page so your site can re-mint a fresh iframe URL and reauthenticate the widget.

Message shape:

{
  "type": "neut-widget-refresh-request",
  "widget": "bill-preview | vote-ledger | legislation-log",
  "instance_id": "your-widget-instance-id",
  "reason": "session_expired"
}

The message is posted from the iframe to the configured customer_origin. Your parent page should listen for this event, verify event.origin === "https://widgets.neut.us", verify the message shape, then replace or reload the iframe using a newly signed bootstrap URL.