Web Presentmanet API

Summary: The 1099 Pro web presentment API is used to interface into the 1099 Pro Corporate Suite software.  It can be used to search for tax forms and retrieve PDF
copies.  The web presentment API is a Microsoft .Net 4.0 DLL with a SOAP web service wrapper.  The API consists of 3 web service operations and 1 web page.  Use the
“RequestForms” web service method to get a list of PDF keys.  Then use the RequestPdf or pdf.aspx to get the actual PDF form using the PDF key.

PDF Key Security: When you make a “RequestForms” call with the correct API key (optional), private key (optional), and HMAC signature (optional) the API searches the 1099
Pro database for forms matching the requested criteria.  When a form is found its unique identifier is noted.  Then the API concatenates a string that contains a time stamp,
the form type, the forms unique ID, the PDF password to be applied, and an expiration date.  The string is then encrypted using 256-bit AES with a random initialization vector
that is appended to the end of the cypher text and then all is base64 encoded.  This result is then passed back as the PDF Key.  When a request comes in for a PDF, the PDF
key is base64 decoded and AES decrypted and the string is checked for proper formatting.  If it passes, we use the forms unique ID from the string to retrieve the tax form
data and generate a PDF.  The symmetric key used for the AES encryption/decryption is a 256-bit key stored in the web.config.  The base64 encoded AES key is set in the
<appSettings><add key="symmetricKey" value="xxx" /></appSettings> value in the web.config.

• https://your.site.com/xxx/api.asmx - A SOAP 1.1 and 1.2 XML web service.
  • FormList - Used for testing, returns a list of form types supported by this API.
  • RequestForms - Returns a list of PDF keys based on your search parameters.
  • RequestPdf - Returns a specific PDF key’s PDF as a binary object.
• https://your.site.com/xxx/pdf.aspx?key=[PDF Key] - Returns a specific PDF key’s PDF as a file download.  Used to provide direct download links.
• RequestForms
  • Request XML Parameters.

+ API Security. Optional, but required if they are set in the web.config

- ApiKey = Optional, up to a 256 character string that must match the one set in the web.config.

• • Web.config needs <appSettings><add key="1099ProApiKey" value="xxx" /></appSettings> value set.

- PrivateKey = Optional, up to a 256 character string that must match the one set in the web.config.

• • Web.config needs <appSettings><add key="1099ProPrivateKey" value="xxx" /></appSettings> value set.

- Signature = Optional, base64 encoded HMAC SHA-256 hash of the search parameters.  See page 4 for more details.

• • The base64 encoded 64 byte HMAC secret key is set in the web.config.

° Web.config needs <appSettings><add key="1099ProHmacKey" value="xxx" /></appSettings> value set.

+ PDF & Link Security. Optional.

- Password = Optional, dynamically set up to a 32 character string that will be required to open the PDF.

- Expiration = Optional, integer specifying how many days the PDF keys are good for.  Default is to not expire.

+ Search parameters. If a parameter is not set then it will return all.

- Tin = Optional, 9-11 character string representing the recipients tin and tin type. 

• • • xxx-xx-xxxx = match SSN only.
    • xx-xxxxxxx = match EIN only.
    • xxxxxxxxx = match, SSN, EIN, or unformatted.

- Year = Optional, 4 character tax year, accepts an array of integers.

- Email = Optional, 65 character string representing the recipients email address.

- Account = Optional, 25 character string representing the recipients account number.

- AlternateAccount = Optional, 40 character string that searches both forms and transactions AltRcpAccount number.  Returns the form
if it or any of its transactions have a matching AltRcpAccount.

- pCode = Optional, form/filers pcode, accepts an array of strings.

- FormStatus = Optional, form statuses to return, accepts an array of integers.  The default returns all printed status forms.  If an original
1099 form has a correction, only the latest correction is returned.  This includes both parts of a 2 part correction, the zero correction
and the new part.  The original or new corrected values can be request and both parts are returned.  Corrected W-2’s will return the
latest correction (W-2C) plus any superseded corrections and the original.

- FormType = Optional, if not passed all form types are returned.  Accepts an array of strings and can be any of the following:  1042-S,
1097-BTC, 1098, 1098-C, 1098-E, 1098-T, 1099-A, 1099-B, 1099-C, 1099-CAP, 1099-DIV, 1099-G, 1099-H, 1099-INT, 1099-K, 1099-LTC,
1099-MISC, 1099-OID, 1099-PATR, 1099-Q, 1099-R, 1099-S, 1099-SA, 3921, 3922, 5498, 5498-ESA, 5498-SA, W-2, W-2G.

- ShowDoNotPrint = Optional, allows forms marked as “Do Not Print” to be returned.

- FormSpecificOptions = Optional, applies to a specific form types only, see below.

• • ŸForm1099SABox3Code = Optional, integer code that returns forms 1099-SA with the specified box 3 distribution code only. 
    Valid codes are 1, 2, 3, 4, 5, and 6.
  • Form1099KFilterByFederalFilingThreshold = Optional, boolean code to only return forms 1099-K that meet the federal
    threshold of Box 1 > $20,000.00 AND Box 3 > 200.

+ Web service XML response modifier, optional.

• • • • • SuppressTin = Optional, boolean code to suppress the TIN from being included in the response XML. Default is false/0, include TIN in
          response.

+ Request Example

<?xml version="1.0" encoding="utf-8"?><soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <RequestForms xmlns="http://www.1099pro.com/webpresentment/api/v1">
      <request>
        <Tin>144-22-1027</Tin>
        <Year>
          <int>2012</int>
          <int>2011</int>
        </Year>
        <Email>test@1099pro.com</Email>
        <Account>AccNum</Account>
        <AlternateAccount>AltRcpAccount</AlternateAccount>
        <pCode>
          <string>TESTPAYER</string>
          <string>W2PAYER</string>
        </pCode>
        <FormStatus>
          <int>0</int>
          <int>1</int>
        </FormStatus>
        <FormType>
          <string>1099-MISC</string>
          <string>1099-INT</string>
        </FormType>
        <ShowDoNotPrint>0</ShowDoNotPrint>
        <Password>password</Password>
        <Expiration>1</Expiration>
        <FormSpecificOptions>
          <Form1099SABox3Code>0</Form1099SABox3Code>
          <Form1099KFilterByFederalFilingThreshold>1</Form1099KFilterByFederalFilingThreshold>
        </FormSpecificOptions>
        <ApiKey>CGc65pCQ4DMUXllAO6pU</ApiKey>
        <PrivateKey>1idCGPUjWTEibm8yPcrf</PrivateKey>
        <Signature>jDObuWOaArANLscV8mn5ZNt9dHbpFh7z8xR2Basq==</Signature>
        <SuppressTin>0</SuppressTin>
      </request>
    </RequestForms>
  </soap12:Body>
</soap12:Envelope>

Response XML Parameters

Array of <FormsListItem>

Tin = String, recipients unformatted TIN.
Lastname = String, recipients last name/company.
Firstname = String, recipients first name.
FormType = String, forms form type.
Year = Integer, forms tax tear.
Printed = Boolean, was the form printed.
Correction = Boolean, does the form have an ‘X’ in the corrected box.
FormStatus = Integer, the forms status code.
PCode = String, the forms/filer pcode.
FilerName1 = String, the filers name line 1.
FilerName2 = String, the filers name line 2.
AlternateAccount = String, the form’s alternate account.
Account = String, the forms account.
TaxState = String, forms 2 character tax state code.
DateCreated = DateTime, of when the form was originally created in 1099 Pro.
Key = String, the PDF key used to retrieve the actual PDF form.

Response Example 

<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <soap:Body>
   <RequestFormsResponse xmlns="http://www.1099pro.com/webpresentment/api/v1">
    <RequestFormsResult>
        <Errors />
        <Meta>
          <KeyValue>
            <Key>elapsed</Key>
            <Value>0.0093195</Value>
          </KeyValue>
        </Meta>
        <Items>
          <FormsListItem>
            <Tin>144221027</Tin>
            <Lastname>OSAKI</Lastname>
            <Firstname>JAMES</Firstname>
            <FormType>1099-MISC</FormType>
            <Year>2012</Year>
            <Printed>false</Printed>
            <Correction>false</Correction>
            <FormStatus>0</FormStatus>
            <PCode>TESTPAYER</PCode>
            <FilerName1>Export Test</FilerName1>
            <FilerName2 />
            <AlternateAccount />
            <Account />
            <TaxState>CA</TaxState>
            <DateCreated>2012-11-27T00:00:00</DateCreated>
            <Key>13559FB50C6D77B1471D0316FDFDFSG3453455DFE45D5B510E8E7474F4E380G84FInCAupdtT9cpqmgexCw==</Key>
          </FormsListItem>
        </Items>
      </RequestFormsResult>
    </RequestFormsResponse>
  </soap:Body>
</soap:Envelope>

RequestPdf –

Request XML Parameters 

Key = Required, the PDF key returned from the RequestForms search.

Request Example

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
  <soap:Body>
    <RequestPdf xmlns="http://www.1099pro.com/webpresentment/api/v1"> 
      <request>
        <Key>13559FB50C6D77B1471D0316FDFDFSG3453455DFE45D5B510E8E795482B474F4E380G84FInCAupdtT9cpqmgexCw==</Key 
      </request>
    </RequestPdf>
  </soap:Body>
</soap:Envelope>

Response XML Parameters

FileData = The base64 encoded binary stream of the PDF.  Usually passed back to the client as a download.  

Filename = A string containing the file name of the PDF file.

Response Example

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/>
  <soap:Body>
    <RequestPdfResponse xmlns="http://www.1099pro.com/webpresentment/api/v1">
      <RequestPdfResult>
        <FileData>1C362C5912771AF512B932DBED3198A172A5E658437E9E447697D09B80525B571576107D...</FileData>
        <Filename>2012-1099MISC.pdf</Filename>
      </RequestPdfResult>
    </RequestPdfResponse>
  </soap:Body>
</soap:Envelope>

pdf.aspx?key=[PDF Key] - Used instead of “RequestPdf” to provide a direct download link to the PDF.

A PDF copy of this document can be downloaded here: CS API Brochure.pdf