Track1099 API Readme

The Track1099 API is for customers who want to develop their own software to automate their processes and integrate with Track1099 by Avalara. If you do not want to write your own programs, this page won't help you. Check out our FAQ or How it Works guide instead.

What can you do with the Track1099 API?

We are just getting started with the API, and we would love your input. Right now you can:

1. Retrieve a list of your payers, which the API calls "issuers" (see What's a Payer/Issuer?)
2. Create a new issuer or correct an existing one
3. Add recipient forms to an issuer by uploading a properly-formatted CSV file (see CSV templates)
4. Check the progress of an upload (most are imported in seconds) and get a summary of the recipient forms imported

For now, you will need to use the Track1099.com web app for all other functions, including reviewing your forms, scheduling e-filing and e-delivery, and making form corrections.

Getting started

1. Create or login to your account at Track1099.com

If you are not the team leader and you do not have an account yet, ask your team leader to invite you before you create an account, and follow the instructions in the invitation email. (See this short video on team management.)

If more than one person will be working with the API, they should each have their own account on the team. The team leader controls which payers each user has access to, though users can always add new payers.

2. Create an API token

Visit the API tab in your Account page and click "Create a new API token". The full token will only be visible for 10 minutes, so be sure to save it. You will be required to enable two-factor authentication before you can create an API token.

API tokens always have exactly the same access as the user who created the token. If you lose a token, you can deactivate it at any time. The team leader can also deactivate team members' tokens or accounts.

3. Copy your Team API ID

Your Team API ID is found on the same page, and it will be part of the URL in all your API requests. Unlike an API token, every account in the team uses the same Team API ID, it's always visible on the API page, and the Team API ID is not the same as any API token.

4. Create a Payer (aka Issuer)

Visit your All Payers overview. If you do not have any payers, or you would like to use a new one for testing, click "Add New Payer" then "Enter a New Payer Manually". You can create Issuers with the API, too, but it helps to see the point-and-click form first.

There is no charge to use the Track1099 service until you schedule e-filing, and you can always delete individual forms and entire payers later.

Spoilers! In the next step, you'll retrieve your payer ID from the API, but if you check the URL in the web app after you save, you can get the ID without using the API.

If you know your way around APIs and you know 1099 form terminology, this is a good place to jump off and start exploring on your own.

Using the API

Open our Swagger docs in a new window or tab. The next three steps use the interactive Swagger docs.

1. Find your payer in an API response

First, click the green Authorize button on the right in the Swagger docs and enter the API token you saved from step 2 in "Getting started". Then click GET /api/v1/{team_api_id}/issuers and if team_api_id is not filled in automatically, enter the Team API ID that you found in step 3. Click Try it out and read the response, looking for the payer you created in step 4 above. The API response will include your payer's ID, which you can use in the next step.

2. Upload a CSV of forms

Click POST /api/v1/{team_api_id}/issuers/{issuer_id}/import-forms and enter the ID you found in the last step for issuer_id. For csv_file, you'll need to start from one of our CSV templates and complete the file with your real data. To see how this endpoint works, though, you can use our example 1099-NEC CSV file. Save a copy to your computer, then choose it for your csv_file and click Try it out.

3. Check import status

The response from the last step will include an ID (and a URL) for an import Job. By the time you click GET /api/v1/{team_api_id}/jobs/{job_id}, enter that ID in job_id, and click Try it out, your import will probably already be complete. You should see that 4 forms were imported: 2 ok, 1 missing email, and 1 with an error.

4. See your new forms in the web app

Back in the Track1099.com web app, if you refresh your All Payers Overview you should see colored pills with information about your newly-added forms next to your payer's name. Click one of the pills to see your new forms.

Appendix

What's a Payer/Issuer?

The payer is the company issuing forms in a given tax year. If you are using Track1099 as a bookkeeping or accountant firm on behalf of your clients, you will have many payers. If you are using Track1099 internally, you will probably only have one or a few. When you come back next year, you will create or import a new entry for each payer for the new tax year.

The Track1099.com web app calls these companies "Payers" because "Payer" is what the IRS calls the issuing company on the most common forms. The API calls these companies "Issuers" because many less-common IRS forms use different words for the issuing company, and the programmers felt much better with a single word to accurately cover all cases. Also, the IRS' technical documents are moving to the Issuer terminology, and we think it's a more future-proof word.