Skip to main content

Legal

Tax & Accounting

Trade & Supply

Risk & Fraud

News & Media

Books

Developers

SurePrep API - Binder use cases

Use API to create binders for GoSystem Tax RS

Use SurePrep's API to create binders for GoSystem Tax RS clients.
Review the full binder creation flow chart using API.
Additionally, you can enable firm-level options to save you time from:
  • Manually creating a client in the tax software.
  • Manually rolling over prior year clients in the tax software.
You can enable a firm-level option to create a new client in GoSystem Tax RS automatically on your behalf. If you don't provide a valid Tax Client ID/Locator Number when creating a binder, SurePrep will create a new Client Number/Locator in the linked tax software. With this firm-level option, users can use our
CreateBinder
 API call to create their clients' binders and automatically create the client in the tax software.
Furthermore, you can enable another firm-level option to proforma the client automatically from the prior tax year into the current tax year automatically if the locator number is found in the prior tax year.

Benefits of creating binders via API

Using SurePrep's API, GoSystem Tax RS users can automate the process of:
  • Creating their clients' binders into their workflow
  • Automatically upload TaxCaddy documents to binders
  • Linking binders to existing client accounts in TaxCaddy
  • Uploading new documents to an existing binder
Without the use of SurePrep's API, firm users would need to sign into their accounts to create, upload documents to, and submit each client's binder individually.

Before you begin

To utilize the full functionality of SurePrep's API for GoSystem users when creating and maintaining your clients' binders, we recommend enabling the following firm-level options:
(Optional) Firm-level Options
Description
Auto-creation of a valid Locator No. when necessary
* Optional firm-level option
SurePrep API will automatically generate a new 
Locator No.
 if either:
  • An invalid
    Locator No.
    : the locator number doesn't exist.
  • A 
    Locator No.
     isn't provided in the API call.
This newly generated
Locator No.
 can be found in the tax software.
Automatically roll forward a client's prior year records
* Optional firm-level option
Based on the
Locator No.
, if you can't locate a client in GoSystem Tax RS for the current year, SurePrep will check the previous tax years, then import the previous year's records as proforma data.
Ability to replace records imported from a prior year.
* Optional firm-level option
If a client's records imported from a previous year are no longer accurate, you can replace this information to update your client's records correctly. These fields include:
Taxpayer
 and
Spouse Names
/
SSNs
,
Filing Status
, and
Home State
.
Auto-link (API) binder with TaxCaddy client profile
* Optional firm-level option
Automatically links the newly (API) created binder with a TaxCaddy client profile with a matching 
Tax Client ID
 (that is, Locator No.). 
Auto-upload TaxCaddy documents to (API) binder
* Optional firm-level option
Automatically uploads TaxCaddy documents marked with the 
Include in binder
  document flag to the binder, saving time from manually uploading documents to the binder. 
Contact SurePrep Support to have any of the previous API features enabled for your firm.

Use SurePrep API to create GoSystem Tax RS binders

To create a binder for a client, use the following API Methods in the following order:
  1. CreateBinder
         : Creates a new binder for the specified client when all the relevant identifying information is provided (for example,
    Service Type
    ,
    Email
    , and
    Office Location
    ). Review the full binder creation flow chart.
  2. UploadBinderDocuments
         : Adds documents to the binder once it's created. Unless you enable the Auto-Upload feature for your firm, you'll need to call this method individually for every document you need to add to a binder.
  3. SubmitBinder
         : Submits the binder. Use this method once you upload all documents to SurePrep.
How is a new client record created or rolled over from the prior year?
When using SurePrep's
CreateBinder
 API call to create a client's binder, we refer to the Locator Number in the
locator_No
 field to map the new API call to the correct client. However, there may be some cases in which a valid Locator Number hasn’t been provided in the API call (no
Locator No.
 has been provided in the API call).
When this happens, the API generates a new Locator Number for the client you've specified. You can refer to this client's record in FileRoom to review their newly generated Locator Number before performing API calls for this client's binder.
The client with a newly-created Locator Number will have any missing records populated with placeholder data until you save the client's correct information. This placeholder information will apply to the following fields:
  • Taxpayer
    First
     and
    Last Name
  • Spouse
    First
     and
    Last Name
  • Taxpayer and Spouse
    SSN
  • Filing Status
  • Home State
For clients who don’t require a newly generated Locator Number (the Locator number provided correctly maps to that client via the
unique_Identifier
), any information already saved to their record from the prior tax year will import to their records for the current tax year.
If the client's prior year information is no longer accurate (for example,
Filing Status
 or
Last Name
 updates after getting married), you can use the SurePrep API to update this information to reflect your client's personal information correctly.
Input parameters changes for GoSystem Tax RS
When creating a binder for GoSystem Tax RS, you need to provide all the required fields listed in the developer portal for the
CreateBinder
 method.
However, for GoSystem Tax RS, SurePrep API requires some fields in a specific format. These details are currently not provided in the developer portal. Use the following format for the following API input parameters:
Changed input parameter for the 'CreateBinder' method
Description
Required
Sample Data
filing_Status
(String) The following are the accepted filing status values when using API with GoSystem Tax RS:
  • X
     = Single
  • B
     = Married Filing Jointly
  • C
     = Married Filing Separately
  • D
     = Head of Household
  • E
     = Qualifying widow(er)
No
B
accountNumber
(String) Tax software account number. Maximum limit of 4 characters (alphanumeric values).
No
100A
Locator_pwd
(String) If the client is password protected in the tax software, provide the password in this input parameter, else the binder will be stuck in error. Maximum limit of 9 characters.
No
password1

Default placeholder values

When you call the
CreateBinder
 method, if your client doesn't exist in the tax software, SurePrep will create a client using the input parameter for first name (
first_Name
) and last name (
last_Name
). However, If the API input parameters aren't provided for these optional fields, SurePrep will use the following placeholder values.
Field name
Placeholder value
Taxpayer's First Name (
first_Name
)
Saved as "Taxpayer" by default.
Taxpayer's Last Name (
last_Name
)
Saved as "Taxpayer" by default.
Taxpayer's SSN (
taxPayer_SSN
)
Saved as "111-11-1111" by default.
Taxpayer's Filing Status (
filing_Status
)
Saved as "X" (single) by default.
Home State (
homeState
)
Saved as "XX" (unspecified) by default.
Spouse's First Name (
spouseFirstName
)
Saved as "Spouse" by default.
Spouse's Last Name (
spouseLastName
)
Saved as "Spouse" by default.
Spouse's SSN (
spouse_SSN
)
*Only applies if the taxpayer's
Filing Status
is marked as anything but
X
 for single.
Saved as "222-22-2222" by default.
Example: You are trying to create a binder for Tom Taxpayer. Based on the
Locator_No
 provided in the
CreateBinder
 call, Tom isn't found in the tax software. For a seamless user experience, SurePrep will create Tom Taxpayer in tax software.
  • If you provided Tom Taxpayer's information in the API call (name or SSN, for example), a new client is added with that name, SSN, and filing status.
  • If you didn’t provide taxpayer information, the previous placeholder values are used to create the client. Once SurePrep creates the client on your behalf, you can open the client in the tax software and update the values as needed.

Error messages

When trying to create your clients' binders using our API, it's important to provide accurate data in the input parameters. When the system runs into an issue using the records you've provided, an error message will display, letting you correct any mistakes and try again.
Error code
Error message
1201
We couldn't import because the taxpayer's SSN is incorrect. Enter the correct SSN and try again.
1202
We couldn't import because the SSN is incorrect and the filing status is missing. Enter the correct SSN, fill in the filing status, and try again.
1203
Locator ID is outside of the accepted range. Enter a Locator ID within the range and try again.
1204
The SSN parameter is null or empty. Enter the correct SSN and try again.
1205
Unable to locate tax file.

This article applies to:

  • Product: SurePrep

Related content

Chat now

error-icon

Triva isn't available right now.

Check out the support page for our phone number and hours

error-close