State Unemployment Insurance (SUI)

State Unemployment Insurance (SUI) registration establishes an employer’s unemployment tax account with the state workforce agency. Partners use this flow to order employer account setup or related payroll-tax onboarding where SwyftFilings supports it via API.

When to use this flow

Use the standalone SUI service cart when your customer must register as an employer for unemployment tax in a specific state. Requirements vary widely by state.

Service slug and catalog

Call Get Service Carts and select the State Unemployment Insurance (or the name provided for your program).
Use that slug for configuration and order APIs.

Examples use state-unemployment-insurance. Replace with the slug from your environment.

API flow

Step	Method	Endpoint
1. List carts	GET	externalCart.index
2. Configuration and catalog	GET	externalCart.getCart
3. NAICS (if required)	GET	businessClassification.index
4. Create order	POST	order.store
5. Submit order (if required)	POST	order.submitOrder
6. Post-checkout (optional)	GET	order.getOrderPostCheckout
7. Get order (optional)	GET	order.getOrder

State-specific requirements (discovery)

API-driven configuration: For each target state, call Get Service Configuration with your SUI service slug and build the order using the returned input_fields and catalog.

input_fields return the baseline required and optional keys, types, and validation rules for the selected state and product. Additional inputs may be required during processing based on jurisdiction-specific or employer-specific conditions.
catalog lists line items with sku, name, price, and any applicable state-based fees or conditions.

Do not cache field keys across states without revalidating; requirements vary by jurisdiction.

Partners should design for a multi-step intake flow and not assume all required inputs will always be known at initial configuration.

SUI flows often require payroll start dates, officer SSN last four, or withholding elections. Do not assume parity with formation orders; render forms from input_fields dynamically.

Example: Get Service Configuration

GET {baseUrl}/service-carts/state-unemployment-insurance?service=state-unemployment-insurance
Authorization: Bearer {token}

Abbreviated response:

{
  "success": true,
  "data": {
    "name": "State Unemployment Insurance",
    "slug": "state-unemployment-insurance",
    "description": "Employer registration for state unemployment insurance.",
    "input_fields": [
      {
        "name": "Employer legal name",
        "key": "business_data.name",
        "type": "string",
        "description": "Legal name for tax accounts",
        "validation_rules": ["required"]
      },
      {
        "name": "State",
        "key": "business_data.formation_state",
        "type": "enum",
        "description": "State where SUI registration is required",
        "validation_rules": ["required", "exists:states,abbr"]
      }
    ],
    "catalog": [
      {
        "sku": "SF_SUI_EXAMPLE_SG_0",
        "name": "SUI Employer Registration",
        "item_type": "product",
        "has_gov_fee": true,
        "price": 199,
        "fees": {
          "CA": { "LLC": 0 }
        },
        "package": false
      }
    ]
  }
}

Example: Create order

POST {baseUrl}/orders
Authorization: Bearer {token}
Content-Type: application/json

{
  "service": "state-unemployment-insurance",
  "email": "[email protected]",
  "first_name": "Alex",
  "last_name": "Nguyen",
  "phone_number": "5551112222",
  "consent_sms": false,
  "business_data": {
    "name": "Acme Payroll LLC",
    "type": "LLC",
    "formation_state": "CA",
    "category": "541214",
    "address": "500 Howard St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105"
  }
}

Abbreviated response:

{
  "success": true,
  "data": {
    "message": "Order created successfully",
    "order_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012"
  }
}

Example: Submit order

{
  "order_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "skus": ["SF_SUI_EXAMPLE_SG_0"],
  "total_amount": 199.0,
  "payment_method_nonce": null,
  "service": "state-unemployment-insurance"
}

Jurisdiction

Set business_data.formation_state to the state where the employer is registering for unemployment insurance.

Use the keys returned by Get Service Configuration to determine how jurisdiction fields should be populated.

Fulfillment

Order processing: After creation or submission, SwyftFilings evaluates the order and begins registration.
Follow-up requirements: Additional information may be required during processing based on jurisdiction and employer details. These requirements often involve highly sensitive personally identifiable information (PII).
- To streamline this process and reduce implementation overhead, we recommend using the Swyft Customer Portal iframe This allows users to securely submit required information within a fully managed, SOC 2–compliant experience—eliminating the need for partners to build and maintain complex API integrations for handling sensitive data.
Webhooks: Use order_status_change and order_processing_status_change to track progress.
Completion: The order is complete once registration is successfully processed and account details are available.

Errors and edge cases

Sensitive data: Prefer capturing tax identifiers in the Customer Portal when input_fields mark them post-checkout rather than in initial API payloads, if your cart is configured that way.
Multi-state employers: Each state may require a separate order or SKU selection.

When to use this flow​

Service slug and catalog​

API flow​

State-specific requirements (discovery)​

Example: Get Service Configuration​

Example: Create order​

Example: Submit order​

Jurisdiction​

Fulfillment​

Errors and edge cases​