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 Breakdown	`vote-breakdown`	`/vote-breakdown-embed.html`
Legislation By Subject	`legislation-by-subject`	`/legislation-by-subject-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_id 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.

`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.

`bill_type`

Type: string
Required: Yes
Example: HR

Supported values: HR, S, HRES, SRES, SCONRES, HCONRES, HJRES, and 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

HTTPS fallback bill text URL for same-day coverage.

`temp_title`

Type: string
Required: No
Example: Sample Bill Title

Fallback title for same-day coverage.

`colorway`

Type: string
Required: No
Example: Default

Optional style selection.

temp_text_url and temp_title are fallback values for newly introduced 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.

Vote Breakdown

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-breakdown

Fixed value.

`instance_id`

Type: string
Required: Yes
Example: vote-breakdown-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-breakdown currently supports House roll call votes only. Senate recorded votes are not available in this widget yet.

Legislation By Subject

Use this widget on an issue or policy subject page, either for a single member or for general legislation on that subject.

`widget_id`

Type: string
Required: Yes
Example: legislation-by-subject

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.

`member_type`

Type: string
Required: Conditional
Example: Representative

Must be Representative or Senator when targeting a single member. Omit together with the other member fields for a general subject 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.

`subject`

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

Must match a supported subject.

`status_filter`

Type: string
Required: No
Example: All

Defaults to All.

`show_subject_filter`

Type: boolean
Required: No
Example: false

Defaults to true if omitted by the final iframe URL.

`show_status_filter`

Type: boolean
Required: No
Example: false

Defaults to true if omitted by the final iframe URL.

`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: 10

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

`colorway`

Type: string
Required: No
Example: WashedSage

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.

Supported Subjects

Use one of these values for subject:

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_id`

Source: Server config
Notes: WIDGET_TENANT_ID.

`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-breakdown | legislation-by-subject",
  "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.