Print Endpoints

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

Endpoint authentication

When adopting OAuth 2.0 as an authentication method:

  • The user must fulfill the following security role requirements to trigger this endpoint. If he or she fails to obtain access to all the necessary security roles, a 403 error, Insufficient privileges to execute this request, is returned:

    • The user must be granted with at least one of the following security roles. He or she must 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

This endpoint returns a list of print formats for the product and year specified in the URL of the endpoint.

Model

N/A

Properties

N/A

Examples

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/T1/printFormats?year=2020

Request body

N/A

Response body

{

"result": [

{

"id": "4382550f-f4fb-1c5f-d840-fff01957f57b",

"name": "Client copy",

"description": "Groups forms to give to client.",

"isDefault": ["d6d50e87-7189-4ac9-b136-cc849412f4c3"],

"lastModificationTimestamp": null

},

{

"id": "45e9246b-427c-ab96-f116-bd709930dac7",

"name": "EFILE copy",

"description": "Groups forms necessary to meet the requirements of the tax authorities for EFILING.",

"isDefault": ["d6d50e87-7189-4ac9-b136-cc849412f4c3"],

"lastModificationTimestamp": null

},

{

"id": "373b860e-fd62-2a30-df89-6717e18e74c9",

"name": "Government copy",

"description": "Groups forms required to meet the filing requirements of the tax authorities. It must be used to file paper returns.",

"isDefault": ["d6d50e87-7189-4ac9-b136-cc849412f4c3"],

"lastModificationTimestamp": null

}],

"errors": []

}

/api/partner/1.0/{product}/print (POST)

Endpoint authentication

When adopting OAuth 2.0 as an authentication method:

  • The user must fulfill the following security role requirements to trigger this endpoint. If he or she fails to obtain access to all the necessary security roles, a 403 error, Insufficient privileges to execute this request, is returned:

    • The user must be granted with at least one of the following security roles. He or she must 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, addition, the user cannot print documents to PDF without access to the security role below:

      • Tax – Print to PDF

  • 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

This endpoint prints a batch of documents to PDF for the product and year specified in the URL of the endpoint. Once the print is initiated, a taskID is provided in the response location header and the status of the task can be retrieved by using the Task endpoint.

Model

{

"documents": [

{

"documentId": "string",

"returns": [

{

"id": 0,

"language": "English"

}]

}],

"options": {

"printFormats": [

{

"id": "string"

}],

"overridePrintedDate": "string",

"mergePdf": true,

"maskSinHeaderFooter": true,

"maskSinForms": true

}

}

Properties

documents: Array of documents and IDs

documentId: ID of the document to print

returns: Array of taxpayer IDs

id: ID of the taxpayer within the document (0 for main taxpayer, 1 for spouse and 1000+ for dependants). This parameter is optional and will default to 0 if not included.

language: Language to use for printing the return. This parameter is optional and will default to the language of correspondence of the contact if not included.

options: Options related to the print job.

printFormats: Array of IDs of the print formats to use to print

id: ID of the print format

overridePrintedDate: Overrides the printed date on the forms. This parameter is optional and will default to the current date if not included.

mergePdf: Parameter used to merge the PDFs into a single PDF. This parameter is optional and will use the default set in the Customize PDF File section of the site if not included.

maskSinHeaderFooter: Parameter relevant for the T1 product only. It is used to mask the first five digits of the SIN in the header and footer. This parameter is optional and will use the default set in the Customize PDF File section of the site if not included.

maskSinForms: Parameter relevant for the T1 product only. It is used to mask the first five digits of the SIN in the forms. This parameter is optional and will use the default set in the Customize PDF File section of the site if not included.

Examples

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/T1/print?returnManagerYear=2020

Request body

{

"documents": [

{

"documentId": "221e7400-8d38-432e-a3ac-c988dfc6dc05",

"returns": [

{

"id": 0,

"language": "English"

}]

}],

"options": {

"printFormats": [

{

"id": "373b860e-fd62-2a30-df89-6717e18e74c9"

}],

"overridePrintedDate": "2021-04-20",

"mergePdf": true,

"maskSinHeaderFooter: true,

"maskSinForms": true

}

}

Response body

N/A

Notes:

  • A maximum of 20 documents can be included within a single request. Including more than 20 documents will result in an error.
  • In the firm settings, the options set on the Customize PDF file page, such as the PDF nomenclature, are used for printing via the Web API.
  • The user chooses the returns to print and the application determines which jurisdiction(s) are applicable to those returns. If the return is applicable to a jurisdiction, the print will include the relevant forms related to this jurisdiction.
  • The print features via the Web API for the T1 and T2 products are supported starting from CCH iFirm Taxprep Pro T1 2019 and CCH iFirm Taxprep Pro T2 2017. Printing a document prior to those years will result in an error.

/api/partner/1.0/{product}/documents/{documentId}/printslips (POST)

Endpoint authentication

When adopting OAuth 2.0 as an authentication method:

  • The user must fulfill the following security role requirements to trigger this endpoint. If he or she fails to obtain access to all the necessary security roles, a 403 error, Insufficient privileges to execute this request, is returned:

    • The user must be granted with at least one of the following security roles. He or she must 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 print documents to PDF without access to the below security role:

      • Tax – Print to PDF

  • 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

This endpoint prints to PDF the slips of a document specified in the URL of the endpoint. The T3 or TF product must be included in the URL. Once the print is initiated, a taskID is provided in the response location header and the status of the task can be retrieved by using the Tasks endpoint.

Model

{

"form": "string",

"dataType": "string",

"language": "English",

"options": {

"mergePdf": true

}

}

Properties

form: Name of the form for which to print the slips. Click here for the list of forms supported for this endpoint.

dataType: Data type of the slips to print. (Original, Amended, Cancelled)

language: Language to use for printing the return. This parameter is optional and will default to the language of correspondence of the contact if not specified.

options: Options related to the print job

mergePdf: Parameter used to merge the PDFs into a single PDF. This parameter is optional and will use the default set in the Customize PDF File section of the site if not specified.

Examples

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/TF/documents/72f70b71-c5ff-444a-8911-10787851632b/printslips

Request body

{

"form": "T4",

"dataType": "Original",

"language": "English",

"options": {

"mergePdf": true

}

}

Response body

N/A

Notes:

  • In the firm settings, the options set on the Customize PDF file page, such as the PDF nomenclature, are used for printing via the Web API.
  • All applicable copies and slips of the document for the form named in the request will be printed.
  • Only the T3 and TF products are supported by this endpoint. Printing the slips using a different product will result in an error.

/api/partner/1.0/print/{resultId} (GET)

Endpoint description

This endpoint returns the result of a print action (including all returns specified in the batch). An ID must be provided in the URL, which represents the resource of the print that was completed. This ID is provided by the Tasks endpoint.

Model

N/A

Properties

N/A

Examples

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/print/f3eb4d73-208b-4688-a0a0-99a954b2df25

Request body

N/A

Response body

{

"result": [

{

"fileId": "78600302-da96-4714-980a-fd69898c07cc",

"validUntil": "2020-04-20T00:00:00Z",

"content": [

{

"DocumentId": "de857e7e-c22f-44e6-8f3d-a47d957eed42",

"ReturnIds": [

0,

1

]

}]

}],

"errors": []

}

Notes:

  • PDF and .zip files generated by the Web API are stored on our servers for 24 hours. After this period, the files will be deleted.

/api/partner/1.0/files/{fileId} (GET)

Endpoint description

This endpoint allows for downloading Web API-generated files using the value of the field parameter generated by other endpoints.

Model

N/A

Properties

N/A

Examples

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/files/d4d50947332f4747b4173092bee23a73

Request body

N/A

Response body

[object Blob]