fillPdf (POST)

The fillPdf endpoint accepts a json object containing employee information, employer information, and the answers to the form questions. The endpoint validates and processes the data and returns a completed PDF in base 64 format along with the relevant tax parameters for the form. Validation is done using the regular expressions provided in the question sets and validation of question dependencies is performed.

Form Versions

Specifying a form version can be done by adding formVersion to the outer object of your request. This is an optional attribute and if not included, the endpoint will expect the latest form version input parameters. If a form version is not specified we will return a warning message of the reasons why specifying a form version is best practice. In addition this is the same place we will send back a warning if a form has now been deprecated.

You can collect all the relevant input parameters of a particular form version and the currently supported versions from the ​getPdf​/{formId} (GET) endpoint.

Example Request

{ 
  "formId": "AL101", 
  "employee": { 
    "firstName": "John", 
    "lastName": "Smith", 
    "socialSecurityNumber": "123-45-6789", 
    "address": { 
      "streetAddress1": "11 S Union St", 
      "city": "Montgomery", 
      "state": "AL", 
      "zipCode": "36130" 
    } 
  }, 
  "employer": { 
    "name": "Symmetry", 
    "federalEIN": "98-7654321", 
    "telephoneNumber": "456-867-5309", 
    "address": { 
      "streetAddress1": "64 N Union St", 
      "city": "Montgomery", 
      "state": "AL", 
      "zipCode": "36130" 
    } 
  }, 
  "signForm": "PREVIEW", 
  "fields": { 
    "filingStatus": "SINGLE", 
    "dependents": 1 
  } 
}

Example Response

{ 
  "form": "AL101", 
  "pdf": "JVBERi0xLjYKJfbk/...”, 
  "taxParameters": [ 
  { 
    "id": "AL.dependents", 
    "value": "1" 
  }, 
  { 
    "id": "AL.filingStatus", 
    "value": "S" 
  }, 
  ... 
]

In the response we send back we have three objects (form, pdf, and taxParameters).

1. form will return a string of the forms id.
2. pdf will return a complete pdf in base 64 format. When decoded will produce a filed out pdf.
3. taxParameters will return an array of objects with two keys (id and value).

• id will represent a single tax parameter name in the form of a string.
• value will represent the associated value in the form of a string.

It is important to note the taxParameters object consists of all the values that will be needed for a payroll system to properly calculate payroll taxes.

Form Signing Options

The fillPdf endpoint has a signForm attribute as part of the API request. The signForm will accept three different values: PREVIEW, SIGN, SIGN_EXTERNALLY. The default value is PREVIEW.

PREVIEW: this is used to produce an un-signed preview of the form. In this mode, the SSN will be masked and all form fields will be flattened.

SIGN: this is used to produce a completed and fully executed form. When this option is set, the signature line on the form will include the employee's name, a date/time stamp, and the SSN will be unmasked. All form fields will be flattened.

SIGN_EXTERNALLY: this is used to produce a completed form with an unmasked SSN and without an electronic signature or date. This can mode can be used if an external signature process or tool like DocuSign is desired to produce a fully executed form. This mode flattens all fields on the PDF except for the signature and date fields.

If using an external signing platform there are some important details to note.

1. Most forms use two field ids for signature and date. The signature field uses the id signatureLine and the date field uses the id date
2. A few forms use nonstandard signatures. These are the MO101, MO102, MO103, and the NJ102.

• The MO101, MO102, and MO103 forms use a signature field with the id signatureLine and three date fields with the ids date_month, date_day, and date_year

• For the NJ102 form, two signature fields with the ids; signatureLine_1, signatureLine_2 and two date fields with the ids date_1 and date_2.

📘

Timezones

The fillPdf endpoint may be passed a timezone in the headers, as the Timezone header, of the request to specify the timezone that should be used when signing and dating a completed form. Specified timezones will only be used if signForm is set to SIGN. If no value is passed with the request, then the API with default to UTC.

Information on accepted Timezone IDs can be found here.

📘

Federal values

Several states use the Federal W4 for state purposes and have various requirement surrounding whether employees can diverge from values declare on the Federal W4 for state withholding. Values for federal values correspond to the W4101 tax parameter values.

The API provides functionality to allow captured federal values be applied to CO101, NM101, ND104, and UT101.

The following federal values are allowed:

• filingStatus
• isExempt
• isNonResidentAlien
• twoJobs
• additionalWithholding
• dependentsAmt
• deductions
• otherIncome

Example using federal values for form NM101:

JSON

{
  "formId": "NM101",
  "employee": {
    "firstName": "John",
    "lastName": "Smith",
    "socialSecurityNumber": "123-45-6789",
    "address": {
      "streetAddress1": "11 S Union St",
		"city": "Montgomery",
		"state": "AL",
		"zipCode": "36130"
    }
  },
  "employer": {
    "name": "Symmetry",
    "federalEIN": "98-7654321",
    "telephoneNumber": "456-867-5309",
    "address": {
    	"streetAddress1": "64 N Union St",
		"city": "Montgomery",
		"state": "AL",
		"zipCode": "36130"
    }
  },
  "signForm": "PREVIEW",
  "fields": {
  	"adjustFederalValues": "false"
  },
  "federalValues": {
      "filingStatus": "SINGLE_OR_MARRIED_FILING_SEPARATELY",
      "isExempt": "false",
      "isNonResidentAlien": "false",
      "twoJobs": "false",
      "additionalWithholding": 25,
      "dependentsAmt": 0,
      "deductions": 0,
      "otherIncome": 0

  }
}