Quickstart: Launch your first hosted form

Symmetry Payroll Forms (SPF) Hosted runs on Symmetry’s infrastructure at spf.symmetry.com: there’s nothing to install or deploy. You can embed SPF in an iframe within your application, or redirect the employee’s browser directly to their SPF session with no iframe at all (see Step 5). Either way, Symmetry manages server uptime, form compliance, and UI rendering. This guide walks a new hosted client through submitting a first SPF Registration and confirming the integration end to end. For a comparison of API, Hosted, and On-Premise delivery, see Implementation types.

Before you begin

You’ll need your Profile Key to complete this guide. If you don’t have it, contact your Symmetry Account Manager or reach out through the Client Support Center. You’ll also need to decide between Choose Mode, where the employee selects forms directly, and Guided Mode, where SPF asks targeted questions to determine the employee’s required forms. See Form Modes for a full comparison. This guide covers both.

Admin Panel

See how your account’s default application settings are managed and how to request changes.

Settings Builder

Prototype and troubleshoot your SPF Registration without touching your own application.

Step 1: Access the download center

The Download Center is your starting point for CSS files and other resources tied to your account. Navigate to:

https://spf.symmetry.com/spf/download-center?profile=[YourProfileKey]

Bookmark this URL. You’ll return to it whenever you need to download updated CSS files or review other available resources.

Step 2: Review your settings in the admin panel

The Admin Panel defines your account’s default application settings: form modes, postback configuration, presentation options, and more. These are account-wide defaults: Symmetry has to make any change to them for you, via a support ticket, and the new default applies to every session going forward. Most of these same settings can also be set per session, by including them directly in your SPF Registration (see Step 5), no support ticket required. Use this when a specific employee or use case needs different behavior than your account default, without changing that default for everyone else. During initial setup, your Symmetry Account Manager works with you to configure sensible account-wide defaults based on your needs. To change a default after go-live, submit a support ticket.

Not sure whether something belongs in your account defaults or a per-session override? Use Settings Builder to prototype either approach before deciding.

Step 3: Prototype with settings builder

Settings Builder lets you generate a prototype SPF Registration, submit it to SPF, and receive a real Postback response, without touching your own application. Use it to validate settings, troubleshoot configurations, and explore the three form modes before you build. Access Settings Builder at:

https://spf.symmetry.com/spf/utility/settings-builder?profile=[YourProfileKey]

The tabs step you through each part of the SPF Registration:

Tab	What it does
Employee	Set employee information (name, SSN, federal values, PIN)
Employer Information	Set employer/company data
Resident Address	Select a resident address from a preconfigured test list
Work Addresses	Select one or more work addresses
Nexus and Lock In Letters	Configure nexus states and IRS lock-in letters (U.S. only)
Application Settings	Adjust form modes, postback, presentation, and more
Submit (generated)	Review the generated SPF Registration and submit it to SPF
Submit (custom)	Paste in your own SPF Registration and submit it directly

From either Submit tab, you can send the data to SPF three ways:

Submit: generates a URL with a valid token, used for iframe mode
Submit One Step: directs you to the Employee Withholding Resource Center, where Guided Mode and Choose Mode are available
Submit to Helper: directs you to Helper Pages with the submitted employee and employer data pre-populated

See Settings Builder for the full reference of every tab and field.

Step 4: Choose your form mode

SPF supports three form modes. Choose the one that fits your use case before building your SPF Registration:

Guided Mode

Ideal for employee onboarding. SPF guides employees through a survey (based on their resident and work address(es)) to determine the correct forms automatically.

Choose Mode

Ideal when employees know which forms they need. Presents a list of suggested forms for the employee to select from, based on the resident and work address(es) submitted in the SPF Registration.

Single Form Mode

Presents one specific form directly, regardless of address. Use when your workflow already knows which single withholding form is needed.

Both Guided Mode and Choose Mode can be enabled at the same time, giving employees the option to select Guide me or Let me choose. See Form Modes for configuration details and examples.

Step 5: Build your first SPF registration

The SPF Registration (also called the Registration Context) is the data you submit to SPF at the start of each employee session. It carries employee and employer data and your configuration settings. formSubmissionMode controls how SPF returns each completed form: "POSTBACK" sends the form’s JSON and PDF to an endpoint you control immediately after each submission, while "PRINT" has the employee print the form themselves instead. See Returning Forms/Form Data for the full payload reference. If you’re using Postback, your registration also needs to specify the endpoint where SPF should send that data. For SPF U.S., a registration must include two top-level elements (employee and workAddresses) plus a config element with formSubmissionMode set. employer is optional at the registration level; it’s required only when a recommended form needs it: this applies to some U.S. forms (for example, the Federal W-4) and no Canadian forms.

employee: name, resident address, and a uniqueIdentifier
employer: company name, FEIN, and address; required only when a recommended form needs it
workAddresses: at least one work address
config.formSubmissionMode: set to "POSTBACK" or "PRINT"
config.postback.target.url: required if formSubmissionMode is "POSTBACK"; the endpoint where SPF sends the completed form data

{
  "employee": {
    "firstName": "Jane",
    "lastName": "Smith",
    "uniqueIdentifier": "your-employee-id",
    "socialSecurityNumber": "000-00-0000",
    "address": {
      "streetAddress1": "123 Main St",
      "city": "Phoenix",
      "state": "AZ",
      "zipCode": "85001"
    }
  },
  "employer": {
    "name": "Acme Corp",
    "federalEIN": "000000000",
    "address": {
      "streetAddress1": "456 Commerce Blvd",
      "city": "Scottsdale",
      "state": "AZ",
      "zipCode": "85251"
    }
  },
  "workAddresses": [
    {
      "streetAddress1": "456 Commerce Blvd",
      "city": "Scottsdale",
      "state": "AZ",
      "zipCode": "85251"
    }
  ],
  "config": {
    "formSubmissionMode": "POSTBACK",
    "postback": {
      "target": {
        "url": "https://your-app.com/spf/postback",
        "authentication": {
          "authType": "NONE"
        }
      }
    },
    "guidedMode": {
      "enabled": true
    }
  }
}

You can submit this data to SPF in two ways. A one-step, client-side post directly to spf/register-forward is a plain HTML form submission: by default, it fully navigates the employee’s browser to their session, with no iframe involved. A two-step post to spf/register instead returns a token/URL in the response body: load that URL in an iframe, or navigate the employee’s browser to it directly. Sending the same data to spf/get-started instead pre-populates Helper Pages for the employee to review and complete. See SPF Registration for the full submission mechanics, and the SPF Schema & Complete List of SPF Elements for every available element.

Any element set by default in the Admin Panel can be overridden per session by including it in the SPF Registration with a different value.

Step 6: Customize the UI (optional)

SPF uses two CSS files (spf.css and spf-responsive.css) that you can override to match your company’s branding. Download spf-css.zip from the Download Center (see Step 1), then host your custom stylesheet and pass its URL in config.presentation.css in your registration.

{
  "config": {
    "presentation": {
      "css": [
        "https://your-cdn.com/your-custom-styles.css"
      ],
      "companyLogoSrc": "https://your-cdn.com/your-logo.png"
    }
  }
}

The config.presentation.css array must be included in every registration request. Presentation configuration is applied per session, not globally.

See CSS Selectors for the SPF UI for the full list of available classes, grouped by UI area.

Next steps

SPF registration

Every element available in the SPF registration, with submission mechanics and examples.

Core concepts overview

The model behind every SPF integration: forms, determination, and outputs.

More references:

​Before you begin

Admin Panel

Settings Builder

​Step 1: Access the download center

​Step 2: Review your settings in the admin panel

​Step 3: Prototype with settings builder

​Step 4: Choose your form mode

Guided Mode

Choose Mode

Single Form Mode

​Step 5: Build your first SPF registration

​Step 6: Customize the UI (optional)

​Next steps

SPF registration

Core concepts overview

Before you begin

Step 1: Access the download center

Step 2: Review your settings in the admin panel

Step 3: Prototype with settings builder

Step 4: Choose your form mode

Step 5: Build your first SPF registration

Step 6: Customize the UI (optional)

Next steps