Cells Endpoints

/api/partner/1.0/{product}/documents/{id}/cells/getdata (POST)

Endpoint authentication

When adopting OAuth 2.0 as an authentication method, the below security requirements are needed in order to trigger this endpoint:

• The user must fulfill the below security roles requirements; if he fails to obtain access to all the necessary security roles, an error 403: Insufficient privileges to execute this request is returned:

  • The user must acquire access to at least one of the following security roles; he needs to have access to the security role corresponding to the product included in the URL:

    • Tax – Access T1 Product

    • Tax – Access T2 Product

    • Tax – Access T3 Product

    • Tax – Access Forms Product

• This endpoint validates against the user’s contact security and document visibility. If the user does not have access to the document provided in the URL or the contact associated to this document, an error 404: Resource not found in the system is returned.

Endpoint description

Get the value of one or more cells from the document specified in the URL. The product (T1, T2, T3, or TF) and ID of the document (GUID) must be included in the URL.

Model	[ { "cellPath": "string", "returnId": 0 } ]
Properties	cellPath: ID of the cell from which you want to get data. This ID can be found using the Copy Cell ID button in the contextual menu.
	returnId: Taxpayer’s ID (0 for main taxpayer, 1 for spouse and 1000+ for dependants)

Examples

Request URL	https://mysite.cchifirm.ca/taxcan/api/partner/1.0/T1/documents/1e9bcb47-3ac3-4797-9404-bb4853b5f6a3/cells/getdata
Request body	[ { "cellPath": "ID.Towidt9", "returnId": 0 }, { "cellPath": "ID.Towidt8", "returnId": 0 } ]
Response body	{ "result": [ { "returnId": 0 "path": "ID.Towidt9", "value": "John", "flags": [ "NotEmpty", "HasInput" ] }, { "returnId": 0 "path": "ID.Towidt8", "value": "Smith", "flags": [ "NotEmpty", "HasInput" ] } ], "errors": [] }

Note: The returnId parameter is optional and will default to 0 (main taxpayer) when not included.

Wildcard character for multi-repeat elements using the GetData endpoint

To get a cell value in each repeat of a multi-copy element (for example a T5018 slip), the wildcard character “*” can be used.

Examples

Request body	[ { "cellPath": "T5018[*].S1", "returnId": 0 } ]
Response body	{ "result": [ { "returnId": 0 "path": "T5018[1].S1", "value": "Smith", "flags": [ "NotEmpty", "HasInput" ], "indexes": [ 1 ] }, { "returnId": 0 "path": "T5018[2].S1", "value": "Taylor", "flags": [ "NotEmpty", "HasInput" ], "indexes": [ 2 ] } ], "errors": [] }

/api/partner/1.0/{product}/documents/{documentId}/cells/getdata/reviewfilter (POST)

When adopting OAuth 2.0 as an authentication method, the below security requirements are needed in order to trigger this endpoint:

• The user must fulfill the below security roles requirements; if he fails to obtain access to all the necessary security roles, an error 403: Insufficient privileges to execute this request is returned:

  • The user must acquire access to at least one of the following security roles; he needs to have access to the security role corresponding to the product included in the URL:

    • Tax – Access T1 Product

    • Tax – Access T2 Product

    • Tax – Access T3 Product

    • Tax – Access Forms Product

• This endpoint validates against the user’s contact security and document visibility. If the user does not have access to the document provided in the URL or the contact associated to this document, an error 404: Resource not found in the system is returned.

Endpoint description

Get the value of one or more cells from the document provided in the URL, according to the review filter provided in the request body. The filter categories that are supported are: Cells with data, Cells with review marks and Cells with comments. The Cells with diagnostics filter as well as the custom filters are not supported. The product (T1, T2, T3, or TF) and ID of the document (GUID) must be included in the URL.

Model	{ "filter": "string", "returnId": 0 }
Properties	filter: Name of the filter from which you want to get data. This filter can be found in the Filters table below.
	returnId: Taxpayer’s ID (0 for main taxpayer, 1 for spouse and 1000+ for dependants)

Filters

Filter Category	Filter
Cells with data	entered_this_year_or_last_year
	entered_this_year
	entered_last_year
	overridden
	edited_after_cra_rq_import
	imported
	breakdown
	spreadsheet
	rolled_forward
	tracked_changes
Cells with review marks	all_review_marks
	first_review
	second_review
	question
	problem
	other
Cells with comments	cells_with_comments

Examples

Request URL	https://mysite.cchifirm.ca/taxcan/api/partner/1.0/T1/documents/1e9bcb47-3ac3-4797-9404-bb4853b5f6a3/cells/getdata/reviewfilter
Request body	{ "filter": " entered_this_year", "returnId": 0 }
Response body	{ "result": [ { "path": "ID.Towidt8", "value": "Britney", "flags": [ "NotEmpty", "HasInput", "HasComments", "HasFirstReview" ], "metadata": { "reviewMark": { "username": "Jane Doe", "timestamp": "2024-01-23T02:24:12.130Z" }, "comments": [ { "text": "Comment", "username": "Jane Doe", "timestamp": "2024-01-23T02:26:37.219Z" } ] } }, { "path": "T4Slip[1].Toatsc4", "value": "10000", "flags": [ "NotEmpty", "HasInput", "HasComments", "HasFirstReview" ], "metadata": { "reviewMark": { "username": "Jane Doe", "timestamp": "2024-01-23T02:27:38.229Z" }, "comments": [ { "text": "Need to validate income", "username": "Jane Doe", "timestamp": "2024-01-23T02:30:37.112Z" } ] } } ], "errors": [] }

/api/partner/1.0/{product}/documents/{id}/cells/setdata (POST)

Endpoint authentication

When adopting OAuth 2.0 as an authentication method, the below security requirements are needed in order to trigger this endpoint:

• The user must fulfill the below security roles requirements; if he fails to obtain access to all the necessary security roles, an error 403: Insufficient privileges to execute this request is returned:

  • The user must acquire access to at least one of the following security roles; he needs to have access to the security role corresponding to the product included in the URL:

    • Tax – Access T1 Product

    • Tax – Access T2 Product

    • Tax – Access T3 Product

    • Tax – Access Forms Product

  • In addition, the user cannot modify cells that contain contact information if he does not have access to one of the below security roles. When the user is allowed to edit all contact cells, he can modify all the cells that are synchronized with the Contact. In case the user is only allowed to edit specific contact cells, several cells containing contact information cannot be updated:

    • Tax – Return – Edit specific contact cells

    • Tax – Return – Edit all contact cells

• This endpoint validates against the user’s contact security and document visibility. If the user does not have access to the document provided in the URL or the contact associated to this document, an error 404: Resource not found in the system is returned.

Endpoint description

Sets the value of one or more specific cells, in a particular document. The product (T1, T2, T3, or TF) and the ID of the document (GUID) must be included in the URL.

Model	[ { "cellPath": "string", "value": "string", "returnId": 0 } ]
Properties	cellPath: ID of the cell from which you want to set data. This ID can be found using the Copy Cell ID button in the contextual menu.
	value: Value to be set in the cell specified in the cellPath property. For more details on the format of the value to use, consult the Values format section.
	returnId: Taxpayer’s ID (0 for main taxpayer, 1 for spouse and 1000+ for dependants).

Examples

Request URL	https://mysite.cchifirm.ca/taxcan/api/partner/1.0/T1/documents/1e9bcb47-3ac3-4797-9404-bb4853b5f6a3/cells/setdata
Request body	[ { "CellPath": "T4Slip[1].Toatsc4", "value": "35000", "returnID": 0 }, { "CellPath": "T4Slip[2].Toatsc4", "value": "15000", "returnID": 0 } ]
Response body	{ "errors": [] }

Note: The returnId parameter is optional and will default to 0 (main taxpayer) when not included.

Value formats

The values displayed in the UI are not always the same as that stored in the system. To set values in the system using the WebAPI, values must be provided in the format expected by the system.

Example:

For example, in the T1 product ID form, there is a cell called Date of marriage or union (Cellpath: ID.Towidt92) in the Identification section:

In the UI, simply enter the month and day and the input will be accepted. However, the real value expected by the system is YYYY-MM-DD (e.g. 2020-12-04). In order for the user to be able to set the value to “12/04” in the form with a WebAPI command, the date format given in the command must be the same as what is expected by the system, i.e., YYYY-MM-DD (2020-12-04 in the above example). The request body of a set cell value on ID.Towidt92 should look as follows:

Response body

[ { "cellPath": "ID.Towidt92", "value": "2020-12-04", "returnId": 0 } ]

System value discovery

The following methods are available to find out which value to provide in a WebAPI command:

Via the GetCell endpoint

• Set the value in a cell of the return via the UI.
• Use the GetData endpoint in the Web API request to determine the product and set the document ID used in the first step of the URL request.
• Target the cell set in the first step in the request body.
• Review the value returned in the response body of the request, which is the system raw value.

Via the Copy cell raw value button

• Set a cell of the return with the value for which you are looking to discover the system value via the UI.
• Right-click the cell and click Copy cell raw value.
• Paste the content of your clipboard, which represents the system raw value.