Skip to main content

State requirements reference

This page provides general guidance on how state and jurisdiction impact service requirements and how to integrate with Swyft’s API-driven configuration model.

For standalone services, final required inputs for a given order may be determined during fulfillment and surfaced through follow-up Rejections (Information Requests).

Use this page together with the standalone product guides, including Foreign Qualification, Withholding Tax, New Hire Reporting, Registered Agent (standalone) and SUI.

API-driven configuration​

SwyftFilings does not require partners to maintain a static copy of every field for every state in application code. Instead:

  1. List services — GET {baseUrl}/service-carts returns every service enabled for your account (slug, name, description, allows_addons, is_standalone).
  2. Load configuration — GET {baseUrl}/service-carts/{service} with your product's slug, optionally scoped with state and business_type query parameters.
  3. Read input_fields — Returns the complete list of required keys, validation rules, and descriptions for the selected service and state combination.
    • Additional inputs may be required during processing based on jurisdiction-specific or filing-specific conditions.
    • Some fields are only required depending on the answer to another field. When present, an input_fields entry carries a conditional_required object instead of (in addition to) a flat required: true — for example, the Foreign Qualification "Alien Affiliates" fields: 
      {
        "key": "alien_affiliates_data.*.name",
        "required": false,
        "conditional_required": {
          "field": "state_specific.has_alien_affiliates",
          "values": [true]
        }
      }
      This means alien_affiliates_data.*.name only needs to be submitted when state_specific.has_alien_affiliates is sent as true — order creation returns a 422 on that field otherwise. Use conditional_required to drive conditional show/require behavior in your own UI.
    • Some fields are instead gated on whether another field was answered at all, rather than on a specific answer value. These carry an operator: "filled" alongside an empty values array — for example, Hawaii's county liquor license fields: 
      {
        "key": "state_specific.county_liquor_license_number",
        "required": false,
        "conditional_required": {
          "field": "state_specific.liquor_tax_start_date",
          "operator": "filled",
          "values": []
        }
      }
      This means state_specific.county_liquor_license_number only needs to be submitted once state_specific.liquor_tax_start_date has been answered with any value — order creation returns a 422 on that field if it's missing once the date is set.
    • Some fields are gated on any one of several different sibling fields, rather than a single one. These carry an any array instead of a top-level field/values — for example, Delaware's State Unemployment Insurance multi-state employee fields: 
      {
        "key": "employees_multi_state_data.*.work_states",
        "required": false,
        "conditional_required": {
          "any": [
            { "field": "state_specific.de_primary_work_state_flag", "values": [true] },
            { "field": "state_specific.de_partial_work_in_state", "values": [true] }
          ]
        }
      }
      This means employees_multi_state_data.*.work_states only needs to be submitted when either state_specific.de_primary_work_state_flag or state_specific.de_partial_work_in_state is sent as true — each entry in any uses the same field/values/operator shape as a top-level condition.
  4. Read catalog — SKUs, price, state-specific fees, and conditions for that jurisdiction.
GET {baseUrl}/service-carts/foreign-qualification?state=TX&business_type=LLC
Authorization: Bearer {token}
{
  "success": true,
  "data": {
    "name": "Foreign Qualification",
    "slug": "foreign-qualification",
    "input_fields": [
      {
          "name": "First Name",
          "key": "first_name",
          "type": "string",
          "description": "First name of the user",
          "questionnaire_copy": "What is your first name?",
          "validation_rules": [
              "string",
              "max:100",
              "regex:/^[\\p{L}]+([\\s\\-'.]*[\\p{L}]+)*\\.?$/u"
          ],
          "default_value": null,
          "options": null,
          "is_sensitive": false,
          "required": true
      },
      {
          "name": "Last Name",
          "key": "last_name",
          "type": "string",
          "description": "Last name of the user",
          "questionnaire_copy": "What is your last name?",
          "validation_rules": [
              "string",
              "max:100",
              "regex:/^[\\p{L}]+([\\s\\-'.]*[\\p{L}]+)*\\.?$/u"
          ],
          "default_value": null,
          "options": null,
          "is_sensitive": false,
          "required": true
      },
      {
          "name": "Email",
          "key": "email",
          "type": "string",
          "description": "Email address",
          "questionnaire_copy": "What is your email address?",
          "validation_rules": [
              "email:rfc,dns",
              "max:255"
          ],
          "default_value": null,
          "options": null,
          "is_sensitive": false,
          "required": true
      },
      {
          "name": "Phone Number",
          "key": "phone_number",
          "type": "string",
          "description": "Phone number",
          "questionnaire_copy": "What is your phone number?",
          "validation_rules": [
              "string",
              "size:10",
              "regex:/^(?![01])\\d+$/"
          ],
          "default_value": null,
          "options": null,
          "is_sensitive": false,
          "required": true
      },
      ...
    ],
    "catalog": [
      { "sku": "SF_FQ_EXAMPLE_TX_0", "name": "Foreign Qualification", "item_type": "product", "has_gov_fee": true, "price": 75, "package": false }
    ]
  }
}

Repeat the configuration call whenever the user changes the target state or product mix. Government fees and required disclosures update with catalog and input_fields.

Which field is "the state"? Most products key their state-gated input_fields and catalog off business_data.formation_state. Foreign Qualification is the exception — its jurisdiction field is state_of_foreign_qualification (the state the FQ filing is being requested in). business_data.formation_state is still required and stored on FQ orders as the entity's home state, but it does not drive FQ's state-specific requirements.

Some important attributes:

  • is_sensitive means that we need to treat this field as PII (Personal Information)
  • questionnaire_copy holds a question (in English) that correctly refers to the field.

Jurisdiction: all 50 U.S. states​

Partners must pass a USPS two-letter state code for the state where the filing or registration applies (foreign qualification state, registered agent state, or SUI employer state). The table below is the canonical list of codes to use in API payloads and validation.

CodeStateCodeState
ALAlabamaMTMontana
AKAlaskaNENebraska
AZArizonaNVNevada
ARArkansasNHNew Hampshire
CACaliforniaNJNew Jersey
COColoradoNMNew Mexico
CTConnecticutNYNew York
DEDelawareNCNorth Carolina
FLFloridaNDNorth Dakota
GAGeorgiaOHOhio
HIHawaiiOKOklahoma
IDIdahoOROregon
ILIllinoisPAPennsylvania
INIndianaRIRhode Island
IAIowaSCSouth Carolina
KSKansasSDSouth Dakota
KYKentuckyTNTennessee
LALouisianaTXTexas
MEMaineUTUtah
MDMarylandVTVermont
MAMassachusettsVAVirginia
MIMichiganWAWashington
MNMinnesotaWVWest Virginia
MSMississippiWIWisconsin
MOMissouriWYWyoming

Note: Washington, D.C. and U.S. territories may use different codes or flows; confirm with your SwyftFilings representative if your customers require filings outside the 50 states.

Exceptions and manual filings​

Some states may impose temporary filing restrictions, expedited options, or manual review steps. If Get Service Configuration returns an error for a state or omits expected SKUs, treat that jurisdiction as unavailable in the current release and contact [email protected].

Fulfillment reminders​

  • Webhooks: Webhooks for status changes.