Return Statuses Endpoints

/api/partner/1.0/{product}/documents/{documentId}/returnStatus (PUT)

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 the return status of a document if he does not have access to the below security role:

    • Tax – Returns – Return status

• 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

Updates the return status of the document specified in the URL with the return status specified in the request body. The product (T1, T2, T3, TF) and the GUID of the document must be included in the URL.

Model	{ "returnId": 0, "returnStatusId": "string" }
Properties	returnId: Taxpayer’s ID (0 for main taxpayer, 1 for spouse and 1000+ for dependants)
	returnStatusId: GUID of the return status, can be retrieved by creating a get request using the ReturnStatuses endpoint.

Examples

Request URL	https://mysite.cchifirm.ca/taxcan/api/partner/1.0/T1/documents/9098b588-d70a-473e-ae0f-84a3b2b4a8d0/returnStatus
Request body	{ "returnId": 0, "returnStatusId": "415c4238-9117-d545-85b5-a6c5717bdba1" }
Response body	{ "errors": [] }

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

/api/partner/1.0/{product}/returnStatuses (GET)

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

Endpoint description

Returns a list of return statuses for the product specified in the URL of the endpoint. The product (T1, T2, T3, TF) must be included in the URL.

Model	N/A
Properties	N/A

Examples

Request URL	https://mysite.cchifirm.ca/taxcan/api/partner/1.0/T1/returnStatuses
Request body	N/A
Response body	{ "result": [ { "id": "415c4238-9117-d545-85b5-a6c5717bdba1", "name": "Not Started", "active": true }, { "id": "f3f0d1c4-ef04-7f4f-906d-b04f8e5b9372", "name": "Ready", "active": true }, { "id": "c45bbac2-92c5-cb4f-b2ee-f59f0f22a8cc", "name": "Preparation", "active": false }, { "id": "8539da61-963d-8e4d-aa30-cc91d89253d7", "name": "Review", "active": true }, { "id": "2a374f89-5e4e-d649-ae95-5b14ee09c010", "name": "Authorizing", "active": false }, { "id": "9b41d224-9328-a04c-a2a2-c41b42ccb2d9", "name": "To EFILE", "active": true }, { "id": "e4919957-9f34-184a-af33-8efe6bfbfd14", "name": "To Pay", "active": true }, { "id": "57f89bb5-67f0-0147-8aca-a4f2f64dfb83", "name": "Completed", "active": true } ], "errors": [] }

/api/partner/1.0/{product}/documents/returnStatuses (PUT)

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 the return status of a batch of documents if he does not have access to the below security role:

    • Tax – Returns – Return status

• 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 request body or the contact associated to this document, an error 404: Resource not found in the system is returned.

Endpoint description

Updates the return status of the documents specified in the request body with the return status specified. The product (T1, T2, T3, TF) must be included in the URL.

Model	{ "returnStatusId": "string", "documents": [ { "documentId": "string", "returnIds": [ 0 ] } ] }
Properties	returnStatusId: GUID of the return status, can be retrieved by creating a get request using the ReturnStatuses endpoint.
	documentId: GUID of the document, can be retrieved by creating a get request using the Documents endpoint.
	returnIds: Array of taxpayers’ 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/returnStatuses
Request body	{ "returnStatusId": "6d693fb5-c19c-4486-926c-3016093b046e", "documents": [ { "documentId": "41f3c892-49c3-4c96-9a20-a78f324d9321", "returnIds": [ 0, 1 ] }, { "documentId": "cd3649d1-a885-4fa0-be6c-7a145611892c", "returnIds": [ 1 ] } ] }
Response body	{ "errors": [] }

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