Cells Endpoints

Cette page est en cours de traduction. Elle sera mise à jour dès que son contenu sera disponible en français.

/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/{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.