Withholding Tax (standalone)

A withholding tax is an income tax deducted directly from a payment before the recipient receives it. Instead of the earner paying the government later, the payer—such as an employer or bank—retains the tax and remits it directly to the authorities. SwyftFilings offers Withholding Tax Service as a standalone service so partners can order it.

Related: Service Filings overview · State requirements reference

Service slug and catalog

1. Call Get Services and select the standalone Withholding Tax entry (is_standalone: true).
2. Use that slug for Get Service Configuration and Create New Order.

Examples use withholding-tax. Replace with the slug from your environment.

API flow

Step	Method	Endpoint
1. List services	GET	/service-carts
2. Configuration and catalog	GET	/service-carts/{service}
3. NAICS (if required)	GET	/business-classifications
4. Create order	POST	/orders
5. Get order (optional)	GET	/orders/{order_uuid}
6. Get timely Order status changes and Requests for Information on your Webhook

State-specific requirements (discovery)

API-driven configuration: For each target state, call Get Service Configuration with your Withholding Tax service slug for each state where the entity needs an agent. Build the order using the returned input_fields and catalog.

• input_fields return the baseline required and optional keys, types, and validation_rules for that state and product. Additional inputs may be required during processing based on jurisdiction-specific or filing-specific conditions.
• catalog lists line items with sku, name, price, optional fees by state, and conditions (for example incompatible SKUs).

Example: List services

GET {baseUrl}/service-carts
Authorization: Bearer {token}

{
  "success": true,
  "data": [
    {
      "slug": "withholding-tax",
      "name": "Withholding Tax",
      "description": "State employer withholding tax account registration.",
      "allows_addons": false,
      "is_standalone": true,
      "nested_services": []
    }
  ]
}

Example: Get Service Configuration

Request (replace {baseUrl}, {token}, and the slug):

GET {baseUrl}/service-carts/withholding-tax?state=TX&business_type=LLC
Authorization: Bearer {token}

Abbreviated success payload:

{
  "success": true,
  "data": {
    "name": "Withholding Tax",
    "slug": "withholding-tax",
    "description": "State employer withholding tax account registration.",
    "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_WHT_EXAMPLE_SG_0",
        "name": "Withholding Tax Registration",
        "item_type": "product",
        "has_gov_fee": false,
        "price": 149,
        "fees": {
          "CA": { "LLC": 0 }
        },
        "package": false
      }
    ]
  }
}

sku and field keys are illustrative; use live catalog and input_fields from your environment.

Example: Create order

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

{
  "service": "withholding-tax",
  "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": "e4f5a6b7-c8d9-0123-ef01-345678901234"
  }
}

Example: Submit order

{
  "order_uuid": "e4f5a6b7-c8d9-0123-ef01-345678901234",
  "skus": ["SF_WHT_EXAMPLE_SG_0"],
  "total_amount": 149.0,
  "payment_method_nonce": null,
  "service": "withholding-tax"
}

Example: Get order

GET {baseUrl}/orders/e4f5a6b7-c8d9-0123-ef01-345678901234
Authorization: Bearer {token}

Abbreviated response:

{
  "success": true,
  "data": {
    "id": 1,
    "uuid": "e4f5a6b7-c8d9-0123-ef01-345678901234",
    "service": "withholding-tax",
    "status": "In Progress",
    "business_data": {
      "name": "Acme Payroll LLC",
      "type": "LLC",
      "formation_state": "CA"
    },
    "managers_data": [],
    "order_items": [
      { "submitted_at": "2026-07-01", "type": "sale", "items": ["SF_WHT_EXAMPLE_SG_0"] }
    ],
    "required_actions": {
      "rejections": [],
      "questionnaires": [],
      "alerts": []
    },
    "documents": []
  }
}

Jurisdiction

Set business_data.formation_state to the state where Withholding Tax service is required.

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

Fulfillment

1. Order processing: After creation or submission, SwyftFilings evaluates the order and proceeds with service activation.
2. Follow-up requirements: In some cases, additional inputs may be requested during processing depending on the service configuration.
3. Webhooks: Use order_status_change to track progress.
4. Completion: The order is complete once Withholding Tax service is successfully filed.

Errors and edge cases

• 422 Validation: Field keys or values that fail validation_rules return errors keyed by field name.
• Entity type: Catalog conditions.applicable_biz_types may restrict certain SKUs to specific entity types.
• Additional requirements: Some requirements identified during processing may require follow-up submission.