Roll Forward Endpoints

/api/partner/1.0/{product}/rollforward (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 roll forward a document if he does not have access to the below security role:

      • Tax – Returns – Roll forward iFirm Tax

  • 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

Roll forward of one or more documents. Once the roll forward 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. The product (T1, T2, T3, or TF) must be included in the URL.

Model

{

"documentIds": [

"string"

]

}

Properties

documentIds: Array of document GUID(s), can be retrieved by creating a get request using the Document endpoint.

Examples

Request URL

https://mysite.cchifirm.ca/taxcan/api/partner/1.0/T1/rollforward

Request body

{

"documentIds": [

"ca87cb10-1433-4b64-821b-88aedc949257",

"5ffa3c83-b96e-4855-88f3-472b7608d62f"

]

}

Response body

N/A

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

Endpoint description

Returns the result of a roll forward process (including all returns specified in the batch). An ID must be provided in the URL, which represents the resource of the roll forward 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/rollforward/cb52bec5-5afa-4abb-b9c5-89c104b694a5

Request body

N/A

Response body

{

"result": [

{

"sourceDocumentId": "d1d880ac-ac5e-4542-b8ad-dc068e0b125d",

"rolledForwardDocumentIds": [

"8e7313ca-adea-4dd7-849e-211e65659a64"

],

"resultMessage": "Document rolled forward.'",

"resultCode": 501

},

{

"sourceDocumentId": "d139a1e0-7ae6-4dde-bc71-b10cac29e6f4",

"rolledForwardDocumentIds": [

"13bb9fe2-523a-4698-8695-dfdf8d26d479"

],

"resultMessage": "Document rolled forward.'",

"resultCode": 501

}

],

"errors": []

}

Note: For a list of all result and error codes relating to roll forward, consult the List of errors and messages.