Obtaining a List of Documents
The list of available documents is obtained by calling the RecipList.aspx page. RecipList.aspx should be sent the following XML stream which, in addition to the login information mentioned above, contains the account number, PAN, tax year and the recipient’s tax ID (SSN or EIN) as follows:
<?xml version="1.0"?> <DOCUMENT_LIST_REQUEST> <LOGIN_INFO> <CLIENT_ID/> <CLIENT_PWD/> <USER_ID/> <USER_PWD/> </LOGIN_INFO> <REQUEST_INFO> <TRUST_ACCOUNT_ID/> <FT_ACCOUNT_ID/> <TAX_YEAR/> <RECIP_TAX_ID/> <USE_TAVBENE/> (not required) </REQUEST_INFO> </DOCUMENT_LIST_REQUEST>
All information in the <LOGIN_INFO> node must be present. The input elements of the <LOGIN_INFO> node include:
Input Element | Description | Example |
|---|---|---|
<CLIENT_ID/> | Your ONESOURCE Trust Tax Client ID. | FULLSERVICE |
<CLIENT_PWD/> | Your Client ID password. | 1234@Star |
<USER_ID> | A ONESOURCE Trust Tax User ID. | RETRUSER |
<USER_PWD/> | The password for the User ID. | ABzq$@12Yz |
In the <REQUEST_INFO> node, only the account number is required. The remaining information is to fully qualify the document to be retrieved if there is more than one for the account number. The input elements of the <REQUEST_INFO> node include:
Element | Description | Example |
|---|---|---|
<TRUST_ACCOUNT_ID> | This is the account number. The account number is required. | 12220879 |
<FT_ACCOUNT_ID> | Product Access Number (PAN). | A123 |
<TAX_YEAR/> | This is the tax year. The tax year must be the current tax year or any of the previous four tax years. The tax year should be represented as four digits. If the tax year is not included, all documents that meet the criteria from the previous four tax years plus the current tax year are listed. | |
<RECIP_TAX_ID/> | This is the recipient Tax Identification Number (TIN). If the recipient TIN is included, it must be formatted as it was formatted when transmitted to Thomson Reuters, including dashes. note
For security purposes, a recipient TIN should be included in the parameters. If a recipient TIN is not included, all of the documents for the trust account, PAN and tax year are returned. Future releases will allow submitting the recipient TIN without an account number specified in order to retrieve a list of all documents for the recipient across multiple account numbers and PANs. | 545-55-3434 is not the same as 545553434 |
<USE_TAVBENE/> | Not required. This is a true/false indicator that defines what the value contained in the <RECIP_TAX_ID/> field above represents. If set to "true", the <RECIP_TAX_ID/> field should be populated with the internal beneficiary number from the Trust Accounting System rather than the recipient Tax Indentification Number (TIN). If set to "false" or is omitted, the <RECIP_TAX_ID/> field should be populated with the recipient TIN. | <USE_TAVBENE>true</USE_TAVBENE> (means the value found in the <RECIP_TAX_ID/> field contains the Trust Accounting System internal beneficiary number) <USE_TAVBENE>false</USE_TAVBENE> (means the value found in the <RECIP_TAX_ID/> field contains the recipient TIN) |
The caller will receive back a XML stream with a <REQUEST_STATUS> node, indicating success or failure, and a <DOCUMENT_LIST> node, which will itemize all recipient packages found that meet the <REQUEST_INFO> criteria.
<?xml version="1.0"?> <DOCUMENT_LIST_RESPONSE> <REQUEST_STATUS> <STATUS_CODE/> <STATUS_MSG/> </REQUEST_STATUS> <DOCUMENT_LIST> <FIDUCIARY fast_tax_account_id=’{FT Account Number}’ trust_account_id='{trust account number} '> <TRUST_ACCOUNT_NAME/> <DOCUMENT tax_year=’ {yyyy}’ product_code=’{see table}’ product_option=’{see table}’ <PRODUCT_DESC/> <DATE_TIME_GENERATED/> <MILESTONE_DATE/> <MILESTONE_WHO/> <RECIP_PACKAGE recip_tax_id=’{recipients TIN ein}’> <RECIP_NAME/> <RECIP_NAME_2/> <RECIP_ADDR/> <RECIP_ADDR2/> <RECIP_CITY_ST_ZIP/> <RECIP_FGN_ADDR/> <PACKAGE_KEY/> </RECIP_PACKAGE> </DOCUMENT> </FIDUCIARY> </DOCUMENT_LIST> <DOCUMENT_LIST_RESPONSE>
The <REQUEST_STATUS> node indicates whether an error occurred. The table shows a list of the contents for <STATUS_CODE> and the associated <STATUS_MSG>. Error codes starting with FT-RL or FT-ID are applicable to the recipient list request.
The <DOCUMENT_LIST> node will enclose a <FIDUCIARY> node for each account that has documents that meet the criteria. The output elements and attributes for the <DOCUMENT_LIST> node include:
Output Element | Output Element Attribute | Description | Example |
|---|---|---|---|
<FIDUCIARY> | |||
fast_tax_account_id | This attribute identifies the PAN. | A123 | |
trust_account_id | This attribute reiterates the account number passed. | 12220879 | |
<TRUST_ACCOUNT_NAME> | This child node is for information only to assist in identifying the correct document, if needed. | ||
<DOCUMENT> | There is a node for each tax return document for the account that meets the search criteria. | ||
tax_year | This attribute indicates the tax year of the tax document. | ||
product_code product_option | These attributes further describe the document. | ||
<PRODUCT_DESC> | Text corresponding to the product_code and product_option values. | Tax Return-1099 | |
<DATE_TIME_GENERATED> | This child node describes the exact time the tax document was prepared. | 01/12/2009 03:44:27 P.M. | |
<MILESTONE_DATE> | This child node holds the date and time that the Ready for Web Delivery milestone was completed in ONESOURCE Trust Tax. If the milestone was not defined in ONESOURCE Trust Tax or if the date has not been set, this node will be empty. | 01/22/2009 10:44:27 A.M. | |
<MILESTONE_WHO> | This child node holds the name of the user that completed the Ready for Web Delivery milestone. | Brenda Cox | |
<RECIP_PACKAGE> | This node identifies each package of recipient information contained in the document. One node identifies each package. | ||
recip_tax_id | This attribute is the SSN or EIN of the recipient. If the recipient's SSN or EIN is included in the request, only this one recipient’s information will be present regardless of how many recipient packages are contained in the document. If <USE_TAVBENE>true</USE_TAVBENE>, this attribute is the TAV Bene number of the recipient. | 545-55-3434 OR 78934 (if TAVBENE field is true) | |
<RECIP_NAME> <RECIP_NAME_2> <RECIP_ADDR>, <RECIP_ADDR2> <RECIP_CITY_ST_ZIP> <RECIP_FGN_ADDR> | These are all text fields to assist in identification. | ||
<PACKAGE_KEY> | This field supplies the Thomson Reuters-generated identifier for the recipient package. It contains information that will be needed for retrieving the exact recipient package. Do not store this key for any type of long term access because it may change. It is for use only during a single session of document list and retrieval. This key data must be provided to the document retrieval function. |