About CCH iFirm Tax Web API

The Web API module allows you to interact with the CCH iFirm Tax module externally from the application using HTTP requests. With this module, you can trigger different actions in CCH iFirm Tax such as extracting data, setting data, creating returns and more without the need to be in a browser. This way, you can enhance your firm’s workflow by creating your own home made solutions integrated with CCH iFirm Tax or simply integrate your existing tools with CCH iFirm Tax.

Authentication

In order to use the Web API, a Web API key is required to authenticate yourself on the site. The key must to be included as part of the HTTP request in an x-api-key header.

To manage the Web API keys, click Settings from the left-hand menu, then click Tax, then the Web API Keys option.

Note: The Tax - Settings - Web API - Manage keys security role is required to display the option in the tax settings.

Manage Web API keys

Web API keys must be generated on first access. To do so, click the Click here to create keys link.

After clicking the link, two types of keys will be available for use by your firm:

• a read-write type key, which allows you to get data and metadata, in addition to setting data or metadata in the different tax elements;
• a read-only type key that allows you to get data and metadata from the different elements on your site.

You can manage the keys using the different interface buttons:

1. Copy the Web API key to the clipboard;
2. Regenerate the Web API key;
3. Revoke the Web API key.

A link that points to the API specifications is available in this page so that you can review our different endpoints. For more details, consult the API Specifications and discovery tool section.

Web API identity

Some of the actions performed with the Web API create an entry in the document’s audit trail. For example, where the value of a cell is modified using the Web API, the audit trail displays this modification and the user associated with the action performed displays as API:

CCH iFirm Tax Web API endpoints

• EFILE Information Endpoint;
• Lock/Unlock Endpoint;
• Preparer Profiles Endpoint:
• Print Endpoint;
• Return Statuses Endpoints;
• Roll Forward Endpoints;
• Tasks Endpoint;
• Cells Endpoints;
• T1 - Documents Endpoints;
• T2 - Documents Endpoints;
• T3 - Documents Endpoints;
• TF - Documents Endpoints.

Errors and messages (response body)

The Web API endpoints can return different errors in the response body depending on the context of the request. For more information about our different error messages, consult the List of errors and messages.

HTTP errors and messages

With the Web API, you might receive an HTTP error, for example, a 404 Not found error. In many scenarios, different messages were included to help you troubleshoot your requests. For more information, consult the list of HTTP error messages.

API specifications and discovery tool

In the API specifications, you will be able to discover the different endpoints offered with the Web API and to experiment with different requests to observe their behaviour.

Here is a quick guide using the GetData endpoint to explain how you can experiment with the different endpoints using the API specifications:

1. Enter one of the Web API keys that were created for your site in the “api_key” field.
   Note: For an action such as setting a value in a cell, you will be required to use a read-write key.
2. Expand the section corresponding to the action you would like to perform with the Web API.
3. Expand the endpoint in which you are interested to try out.

4. Complete the product field (e.g., T1, T2, T3 or TF).
5. Complete the id field, which represents the GUID of the document you would like to modify.
6. Click the example value of the body (optional), to paste the example into the requests field—this will allow you to start with an already valid structure.
7. Complete the requests field and make sure that, if you used the body example at point 6, the placeholders such as ‘string’ in the above example are replaced.
8. To launch the request, click the Try it out! button.

Once the request has been completed, the following information is provided:

9. A curl example of your request.
10. The URL of your request, including the parameters that were set at points 4 and 5.
11. The response body.
12. The response code.
13. The different response headers.

Web API Sample

To download a C# language demo sample click here.

The demo application covers the following scenarios and endpoints:

1. Creates a new 2019 document.
2. Retrieves all return statuses.
3. Changes the return status of a return.
4. Retrieves the document to display the status change.
5. Creates two T4 slips by setting the issuer field.
6. Gets data set in the document to show the change was made.
7. Rolls forward the document to 2020.
8. Retrieves the newly rolled forward document.
9. Retrieves the EFILE information of the newly rolled forward document.
10. Retrieves all print formats.

11. Prints the return to PDF using the print formats.

12. Retrieves all electronic services identification profiles.

13. Copies the document.

14. Locks the document.

15. Unlocks the document.

16. Retrieves the list of preparer profiles.

17. Changes the preparer profile of a document.

18. Retrieves the filtered list of documents from the return manager using the date_modified column

19. Retrieves a list of documents and navigate through the pages using the next or previous cursors.

20. Retrieves a list of documents sorted by one specific column.

21. Handles rate limiting using Retry-After.

22. Retrieves a list of environments without the list of templates linked to each environment.

23. Retrieves a list of groups with their group options.

24. Retrieves user data entered or modified in a document.

Note: To get started, read the README file provided with the solution.