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.
  • RequestXml - Returns all of the individual records’ information (recipient info, box amounts, optional fields…) based on your search/filter 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 & RequestXml
  • Request XML Parameters.

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

- ApiKey = Optional, 40 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, 40 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, filers Payer Code filter, accepts an array of strings.  Default returns all Payer Codes.  If Payer Code Security is enabled in the web.config, the returned PCODEs will be limited to the ones configured for that API key.

- 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 (Unless IncludeOriginal is set to true). 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.

- IncludeOriginal = Optional, when set to true corrected 1099 forms will also return the original form in the response list.

- FormType = Optional, if not passed all form types are returned.  Accepts an array of strings and can be any of
the following:  1042-S, 1095-B, 1095-C, 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.

- TinMasking = Optional, enables TIN masking (XXX-XX-1234) for SSNs on approved forms types.
TINs must be formatted as SSNs. Available options: “Mask” = Mask all, “NoMask” = No masking, “FilerDetermined” = User filer default setting.
Default is no masking.

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

- Printed = Optional, Default returns forms that have been printed.

• • All = Optional, returns all forms regardless of DatePrinted field value.
  • Yes[Default] = Optional, returns all forms that have a DatePrinted field value != 0
  • No = Optional, returns all forms that have a DatePrinted field value = 0

 - 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.

+ RequestForms 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>
        <TinMasking>Mask</TinMasking>
        <ShowDoNotPrint>0</ShowDoNotPrint>
        <Printed>All</Printed>
        <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>

+ RequestXml 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>
    <RequestXml 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>
        <TinMasking>Mask</TinMasking>
        <ShowDoNotPrint>0</ShowDoNotPrint>
        <Printed>All</Printed>
        <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>
    </RequestXml>
  </soap12:Body>
</soap12:Envelope>

Response XML Parameters

RequestForms 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.
DateLastEdit = DateTime, of when the form last edited in 1099 Pro.
Key = String, the PDF key used to retrieve the actual PDF form.

Response Example for RequestForms 

<?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>
            <DateLastEdit>2012-11-27T00:00:00</DateLastEdit>
            <Key>13559FB50C6D77B1471D0316FDFDFSG3453455DFE45D5B510E8E7474F4E380G84FInCAupdtT9cpqmgexCw==</Key>
          </FormsListItem>
        </Items>
      </RequestFormsResult>
    </RequestFormsResponse>
  </soap:Body>
</soap:Envelope>

RequestXml Array of <FormField>

FormField = String, Name of Field on the request Form(s)
Value = String, Value of FormField

Response Example for RequestXml

<?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>
   <RequestXmlResponse xmlns="http://www.1099pro.com/webpresentment/api/v1">
    <RequestXmlResult>
        <Errors />
        <Meta />
        <Forms>
          <Form>
            <Fields>
              <FormField name="TrackingID">
                <Value xsi:type="xsd:string">14</Value>
              </FormField>
              <FormField name="TaxYear">
                <Value xsi:type="xsd:string">2014</Value>
              </FormField>
              <FormField name="FormType">
                <Value xsi:type="xsd:string">1099MISC</Value>
              </FormField>
              <FormField name="PCode">
                <Value xsi:type="xsd:string">TestFiler</Value>
              </FormField>
              <FormField name="Category">
                <Value xsi:type="xsd:string" />
              </FormField>
              <FormField name="Source">
                <Value xsi:type="xsd:string">14</Value>
              </FormField>
              <FormField name="Recipient TIN">
                <Value xsi:type="xsd:string">144221027</Value>
              </FormField>
              <FormField name="Corrected">
                <Value xsi:type="xsd:string">14</Value>
              </FormField>
              <FormField name="Last Name/Company">
                <Value xsi:type="xsd:string">Osaki</Value>
              </FormField>
              <FormField name="First Name">
                <Value xsi:type="xsd:string">JAMES</Value>
              </FormField>
              .
              .  etc
              .
          </Fields>
        </Form>
      </Forms>
     </RequestXmlResult>
    </RequestXmlResponse>
  </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