T1 - Documents Endpoints

/api/partner/1.0/t1/documents/getList (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 the following security role:

      • Tax – Access T1 Product

    • When the user has access to the below security role, he is able to use the property customReturnManagerFilterIds in the request body to filter the results based on the custom filter Id(s) provided. In case the user does not have access to the said security role and he tries to apply a filter, an error 403: Insufficient privileges to execute this request is returned:

      • Tax – Return Manager – Custom Filters - Apply

    • Whenever the user has access to the below optional security role, he is able to get the value of the SIN property for T1 documents. In case the user does not have access to the said security role, the SIN property will be returned as empty in all the retrieved documents:

      • Tax – T1 – Return Manager – View SIN column

  • This endpoint validates against the user’s contact security and document visibility. If the user does not have access to a given document or to the contact associated to this document, the document will not be included in the response body.

Endpoint description

Returns a list of documents with all metadata available in the return manager for a specific year of the T1 product.

Model

{

"cursor": "string",

"search": "string",

"perPage": 0,

"sortColumn": "string",

"sortOrder": "string",

"filters": {},

"excludePlanner": true,

"customReturnManagerFilterIds": [

0

]

}

Properties

cursor: Optional parameter used to navigate between the pages of the resulting response. The "nextCursor" and "prevCursor" parameter, returned in the response of this endpoint, provides the value to use for the cursor parameter.

When this parameter is included in a request, the other parameters will be ignored.

search: Optional parameter used for filtering out results based on a string search.

perPage: Optional parameter that controls the number of results per page (1-500). If you do not include the per page parameter, the application will default to 500.

sortColumn: Optional parameter to sort on a specific columnID. The list of columnIDs can be viewed here. If you do not include the sortColumn parameter, the application will sort using the date modified column.

sortOrder: Optional parameter used to sort in ascending or descending order. If you do not include the sortOrder parameter, the application will default to ascending order.

filters: Optional parameter used for filtering out results based on column(s) value(s). One or more columnIDs must be provided with values to use. The list of columnIDs is available here.

excludePlanner: Optional parameter used to include or exclude planner files. If you do not include the excludePlanner parameter, the application will include the planner documents by default.

customReturnManagerFilterIds: Optional parameter used for filtering out results based on a custom filter. The ID of the custom filter must be provided, it can be found in the URL of each custom filter under “Settings/Tax/Custom Diagnostics & Custom Filters”

Examples

Example of getting a list of returns where the reviewer ID is 1:

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents/getList?returnManagerYear=2023

Request body

{

"perPage": 500,

"sortColumn": "date_modified",

"sortOrder": "Desc",

"filters": {

"reviewer_id": [

1

]

},

"excludePlanner": true

}

Response body

{

"result": [

{

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Homer",

"lastName": "Simpson",

"sin": "#########",

"noaStatus": "Not Available",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "3",

"efileStatuses": {

"t1": "Eligible",

"tp1": "Eligible",

"authorization": "Eligible",

"t1135": "Eligible",

"pad": "Not Eligible",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": {

"userId": 1,

"firstName": "Marc",

"lastName": "Lacasse"

},

"partner": null,

"contactGroup": {

"id": 37,

"name": "Vancouver"

},

"returnStatusId": "8539da61-963d-8e4d-aa30-cc91d89253d7",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}],

"documentId": "83a94a22-9218-4338-9c8e-b8f4173d89eb",

"isLocked": true,

"isPrivate": false,

"wasRolledForward": true,

"details”: “Details”,

"labelId": "46918af7-78dc-49bc-9a9d-c82218c18ba6",

"lastModificationTimestamp": "2024-04-20T13:32:47Z",

“lastModificationActionType”: "imported_afr"

},

{

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Georgette",

"lastName": "Upton",

"sin": "#########",

"noaStatus": "Not Applicable",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "768758758757696",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": {

"userId": 1,

"firstName": "Marc",

"lastName": "Lacasse"

},

"partner": {

"userId": 5,

"firstName": "Marko",

"lastName": "Johns"

},

"contactGroup": {

"id": 38,

"name": " Employees"

},

"returnStatusId": "2b346b5d-a880-4d5a-b4c8-219677c26210",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}],

"documentId": "fedf6b5d-3d01-4276-899e-19fe2d222388",

"isLocked": false,

"isPrivate": false,

"details”: “Scenario”,

"labelId": "10ae1db5-1736-44c0-b8ea-7f18aea380a1",

"lastModificationTimestamp": "2024-04-20T13:32:55Z",

“lastModificationActionType”: "published_noa"

}],

"prevCursor": null,

"nextCursor": null,

"errors": []

}

Example of getting a list of returns where the date modified is between two timestamps:

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents/getList?returnManagerYear=2023

Request body

{

"perPage": 500,

"sortColumn": "date_modified",

"sortOrder": "Desc",

"filters": {

"date_modified": [

"2024-04-21T01:11:45Z",

"2024-04-22T01:11:45Z"

]

},

"excludePlanner": true

}

Response body

{

"result": [

{

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Elda",

"lastName": "Wisoky",

"sin": "#########",

"noaStatus": "Not Applicable",

"hasTrackingCardLinked": true,

"returnId": 1000,

"clientCode": "768758758757745",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": {

"id": 40,

"name": "Montreal"

},

"returnStatusId": "8539da61-963d-8e4d-aa30-cc91d89253d7",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}],

"documentId": "89098b66-bc5a-470f-8747-ce5c213d72ed",

"isLocked": false,

"isPrivate": false,

"wasRolledForward": false,

"details”: “Scenario”,

"labelId": "46918af7-78dc-49bc-9a9d-c82218c18ba6",

"lastModificationTimestamp": "2024-04-21T20:52:20Z",

“lastModificationActionType”: "added_review_mark"

},

{

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Minnie",

"lastName": "Gerlach",

"sin": "#########",

"noaStatus": "Not Applicable",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "768758758757746",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": {

"id": 42,

"name": "self-employed"

},

"returnStatusId": "8539da61-963d-8e4d-aa30-cc91d89253d7",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}],

"documentId": "c7a5938c-26c9-4b2e-9d89-d1db23f78669",

"isLocked": false,

"isPrivate": false,

"wasRolledForward": false,

"details”: “”,

"labelId": "6ad6df83-c722-4a6d-bc49-490b4cd55336",

"lastModificationTimestamp": "2024-04-21T20:53:46Z",

“lastModificationActionType”: "deleted_breakdown"

},

{

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Adrianna",

"lastName": "Reichel",

"sin": "#########",

"noaStatus": "Not Applicable",

"hasTrackingCardLinked": true,

"returnId": 1000,

"clientCode": "768758758757748",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": null,

"returnStatusId": "8539da61-963d-8e4d-aa30-cc91d89253d7",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}],

"documentId": "c7a5938c-26c9-4b2e-9d89-d1db23f78669",

"isLocked": false,

"isPrivate": false,

"wasRolledForward": false,

"details”: “Test”,

"labelId": "343228d9-d030-4e3f-ad13-109b5ea58d6a",

"lastModificationTimestamp": "2024-04-21T20:53:46Z",

“lastModificationActionType”: "added_or_edited_spreadsheet"

},

{

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Chauncey",

"lastName": "Romaguera",

"sin": "#########",

"noaStatus": "Not Applicable",

"hasTrackingCardLinked": true,

"returnId": 1,

"clientCode": "768758758757747",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": {

"id": 40,

"name": "Montreal"

},

"returnStatusId": "8539da61-963d-8e4d-aa30-cc91d89253d7",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}],

"documentId": "c7a5938c-26c9-4b2e-9d89-d1db23f78669",

"isLocked": false,

"isPrivate": false,

"wasRolledForward": false,

"details”: “Test”,

"labelId": "72ef30e9-8ca8-46b2-ab0f-a90a55eade14",

"lastModificationTimestamp": "2024-04-21T20:53:46Z",

“lastModificationActionType”: "added_copy"

},

{

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Roma",

"lastName": "Rosenbaum",

"sin": "#########",

"noaStatus": "Available",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "768758758757844",

"efileStatuses": {

"t1": "Accepted",

"tp1": "Eligible",

"authorization": "Eligible",

"t1135": "Eligible",

"pad": "Not Eligible",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": {

"id": 37,

"name": "Vancouver"

},

"returnStatusId": "8539da61-963d-8e4d-aa30-cc91d89253d7",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}],

"documentId": "87db3db0-a2db-45c4-bf5f-d0cc7330af61",

"isLocked": true,

"isPrivate": false,

"wasRolledForward": false,

"details”: “Copy WebAPI”,

"labelId": "f5025bdd-a55f-4f17-8579-b20ea5611084",

"lastModificationTimestamp": "2024-04-21T20:59:09Z",

“lastModificationActionType”: " transmitted"

}],

"prevCursor": null,

"nextCursor": null,

"errors": []

}

Example of getting a list of returns where the date from a particular timestamp is modified to the current date:

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents/getList?returnManagerYear=2023

Request body

{

"perPage": 500,

"sortColumn": "date_modified",

"sortOrder": "Desc",

"filters": {

"date_modified": [

"2024-04-22T05:10:45Z"

]

},

"excludePlanner": true

}

Response body

{

"result": [

{

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Emile",

"lastName": "Cormier",

"sin": "#########",

"noaStatus": "Not Applicable",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "768758758757460",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": null,

"returnStatusId": "415c4238-9117-d545-85b5-a6c5717bdba1",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}],

"documentId": "0258582f-1c4a-4b5f-a4e2-8f90dd39c5bc",

"isLocked": false,

"isPrivate": false,

"wasRolledForward": true,

"details”: “”,

"labelId": "7efc32ce-d1ad-47ec-b5c0-e0fe9814f56c",

"lastModificationTimestamp": "2024-04-22T12:23:16Z",

“lastModificationActionType”: "activated_track_changes"

}],

"prevCursor": null,

"nextCursor": null,

"errors": []

}

Example of getting a list of returns where the T1 EFILE status is Eligible

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents/getList?returnManagerYear=2023

Request body

{

"perPage": 100,

"sortColumn": "date_modified",

"sortOrder": "Desc",

"filters": {

"t1_efile_status": [

"Eligible"

]

},

"excludePlanner": true

}

Response body

{

"result": [

{

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Jolie",

"lastName": "Ankunding",

"sin": "#########",

"noaStatus": "Not Available",

"hasTrackingCardLinked": true,

"returnId": 1,

"clientCode": "768758758757694",

"efileStatuses": {

"t1": "Eligible",

"tp1": "Eligible",

"authorization": "Eligible",

"t1135": "Eligible",

"pad": "Not Eligible",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": null,

"returnStatusId": "8539da61-963d-8e4d-aa30-cc91d89253d7",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}],

"documentId": "83a94a22-9218-4338-9c8e-b8f4173d89eb",

"isLocked": true,

"isPrivate": false,

"wasRolledForward": true,

"details”: “”,

"labelId": "c2ccaf9a-138a-4a06-996f-cbb4214bf701",

"lastModificationTimestamp": "2024-04-20T13:32:47Z",

“lastModificationActionType”: "changed_label"

}],

"prevCursor": null,

"nextCursor": null,

"errors": []

}

Example of getting a list of returns that is filtered based on a Custom Filter:

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents/getList?returnManagerYear=2023

Request body

{

"perPage": 100,

"sortColumn": "date_modified",

"sortOrder": "Desc",

"excludePlanner": true,

"customReturnManagerFilterIds": [

80

]

}

Response body

{

"result": [

{

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Frank",

"lastName": "Ankunding",

"sin": "#########",

"noaStatus": "Not Available",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "768754358757694",

"efileStatuses": {

"t1": "Eligible",

"tp1": "Eligible",

"authorization": "Accepted",

"t1135": "Eligible",

"pad": "Not Eligible",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": 2,

"tp1000": 2

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": null,

"returnStatusId": "8539da61-963d-8e4d-aa30-cc91d89253d7",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3",

"columnValues": {

"80": {

"ID.Towidt127": "0",

"T1.Towjac111": "62747.26",

"T1.Towjac132": "161.69",

}

}

}],

"documentId": "83a94a22-9218-4338-9c8e-b8f4436a98cf",

"isLocked": true,

"isPrivate": false,

"wasRolledForward": true,

"details”: “”,

"labelId": "b5655036-7810-47eb-9c3d-b42c25aec427",

"lastModificationTimestamp": "2024-04-20T13:32:47Z",

“lastModificationActionType”: "changed_data_entered"

}],

"prevCursor": null,

"nextCursor": null,

"errors": []

}

/api/partner/1.0/t1/documents (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 the following security roles:

      • Tax – Access T1 Product

      • Tax – Returns - Add

    • The user cannot create a document for a new contact if he does not have access to the below security role:

      • Contacts - View, Add and Edit Contacts

  • This endpoint validates against the user’s contact security. If the user does not have access to the contact associated to the document he is requesting to create, an error 404: Resource not found in the system is returned.

Endpoint description

Creates a new T1 document and, once created, returns the metadata of the new document, including the ID. This endpoint can manage to create a document from both an existing contact or for a new contact.

Creating a T1 document from an existing contact

Model

{

"year": 2023,

"isPlanner": false,

"details": "string",

"labelId": "00000000-0000-0000-0000-000000000000",

"existingClientCode": "string"

}

Properties

year: The year in which you would like the document to be created.

isPlanner: Controls whether or not the document created is a planner document. Please note that a planner document can only be created in the latest year of the T1 product.

details: Details to add to the document (optional).
labelId: The value of the label to be associated to the document (optional).

existingClientCode: Client Code of the existing contact for which you want to create a document.

Creating a T1 document for a new contact

Model

{

"year": 2023,

"isPlanner": false,

"newClient": {

"title": "Mr",

"firstName": "string",

"lastName": "string",

"sin": "#########",

"birthDate": "1968-05-24",

"code": "string",

"group1Id": -1,

"group2Id": -1

},

"details": "string",

"labelId": "00000000-0000-0000-0000-000000000000"

}

Properties

year: The year in which you would like the document to be created.

isPlanner: Controls whether or not the document created is a planner document. Please note that a planner document can only be created in the latest year of the T1 product.

title: Title of the taxpayer (Mr., Mrs., or Ms.).

firstName: First name of the taxpayer.

lastName: Last name of the taxpayer.

sin: Social insurance number of the taxpayer.

birthDate: Date of birth of the taxpayer.

code: Client code of the new contact.

details: Details to add to the document (optional).

labelId: The value of the label to be associated to the document (optional).

group1Id: ID of the group1 option (optional: default to -1)

group2Id: ID of the group2 option

Note: The “code” parameter is optional if the Auto assign numeric client codes for new contacts option has been enabled for your site.

Examples

 

Existing contact

New contact

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents

Request body

{

"year": 2023,

"isPlanner": false,

"details": "Copy-1",

"labelId": "415c4238-9117-d545-75k5-a6o5785bdba1",

"existingClientCode": "Abc123"

}

{

"year": 2023,

"isPlanner": false,

"newClient": {

"title": "Mr",

"firstName": "Robert",

"lastName": "Tremblay",

"sin": "#########",

"birthDate": "1968-05-04",

"code": "Abc1234",

"group1Id": -1,

"group2Id": -1

},

"details": "Copy-2",

"labelId": "415c4238-9117-d545-75k5-a6o5785bdba1"

}

Response body

{

"result": {

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "John",

"lastName": "Smith",

"sin": "#########",

"noaStatus": "Not Applicable",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "Abc123",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": null,

"returnStatusId": "415c4238-9117-d545-85b5-a6c5717bdba1",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}

],

"documentId": "2ad061f8-de4e-4199-9e54-053b5bf18fdf",

"isLocked": false,

"isPrivate": false,

"wasRolledForward": false,

"details": "Copy-1",

"labelId": "415c4238-9117-d545-75k5-a6o5785bdba1",

"lastModificationTimestamp": "2024-09-23T12:54:49Z",

“lastModificationActionType”: "changed_preparer_profile"

},

"errors": []

}

{

"result": {

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Robert",

"lastName": "Tremblay",

"sin": "#########",

"noaStatus": "Not Applicable",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "Abc1234",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": 0,

"tp1000": 0

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": null,

"returnStatusId": "415c4238-9117-d545-85b5-a6c5717bdba1",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}

],

"documentId": "2ad061f8-de4e-4199-9e54-053b5bf18fdf",

"isLocked": false,

"isPrivate": false,

"wasRolledForward": false,

"details": "Copy-2",

"labelId": "415c4238-9117-d545-75k5-a6o5785bdba1",

"lastModificationTimestamp": "2024-09-23T12:54:49Z",

“lastModificationActionType”: "changed_preparer_profile"

},

"errors": []

}

Creating a T1 planner document from an existing contact

Model

{

"year": 2023,

"isPlanner": true,

"details": "string",

"labelId": "00000000-0000-0000-0000-000000000000",

"existingClientCode": "string"

}

Properties

year: The year in which you would like the document to be created.

isPlanner: Controls whether or not the document created is a planner document. Please note that a planner document can only be created in the latest year of the T1 product.

details: Details to add to the document (optional).

labelid: The value of the label to be associated to the document (optional).

existingClientCode: Client Code of the existing contact for which you want to create a document

Note: When creating a T1 planner document, the year entered in the request represents the T1 version that will create the planner document. For example, to create a 2024 T1 planner document, the property “year” must be set to “2023” and the “isPlanner” property must be set to “True.”

Creating a T1 planner document for a new contact

Model

{

"year": 2023,

"isPlanner": true,

"newClient": {

"title": "Mr",

"firstName": "string",

"lastName": "string",

"sin": "#########",

"birthDate": "1968-05-24",

"code": "string",

"group1Id": -1,

"group2Id": -1

},

"details": "string",

"labelId": "00000000-0000-0000-0000-000000000000"

}

Properties

year: The year in which you want the document to be created.

isPlanner: Controls whether or not the document created is a planner document. Please note that a planner document can only be created in the latest T1 year.

title: Title of the taxpayer (Mr., Mrs., or Ms.).

firstName: First name of the taxpayer.

lastName: Last name of the taxpayer.

sin: Social insurance number of the taxpayer.

birthDate: Date of birth of the taxpayer.

code: Client code of the new contact.

details: Details to add to the document (optional).

labelId: The value of the label to be associated to the document (optional).

group1Id: ID of the group1 option (optional: default to -1)

group2Id: ID of the group2 option (optional: default to -1)

Note: When creating a T1 planner document, the year entered in the request represents the T1 version that will create the Planner document. For example, to create a T1 planner 2024 document, the “year” property must be set to “2023” and the “isPlanner” property must be set to “True.”

Examples

 

Existing contact

New contact

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents

Request body

{

"year": 2023,

"isPlanner": true,

"details": "Copy-1",

"labelId": "415c4238-9117-d545-75k5-a6o5785bdba1",

"existingClientCode": "Abc123"

}

{

"year": 2023,

"isPlanner": true,

"newClient": {

"title": "Mr",

"firstName": "Robert",

"lastName": "Tremblay",

"sin": "#########",

"birthDate": "1968-05-04",

"code": "Abc1234",

"group1Id": -1,

"group2Id": -1

},

"details": "Copy-2",

"labelId": "415c4238-9117-d545-75k5-a6o5785bdba1",

}

Response body

{

"result": {

"year": 2023,

"isPlanner": true,

"taxpayers": [

{

"firstName": "John",

"lastName": "Smith",

"sin": "#########",

"noaStatus": "Not Applicable",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "Abc123",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": null,

"returnStatusId": "415c4238-9117-d545-85b5-a6c5717bdba1",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}

],

"documentId": "2ad061f8-de4e-4199-9e54-053b5bf18fdf",

"isLocked": false,

"isPrivate": false,

"wasRolledForward": false,

"details": "Copy-1",

"labelId": "415c4238-9117-d545-75k5-a6o5785bdba1",

"lastModificationTimestamp": "2024-09-23T12:54:49Z",

“lastModificationActionType”: "changed_preparer_profile"

},

"errors": []

}

{

"result": {

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Robert",

"lastName": "Tremblay",

"sin": "#########",

"noaStatus": "Not Applicable",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "Abc1234",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": 0,

"tp1000": 0

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": null,

"returnStatusId": "415c4238-9117-d545-85b5-a6c5717bdba1",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}

],

"documentId": "2ad061f8-de4e-4199-9e54-053b5bf18fdf",

"isLocked": false,

"isPrivate": false,

"wasRolledForward": false,

"details": "Copy-2",

"labelId": "415c4238-9117-d545-75k5-a6o5785bdba1",

"lastModificationTimestamp": "2024-09-23T12:54:49Z",

“lastModificationActionType”: "changed_preparer_profile"

},

"errors": []

}

/api/partner/1.0/t1/documents/recycleBin (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 the following security roles:

      • Tax – Access T1 Product

      • Tax – Recycle Bin – Access

    • Whenever the user has access to the below optional security role, he is able to get the value of the SIN property for T1 documents. In case the user does not have access to the said security role, the SIN property will be returned as empty in all the T1 retrieved documents:

      • Tax – T1 – Return Manager – View SIN column

  • This endpoint validates against the user’s contact security and document visibility. If the user does not have access to a given document or to the contact associated to this document, the document will not be included in the response body.

Endpoint description

Returns a list of all T1 documents, with their associated metadata, that have been deleted and are in the recycle bin. This endpoint will also return all private documents that may not be visible to all users when accessing the recycle bin modal through the user interface.

Examples

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents/recycleBin

Request body

N/A

Response body

{

"result": [{

"deletedBy": "UserName",

"deletedOn": "2024-07-07T14:50:26Z",

"year": 2023,

"isPlanner": false,

"taxpayers": [{

"firstName": "Selmer",

"lastName": "Lang",

"sin": "#########",

"noaStatus": "Eligible",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "10819",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Eligible"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": {

"userId": 39,

"firstname": "Marc",

"lastname": "Lacasse"

},

"reviewer": {

"userId": 54,

"firstname": "Alex",

"lastname": "Tremblay"

},

"partner": null,

"contactGroup": null,

"returnStatusId": "415c4238-9117-d545-85b5-a6c5717bdba1",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}],

"documentId": "4e3f9358-9e0c-4488-a617-bd62f44b1a65",

"isLocked": false,

"isPrivate": false,

"wasRolledForward": false,

"details": "Details",

"labelId": "415c4238-9117-d545-75k5-a6o5785bdba1",

"lastModificationTimestamp": "2024-07-07T14:50:26Z",

“lastModificationActionType”: "moved_return_to_recycle_bin"

}],

"errors": []

}

/api/partner/1.0/t1/documents/{documentId} (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 the following security role:

      • Tax – Access T1 Product

  • This endpoint validates against the user’s contact security and return 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

Returns a specific T1 document with all the metadata available in the return manager.

The document GUID must be inserted in the request URL.

Model

N/A

Properties

N/A

Examples

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents/cfbf5953-bd98-421e-ba9d-7557a68743e1

Request body

N/A

Response body

{

"result": {

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Ray",

"lastName": "Williams",

"sin": "#########",

"noaStatus": "Not Applicable",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "Abc123",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": null,

"partner": null,

"contactGroup": null,

"returnStatusId": "415c4238-9117-d545-85b5-a6c5717bdba1",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}

],

"documentId": "cfbf5953-bd98-421e-ba9d-7557a68743e1",

"isLocked": false,

"isPrivate": false,

"wasRolledForward": false,

"details": "",

"labelId": "415c4238-9117-d545-75k5-a6o5785bdba1",

"lastModificationTimestamp": "2024-09-23T12:18:47Z",

“lastModificationActionType”: "updated_comment"

},

"errors": []

}

Note: The “group1Id” and “group2Id” properties are always returned in the document’s endpoint response even if the groups are not activated for your site. The ID -1 represents the “None” group option.

/api/partner/1.0/t1/documents/{documentId}/copy (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 the following security roles:

      • Tax – Access T1 Product

      • Tax – Returns – Copy

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

Copies a specific document in the T1 product. The GUID of the document must be inserted in the URL of the request.

Model

{

"details": "string",

"labelId": "00000000-0000-0000-0000-000000000000"

}

Properties

details: Optional parameter to add details to the copied document.

labelId: Optional parameter to add a label to the copied document.

Examples

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents/fedf6b5d-3d01-4276-899e-19fe2d222388/copy

Request body

{

"details": "Scenario 1",

"labelId": "415c4238-9117-d545-75k5-a6o5785bdba1"

}

Response body

{

"result": {

"year": 2023,

"isPlanner": false,

"taxpayers": [

{

"firstName": "Georgette",

"lastName": "Upton",

"sin": "166102632",

"noaStatus": "Not Applicable",

"hasTrackingCardLinked": true,

"returnId": 0,

"clientCode": "768758758757696",

"efileStatuses": {

"t1": "Not Eligible",

"tp1": "Not Applicable",

"authorization": "Not Eligible",

"t1135": "Not Applicable",

"pad": "Not Applicable",

"mr69": "Not Applicable"

},

"eSignatureStatuses": {

"t183": "0",

"tp1000": "0"

},

"preparer": null,

"reviewer": {

"userId": 1,

"firstName": "Marc",

"lastName": "Lacasse"

},

"partner": {

"userId": 5,

"firstName": "Mark",

"lastName": "Johns"

},

"contactGroup": null,

"returnStatusId": "2b346b5d-a880-4d5a-b4c8-219677c26210",

"group1Id": -1,

"group2Id": -1,

"environmentId": "d6d50e87-7189-4ac9-b136-cc849412f4c3"

}],

"documentId": "b06b6f17-3b40-4d4b-88ba-00d8141e710d",

"isLocked": false,

"isPrivate": false,

"wasRolledForward": false,

"details": "Scenario 1",

"labelId": "415c4238-9117-d545-75k5-a6o5785bdba1",

"lastModificationTimestamp": "2024-04-22T17:10:56Z",

“lastModificationActionType”: "printed_return"

},

"errors": []

}

wasRolledForward parameter limitation

The parameter “wasRolledForward” is returned for every year and period. However, the parameter will display the "false" default value for all documents prior to T1 2020.

/api/partner/1.0/t1/documents/{documentId}/couple (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 the following security roles:

      • Tax – Access T1 Product

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

Endpoint description

Couples a T1 document with an existing document as a Spouse or Dependant. The ID of the main taxpayer’s document (GUID) must be provided in the URL.

Model

{

"documentId": "string",

“taxpayer”: “string”

}

Properties

documentId: The ID of the document to couple as spouse or dependant. The GUID of the document can be retrieved by creating a get request using the Documents endpoint.

taxpayer: The relationship type with the taxpayer whose documentId is provided in the URL. This property can only be “spouse” or “dependant”.

Examples

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents/fedf6b5d-3d01-4276-899e-19fe2d222388/couple

Request body

{

"documentId": " fedf6b5d-3d01-4276-899e-19fe2d225143",

“taxpayer”: “spouse”

}

Response body

{

"errors": []

}

/api/partner/1.0/t1/documents/{documentId}/uncouple (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 the following security roles:

      • Tax – Access T1 Product

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

Endpoint description

Uncouples a T1 return from an existing document. The ID of the document (GUID) must be included in the URL.

Model

{

"returnId": 0

}

Properties

returnId: The return Id to be uncoupled from the document (1 for spouse and 1000+ for dependants).

Examples

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents/fedf6b5d-3d01-4276-899e-19fe2d222388/uncouple

Request body

{

"returnId": 1

}

Response body

{

"errors": []

}

/api/partner/1.0/t1/documents/delete (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 the following security roles:

      • Tax – Access T1 Product

      • Tax – Returns – Delete

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

Endpoint description

Deletes one document or a batch of documents and moves them to the Recycle Bin. The GUID of the document(s) must be provided in the request body.

Model

{

"documentIds": [

"string"

]

}

Properties

documentIds: The GUID(s) array of documents can be retrieved by creating a get request using the Documents endpoint.

Examples

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/t1/documents/delete

Request body

{

"documentIds": [

" fedf6b5d-3d01-4276-899e-19fe2d222388"

]

}

Response body

{

"errors": []

}