About CCH iFirm Common API

The Common API module allows you to interact with the CCH iFirm common areas (Contacts, Users, Contact Security and Security Profiles) externally from the application using HTTP requests. With this module, you can trigger different actions in CCH iFirm such as extracting data, setting data, creating Contacts or Users and more without the need to be in a browser. This way, you can enhance your firm’s workflow by developing your own home-made solutions integrated with CCH iFirm or simply merge your existing tools with CCH iFirm.

Looking for information on the CCH iFirm Taxprep Web API, consult the Taxprep Web API help topic.

Authentication

To use the Common API, you will need to set up OAuth 2.0 to implement authentication and authorization. It is required to have an authorization flow so your users can authorize your app to connect with CCH iFirm. If users grant permission, our server sends an authorization code back to your app. Your app exchanges this code for access tokens. Please consult the Knowledge Base article for more details: How do I implement Oauth2 token authentication for CCH iFirm API?

Errors and messages (response body)

The 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, please refer to the Swagger API discovery tool.

HTTP Errors and Messages

With the API, you might receive an HTTP error, like a 404 Not found error. In many scenarios, different messages were included to help you troubleshoot your requests. For more information, please refer to the Swagger API discovery tool.

Rate limiting

Different types of API requests to CCH iFirm Common API are subject to different rate limits. The endpoints are separated in 2 categories which are Group A and Group B. You can consult the list of available endpoints to validate in which category they belong in this section of the help topic: API Endpoints Specifications and Discovery Tool.

The Group A of requests are limited to 30 requests per minute and 3000 requests per day. The Group B of requests are limited to 6 requests per minute and 125 requests per day. Plans that allow for more requests are available. Contact your solution consultant for more information.

A 429 error, Too many requests, is returned when the number of requests limit per minute or day is reached. Note that the rate-limit algorithm that track the number of requests for the Common API includes a margin of error that may lead to imperfect count before you get an error for exceeding a threshold.

API Endpoints Specifications and Discovery Tool

In the API specifications, you will be able to discover the different endpoints offered with the API and to experiment with various requests to observe their behaviour. There are two different pages that provides information on the available endpoints:

https://yoursite.cchifirm.ca/fe/api/swagger/ui/index#/

Group	Endpoint	Rate limit category
Profiles	/global/1.0/getprofiles	Group A
Profiles	/global/1.0/updaterolesforprofiles	Group B
Profiles	/global/1.0/getsecurityrolesforprofile/{profileId}	Group A
Global	/global/1.0/getlicensedetails	Group A
Global	/global/1.0/getroles	Group A
Global	/global/1.0/customroles	Group A
Global	global/1.0/customroleusers/{customRoleId}	Group A
Global	/global/1.0/getfirmgroups	Group A
Global	/global/1.0/getdynamicfields	Group A
Global	/global/1.0/createfirmfiltergroups	Group A
Global	/global/1.0/deletefirmfiltergroups	Group A
Users	/global/1.0/getuserdetails/{id}	Group A
Users	/global/1.0/createusers	Group B
Users	/global/1.0/updateusers	Group A
Users	/global/1.0/fetchusers	Group A
Users	/global/1.0/getusersroles	Group A
Users	/global/1.0/GetUserAccessListPerClient/{id}	Group B
Users	/global/1.0/getblockedcontacts/{userId}	Group B
Users	/global/1.0/updaterolesforusers	Group A
Users	/global/1.0/updatesecurityprofilesforuser	Group A
Users	/global/1.0/addssologindetailsforuser	Group A
Users	/global/1.0/GetUserRolesByIdentifier	Group A
Users	/global/1.0/usercustomroles/{userId}	Group A
Users	/global/1.0/users/{userId}	Group A
Contact Security	/global/1.0/getcontactsecurityfilters	Group A
Contact Security	/global/1.0/getuserscontactsecurityfilter	Group A
Contact Security	/global/1.0/updatecontactsecurityforuser	Group B
Contact Security	/global/1.0/recalculatecontactsecurity	Deprecated
Contacts	/global/1.0/contacts/search	Group A

https://yoursite.cchifirm.ca/crm/api/swagger/ui/index#/

Group	Endpoint	Rate limit category
Contacts	/global/1.0/CreateOrUpdateContacts	Group B
Contacts	/global/1.0/getcontact	Group A
Contacts	/global/1.0	Group A
Contacts	/updatecontactdynamicfield	Group A
Contacts	/global/1.0/CreateRelationshipByID	Group A
Contacts	/global/1.0/CreateRelationshipByGUID	Group A
Contacts	/global/1.0/DeleteContactRelationships	Group A
Contacts	/global/1.0/FetchContactRelationById	Group A
Contacts	/global/1.0/FetchContactRelationByIdentifier	Group A

Note: The API Administration security role is required to display the Swagger interface.

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

Expand the section corresponding to the action you would like to perform with the API.
Expand the endpoint that you are interested to try out.
Click on the example value of the body (optional), to paste the example into the requests field—this will enable you to start with an already valid structure.
Complete the profileID field (e.g., 1, 2, 3 or 4).
To launch the request, click the Try it out! button.

Once the request has been completed, the following information is provided:
A curl example of your request.
The URL of your request, including the parameters that were set at points 4 and 5.
The response body.
The response code.
The different response headers.

API Sample

The following is a link to a sample project for an API (GET) request under OAuth 2.0: How do I implement Oauth2 token authentication for CCH iFirm API?