Ingestion of Schedule K-1 Data

By investing approximately 60 hours of coding
(and a corresponding amount of testing)
to add K-1 import to your 1040 tax software,
you save your users thousands of hours
of time and tedium.

As diagrammed below, your 1040 app will receive Schedule K-1 information
in industry-standard FDX JSON format through 1 of 5 channels.

You then ingest the data into the user's tax return.

We recommend that you implement data ingestion as seen below
so data received via API and file upload leverage the same processes.

Steps

1. Upload JSON file

You probably are already set up to allow file upload using HTTP multipart/form-data technology.

Because JSON files are so small, you may wish to immediately process the JSON in memory.

Alternatively, you may save the data to a file and hand off processing to another module.


2. Upload PDF file. Extract JSON.

If the uploaded file has a "pdf" extension, extract the embedded JSON from the PDF. Here is sample java code based on the Apache PDFBox library.

import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.PDDocumentInformation;

public class PdfFdxJsonReader {

    private String fdxJson;
    private String fdxVersion;
    private String fdxSoftwareId;

    public String getFdxJson( ) {
        return fdxJson;
    }

    public String getFdxVersion( ) {
        return fdxVersion;
    }

    public String getFdxSoftwareId( ) {
        return fdxSoftwareId;
    }

    public void read( byte[] pdfBytes ) {

        try (
            PDDocument document = PDDocument.load( pdfBytes ) );
        ) {

            PDDocumentInformation info = document.getDocumentInformation( );
            if ( info == null ) {
                return;
            }

            this.fdxJson = info.getCustomMetadataValue( "fdxJson" );
            this.fdxVersion = info.getCustomMetadataValue( "fdxVersion" );
            this.fdxSoftwareId = info.getCustomMetadataValue( "fdxSoftwareId" );

        } catch ( Exception e ) {

            System.out.println( e.getMessage( ) );

        }

    }

}

3. QR Code

JSON can be encoded into a QR code and read by your smartphone app.

There is an assumption here that your smart phone app allows users to sign in to their account AND specify the tax return they are working on.


4. API Client

Approximately 20 hours of coding

Retrieving data via API client involves a straight-forward HTTP GET request. For more information, see User Prompts and HTTP GET General Information.

Proxyman


5. API Server

Allow trusted third party applications to push tax data to your program via API on behalf of users.

There are now many applications assisting taxpayers and tax preparers to collect and assemble annual tax documents. Many of these extract tax data from the documents and are positioned to push that data into tax software applications. However, not enough tax software applications provide API server technologies at this time.

Additionally, many taxpayers would be willing to give permission to tax document issuers to securely forward their annual tax document data to a trusted application as soon as the data is available.

You would need to design an authorization flow to enable this feature.


6. Parse (deserialize) JSON

Approximately 12 hours of coding

Deserializing the JSON to an FDX object in your programming language of choice is a straight-forward process.

Using the FDX OpenAPI schema file, generate model files. Email fdxsupport@financialdataexchange.org to get a copy of the FDX specification and schema files.

As a convenience, the model files are available for download from GitHub for a nominal fee of $150. Email support@schedulek-1.com to obtain access to the repository(ies).

Version 5: https://github.com/iTipsDev/fdx-tax-schema-v5.3.3

Version 6: https://github.com/iTipsDev/fdx-tax-schema-v6.1.0

GitHub

These languages are currently available: csharp, java, python, ruby, and typescript-angular. Let us know if you need another language.

Then using the JSON serialization utility of your choice, deserialize the JSON. Here is an example using the popular Jackson library.

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.core.JsonGenerationException;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.datatype.joda.JodaModule;

import fdx.tax.models.*;

import java.io.IOException;
import java.io.StringWriter;

public class TaxDataListSerializer {

    public static Logger LOGGER = Logger.getLogger( TaxDataListSerializer.class.getName( ) );

    public static TaxDataList deserialize(
        String json
    ) {

        TaxDataList data = null;

        try {

            ObjectMapper objectMapper = new ObjectMapper( );

            // Special handling for dates
            objectMapper.registerModule( new JodaModule( ) );
            objectMapper.disable( SerializationFeature.WRITE_DATES_AS_TIMESTAMPS );

            data = objectMapper.readValue( json, TaxDataList.class );

       } catch( Exception e ) {

            LOGGER.severe( e.getMessage( ) );

       }

       return data;

    }

}

7. Map FDX tax objects to your tax software objects

Approximately 16 hours of coding

For each item on Schedule K-1, you will map the data from the FDX object to your software object.

Download skeleton code that is intended to jump-start the process for you.

Here are excerpts:

public class Tax1065K1MapperSkeleton {

    public Object mapFromFdxObject( Tax1065K1 fdxObj ) {

        Object ourForm = new Object( );

        // ...

        // ----------------------------------------------------------------------------------------------------
        // Box G, Limited partner or other LLC member
        // ----------------------------------------------------------------------------------------------------
        boolean limitedPartner = fdxObj.getLimitedPartner( );
        // If required, transform data. Then populate your object value(s).

        // ----------------------------------------------------------------------------------------------------
        // Box 1, Ordinary business income (loss)
        // ----------------------------------------------------------------------------------------------------
        Double ordinaryIncome = fdxObj.getOrdinaryIncome( );
        // If required, transform data. Then populate your object value(s).

        // ----------------------------------------------------------------------------------------------------
        // Box 2, Net rental real estate income (loss)
        // ----------------------------------------------------------------------------------------------------
        Double netRentalRealEstateIncome = fdxObj.getNetRentalRealEstateIncome( );
        // If required, transform data. Then populate your object value(s).

        // ...

        return ourForm;

    }

}

8. Add or Merge

Approximately 12 hours of coding

It is likely that your software has generated an existing K-1 instance based on the prior year tax return.

The user may have also started to work on the K-1 to enter estimated amounts.

If there are existing K-1s in the tax return, you can employ one of these approaches:

  • Scan the existing K-1s for matching EIN and, if joint tax return, recipient SSN. Merge in the new data.
  • Prompt the user to identify the K-1 that is the intended imported data destination. Then merge in the new data.

MERGE STRATEGIES

You may let the user choose from the below merge strategies or inform the user that you are employing one of them.

  • Imported data will be applied universally and replace any data previously entered.
  • Imported data will be applied - except where the user has already entered a value.