Triva isn't available right now.
Check out the support page for our phone number and hours
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.
note
When using GoSystem Tax RS, certain input parameter requirements may vary from those listed in the developer portal.
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.
note
Some of the previous items require activation for your firm before you can use them for your clients. Contact SurePrep Support to enable these features if you're interested in using them at your firm. Review the before you begin section for more information on what SurePrep Support needs to enable.
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:
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. note
You can enable this option only if you also enable the Auto-link option. |
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:
- CreateBinder: Creates a new binder for the specified client when all the relevant identifying information is provided (for example,Service Type,Email, andOffice Location). Review the full binder creation flow chart.noteWe recommend fetching the necessary Lookup methods to provide records for theCreateBinderinput parameters correctly.noteWhen using GoSystem Tax RS, certain input parameters descriptions/limits may vary from those listed in the developer portal.
- 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.noteWhile we recommend uploading documents to a binder, you can skip this step for any reason.
- 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.
note
To let the SurePrep API automatically create new Locator Numbers for either of the previous cases, your firm will need the auto-create ability enabled. Contact SurePrep Support to inquire about enabling this for your firm.
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:
- TaxpayerFirstandLast Name
- SpouseFirstandLast Name
- Taxpayer and SpouseSSN
- 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:
| No | B |
accountNumber | (String) Tax software account number. Maximum limit of 4 characters (alphanumeric values). note
Tax Software activation needs to be completed in the FileRoom. If an empty value passes, then API Firm Default settings are used (). | 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 |
note
Certain input parameters in the developer portal don’t fully reflect the requirements to create a binder for GoSystem Tax RS. The 3 input parameters described in this article are specific to GoSystem Tax RS binders and thus override the description in the developer portal.
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. |
Related Content
-
SurePrep API - Binder use cases
Format:
Article,
6 min read
-
SurePrep API - Binder use cases
Format:
Article,
6 min read