API Reference
Log In
API Reference

One stop setup for I9Center V2

post
https://services.fountain.com/api/serviceemployment/processes/i9center/setup
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Request body for I9Center setup endpoint. This endpoint configures I-9 and W-4 form processing for a company. All fields are optional. If omitted, sensible defaults will be applied. The endpoint will create or update the company's onboarding provider configuration with Workbright as the default provider for both I-9 and W-4 forms. MULTI-EIN SUPPORT: By default, the system creates one Workbright credential per EIN when multiple EINs are configured. Each Workbright credential is linked to its EIN, and the default EIN's Workbright credential is marked as the default credential. To override this behavior and use a single shared Workbright credential for all EINs, set useOneWbCredentialForAllEin=true or provide manual Workbright credentials (wbApiKey). If hireAccountUuid is provided, the system will configure Fountain Hire integration using the provided hireAccountUuid and PAPI credentials. PAPI credentials (papiAccountUuid, papiAccountApiKey, partnerGatewayBaseUrl) can be optionally provided in the request body. If not provided, the system will use default PAPI credentials. If hireAccountUuid is not provided, PAPI setup will be skipped and hirePapiSettings will not be set in the configuration. This is designed for one-call setup by AI agents, allowing flexibility to customize PAPI credentials per company or use system defaults. AI OUTPUT RULE FOR UPDATE REQUESTS: build a MINIMAL PATCH only. Include ONLY fields explicitly provided by the user in the current request. Do NOT infer/backfill from prior messages or fetched data. Do NOT send empty string, null, undefined, default false, or unchanged values unless explicitly requested.

boolean

Enable E-Verify integration. E-Verify is an internet-based system that compares information from an employee's Form I-9 to data from U.S. government records to confirm employment eligibility. When enabled, the system will automatically verify new hires through E-Verify. Set to true to enable E-Verify, false to disable, or omit to use the default (false).

skipEVerifyStates
array of strings

List of U.S. state codes (two-letter abbreviations) where E-Verify should be skipped, even if eVerifyEnabled is true. This is useful for states that have restrictions on E-Verify usage or when certain states should be excluded from verification. Each element should be a valid two-letter state code (e.g., "CA", "NY", "TX").

skipEVerifyStates
skipEVerifyByJobs
array of strings

List of job UUIDs where E-Verify should be skipped. This allows you to exclude specific job positions from E-Verify verification. Each element should be a valid UUID string. Useful when certain job types or positions should not be subject to E-Verify requirements.

skipEVerifyByJobs
boolean

When true, keeps the I-9 task in "in progress" status until Section 2 of the I-9 form is completed. Section 2 is the employer verification section that must be completed within 3 business days of the employee's start date. This setting ensures the task remains active until the employer completes their portion. Set to true to enable this behavior, false to allow task completion after Section 1, or omit to use the default (false).

boolean

When true, automatically resets the I-9 form when worker information changes (e.g., name, date of birth, SSN). This ensures I-9 forms stay current with worker data. Set to true to enable automatic resets, false to disable, or omit to use the default (false).

boolean

When true, automatically resets the I-9 form when a worker is rehired. This ensures a fresh I-9 is completed for each new employment period. Set to true to enable automatic resets on rehire, false to disable, or omit to use the default (false).

boolean

When true, automatically resets the W-4 form when a worker is rehired. This ensures workers can update their tax withholding preferences for each new employment period. Set to true to enable automatic resets on rehire, false to disable, or omit to use the default (false).

string
enum

The provider service to use for importing worker data into the onboarding system. Use "hire" to enable Hire.com integration, "none" to disable worker imports, or omit to use the default (none).

Allowed:
boolean

Enable state tax reciprocity for W-4 forms. When enabled, the system will handle state tax reciprocity agreements where workers who live in one state but work in another may be exempt from withholding in the work state. Set to true to enable reciprocity handling, false to disable, or omit to use the default (true).

string

The W-4 group code used for organizing and categorizing W-4 forms. This is typically a company-specific code used for internal tracking and reporting. Should be a short alphanumeric string. If not provided, defaults to "AFPU".

string
length between 64 and 64

The Workbright API key for authenticating API requests to Workbright services. Must be exactly 64 hexadecimal characters (0-9, a-f, A-F). This key is required to communicate with Workbright for I-9 and W-4 form processing. The key will be encrypted before storage. If not provided, a placeholder key will be used for testing purposes.

string
length ≥ 1

The Workbright subdomain for your organization's Workbright instance. This is the unique identifier that appears in your Workbright URL (e.g., if your URL is "company.workbright.com", the subdomain is "company"). Required for connecting to the correct Workbright account. If not provided, defaults to "fountain-sandbox" for testing.

string

The Workbright provider domain suffix. This is typically ".workbright.fountain.com" for Fountain-managed Workbright instances. Used to construct the full Workbright API endpoint URL. If not provided, defaults to ".workbright.fountain.com".

string

The default employee ID to use when creating new employee records in Workbright. This is used as a fallback when no specific employee ID is provided. Typically set to "1" or another default identifier. If not provided, defaults to "1".

uuid

OPTIONAL: The Hire account UUID that identifies the Fountain Hire account to connect with this onboarding provider configuration. This is the external account identifier from Fountain Hire that will be used for worker data import (PAPI Partner API) and synchronization. If provided, the system will configure fountainHire settings along with PAPI credentials. If not provided, PAPI setup will be skipped and hirePapiSettings will not be set in the configuration and WX I9 Center will be configured without Hire.

uuid

OPTIONAL: The PAPI account UUID for authenticating with Hire.com's Partner API. This is the external PAPI account identifier in Hire.com used for partner API authentication. If not provided, the system will use default PAPI credentials. Provide this value if you need to use a specific PAPI account for this company.

string

OPTIONAL: The PAPI account API key for authenticating API requests to Hire.com's Partner API. This key is required to communicate with Hire.com for worker data import and synchronization. If not provided, the system will use default PAPI credentials. Provide this value if you need to use a specific PAPI API key for this company.

uri

OPTIONAL: The base URL for the Hire.com Partner Gateway API. This is the endpoint used to update partner status and details in Hire.com. Typically this is the partners API base URL (e.g., "https://partners-api.fountain.com/"). If not provided, the system will use the default Partner Gateway URL. Provide this value if you need to use a specific Partner Gateway endpoint for this company.

boolean

OPTIONAL: When true, prevents workers from being redirected to Hire.com even when they book a Section 2 appointment (video call or on-site appointment). Section 2 is the employer verification section of the I-9 form. This setting allows you to keep workers on the portal instead of redirecting them to Hire.com for Section 2 completion. Set to true to lock workers on the portal, false to allow redirects, or omit to use the default (false).

integer
> 0

OPTIONAL: The duration in minutes for worker access tokens. This determines how long a worker's authentication token remains valid before they need to refresh it. Longer durations provide better user experience but may pose security risks. Shorter durations are more secure but may require workers to re-authenticate more frequently. If not provided, defaults to 30 minutes.

papiStageSettings
array of objects

OPTIONAL: Array of PAPI stage settings that define which onboarding tasks are available and how they are configured. Each entry specifies a task type (I-9, W-4, or combined) and its corresponding identifier. If not provided, the system will use default PAPI stage settings that include I-9, W-4, and combined I-9 and W-4 options. This allows you to customize which onboarding tasks are available for workers.

papiStageSettings
boolean

When true, uses a single shared Workbright credential for all EINs. When false (default), creates one Workbright credential per EIN. Ignored if manual Workbright credentials (wbApiKey) are provided.

everifyAccountsByEin
array of objects

Optional array of E-Verify account entries. Each entry has everifyAccount (partial for update, full for create) and optionally einUuid. If einUuid is provided, it must match one of the company's EINs and the E-Verify account is applied to that EIN's Workbright credential. If einUuid is omitted, the E-Verify account is applied to the default Workbright credential (used when the company has no EINs or a single shared credential). Decision rule: web_service_password present => CREATE payload, web_service_password absent => UPDATE payload. For UPDATE, send MINIMAL PATCH only (only explicit user-provided changed fields). Never include remembered/default/unchanged fields. Failures are reported in everifyAccountUpdates.failed (use "default" as einUuid in the response when the entry had no einUuid) and do not fail the overall setup.

everifyAccountsByEin
registrationInfosByEin
array of objects

Optional array of registration information object per EIN. Each entry specifies an EIN UUID (must match one of the company's EINs) and an optional partial registration information. Missing fields are inferred from the existing EIN registration information or set to sensible defaults. Failures (e.g. EIN not found) are reported in the response (registrationInfoUpdates.failed) and do not fail the overall setup.

registrationInfosByEin
Response

Updated 21 days ago

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 21 days ago