# Trigger Max ITC Workflow

### Max ITC API

This API will trigger MaxITC workflow based on the inputs provided by the user in the request payload. It is a bi-functional API with the option to ingest PR data or skip ingestion if the user wants to trigger MaxITC for the existing purchase data in Clear. 

### Request Method

POST

### Request URL

```
{{BASE_URL}}/integration/v1/maxItc/triggerWorkflow
```

### Request Headers

|       Parameter       | Data Type | Field Validations | Description                              |
| :-------------------: | :-------: | :---------------: | ---------------------------------------- |
| x-cleartax-auth-token |   String  |         NA        | <p>Mandatory.</p><p>User auth token.</p> |

### Request Path Params

There are no path parameters for this API.&#x20;

### Request Query Params

There are no query parameters for this API.&#x20;

### Request Body

| Parameter     | Data Type | Field Validations | Description                                                                                                                                        |
| ------------- | --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| fileList      | Array     | NA                | Conditional. List of File Objects. Each File Object contains information about the file which is to be ingested before running the reconciliation. |
| userInputArgs | Object    | NA                | Mandatory. User input arguments for the running reconciliation.                                                                                    |

#### File List

{% hint style="info" %}
If no data needs to be ingested, provide ***`fileList`***&#x61;s an empty list. The API will run reconciliation against the data already available in Clear system.
{% endhint %}

| Parameter    | Data Type | Field Validations | Description                                                                |
| ------------ | --------- | ----------------- | -------------------------------------------------------------------------- |
| s3FileUrl    | String    | NA                | Mandatory. Pre-Signed URL used to upload the file to storage.              |
| userFileName | String    | NA                | <p>Mandatory. </p><p>Filename used when generating the Pre-signed URL.</p> |

#### User Input Arguments Object&#x20;

<table><thead><tr><th width="209">Parameter</th><th width="150">Data Type</th><th>Field Validations </th><th>Description</th></tr></thead><tbody><tr><td>gstins</td><td>List&#x3C;String></td><td>NA</td><td><p>Optional. List of GSTINs for which reconciliation will be triggered. </p><p>Default: Can be an empty list or NULL. We will take all GSTINs under the provided PAN in the pan field and will be considered for reconciliation and GSTR Pull.</p></td></tr><tr><td>pan</td><td>String</td><td>NA</td><td>Mandatory. PAN for which the reconciliation will be triggered.</td></tr><tr><td>pullReturnPeriodStart</td><td>String</td><td>Format: MMYYYY</td><td>Mandatory. Start Return Period for 2A Pull in <em><mark style="color:blue;">MMYYYY</mark></em> format. Example : 042021 if the return period is April 2021.</td></tr><tr><td>pullReturnPeriodEnd</td><td>String</td><td>Format: MMYYYY</td><td>Mandatory. End Return Period for 2A Pull in <em><mark style="color:blue;">MMYYYY</mark></em> format. Example : 042021 if the return period is April 2021.</td></tr><tr><td>reconReturnPeriodStart</td><td>String</td><td>Format: MMYYYY</td><td>Mandatory. Start Return Period for recon in MMYYYY format. Example : 042021 if the return period is April 2021. </td></tr><tr><td>reconReturnPeriodEnd</td><td>String</td><td>Format: MMYYYY</td><td>Mandatory. End Return Period for recon in MMYYYY format. Example : 042021 if the return period is April 2021</td></tr><tr><td>enableVoucherMerge</td><td>Boolean</td><td>NA</td><td>If enabled, vouchers pertaining to same document will get merged in the same document e.g. doc1 [v1, v2] If disabled, vouchers will get overridden in the document E.g. doc1 [v2]</td></tr><tr><td>templateId</td><td>String</td><td>NA</td><td>Mandatory. Template ID of the file uploaded. For a purchase document, the system template ID is "60e5613ff71f4a7aeca4336b".  </td></tr><tr><td>reconType</td><td>Enum</td><td><p>Enum: </p><p>MAX_ITC_2A_PR,  MAX_ITC_2B_PR, MAX_ITC_6A_PR,  MAX_ITC_8A_PR</p></td><td>Mandatory. Type of Reconciliation to trigger.</td></tr><tr><td>reconResultFilter</td><td>Object</td><td>NA</td><td>Optional. Pass filtering criteria to filter response.</td></tr><tr><td>returnType</td><td>String</td><td>NA</td><td>MAX_ITC_2A_PR, MAX_ITC_2B_PR, MAX_ITC_8A_PR, MAX_ITC_6A_PR</td></tr></tbody></table>

{% hint style="info" %}
***gstins*** can be an empty list or NULL. We will take all GSTINs under the provided PAN in ***pan*** field for reconciliation and GSTN Pull in such case.
{% endhint %}

{% hint style="info" %}
Return Period will be accepted only in <mark style="color:blue;">MMYYYY</mark> format.
{% endhint %}

#### ReconResultFilter Object

| Parameter    | Data Type | Field Validations | Description                                                             |
| ------------ | --------- | ----------------- | ----------------------------------------------------------------------- |
| matchStatus  | Object    | NA                | Optional; Filter based on match status e.g. exact, missing\_in\_pr etc. |
| voucherNos   | Object    | NA                | Optional; Filter based on voucher number                                |
| returnPeriod | Object    | NA                | Optional; Filter based on govt / pr return period                       |
| myGstin      | Object    | NA                | Optional; Filter based on customer gstin                                |
| vendorCode   | Object    | NA                | Optional; Filter based on voucher code                                  |
| supplierPan  | Object    | NA                | Optional; Filter based on supplier PAN                                  |

#### MatchStatus Object

| Parameter | Data Type | Field Validations   | Description                                                                                                                                                                                |
| --------- | --------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| values    | Array     | Valid MatchStatus   | <p>Mandatory</p><p>Values should be one or more of \[exact, suggested, manual, mismatch, missing\_in\_pr, missing\_in\_govt, ignored\_pr, ignored\_govt, excluded\_pr, excluded\_govt]</p> |
| negative  | Boolean   | <p>NA<br></p>       | Optional : Negates the filtering criteria                                                                                                                                                  |
| source    | String    | Valid source string | <p>Mandatory</p><p>Should be  “metadata”</p>                                                                                                                                               |

#### VoucherNos Object

| Parameter | Data Type | Field Validations   | Description                                                                                       |
| --------- | --------- | ------------------- | ------------------------------------------------------------------------------------------------- |
| values    | Array     | NA                  | <p>Mandatory</p><p>Should be an array of voucher numbers</p><p>E.g. \[“voucher1”, “voucher2”]</p> |
| negative  | Boolean   | <p>NA<br></p>       | Optional : Negates the filtering criteria                                                         |
| source    | String    | Valid source string | <p>Mandatory</p><p>Should be one of “pr” or “govt”</p>                                            |

#### ReturnPeriod Object

| Parameter | Data Type | Field Validations   | Description                                            |
| --------- | --------- | ------------------- | ------------------------------------------------------ |
| values    | Array     | Format: MMYYYY      | <p>Mandatory</p><p>Return period of the document</p>   |
| negative  | Boolean   | <p><br>NA</p>       | Optional : Negates the filtering criteria              |
| source    | String    | Valid source string | <p>Mandatory</p><p>Should be one of “pr” or “govt”</p> |

#### MyGSTIN Object

| Parameter | Data Type | Field Validations   | Description                                                                                 |
| --------- | --------- | ------------------- | ------------------------------------------------------------------------------------------- |
| values    | Array     | Valid GSTIN number  | <p>Mandatory </p><p>Should be an array of GSTIN numbers</p><p>E.g. \["23AAAAAAAAAA123"]</p> |
| negative  | Boolean   | <p>NA<br></p>       | Optional : Negates the filtering criteria                                                   |
| source    | String    | Valid source string | <p>Mandatory</p><p>Should be one of “pr” or “govt”</p>                                      |

#### VendorCode Object

| Parameter | Data Type | Field Validations   | Description                                                               |
| --------- | --------- | ------------------- | ------------------------------------------------------------------------- |
| values    | Array     | NA                  | <p>Mandatory</p><p>Should be array of vendor codes</p><p>E.g. \["V1"]</p> |
| negative  | Boolean   | <p>NA<br></p>       | Optional : Negates the filtering criteria                                 |
| source    | String    | Valid source string | <p>Mandatory</p><p>Should be one of “pr” or “govt”</p>                    |

#### SupplierPan Object

| values   | Array   | Valid GSTIN number  | <p>Mandatory </p><p>Should be an array of supplier PAN numbers</p><p>E.g. - \[“CXXPS1795P”]</p> |
| -------- | ------- | ------------------- | ----------------------------------------------------------------------------------------------- |
| negative | Boolean | <p>NA<br></p>       | Optional : Negates the filtering criteria                                                       |
| source   | String  | Valid source string | <p>Mandatory</p><p>Should be one of “pr” or “govt”</p>                                          |

### Example

1. Not in “Missing in PR”

```json
reconResultFilter:{
    "matchStatus": {
        "values": ["missing_in_pr"], 
        "negative": true,
        "source": "metadata",
    }
}
```

2. Not in “Missing in PR” & “Not in supplier pan = \[“abcd…”]” (“abcd..” is PAN for which recon is triggered)

```json
reconResultFilter:{
    "matchStatus": {
        "values": ["missing_in_pr"], 
        "negative": true,
        "source": "metadata",
    },
"supplierPan": {
        "values": ["<Insert PAN for which recon is being triggered>"],
 "negative": true,
        "source": "pr"
    }
}
```

### Sample Request

Request Body:

```json
{
  "fileList": [
        {
            "userFileName": "test123.xls",
            "s3FileUrl": "https://ingestionv2-prod.s3.ap-south-1.amazonaws.com/4fee63cb-6f7c-455c-9c13-6f3cdb7a0e08/MaxItc/2021/NOVEMBER/e3704ce6d0074d9e8378c716224bc48f/OriginalFileName/e3704ce6d0074d9e8378c716224bc48f__1637316021949.xls"
        }
  ],
 "userInputArgs": {
        "gstins": [],
        "pan": "AAFCD5862R",
        "templateId": "60e5613ff71f4a7aeca4336b",
        "reconType": "MAX_ITC_2A_PR",
        "pullReturnPeriodStart": "042021",
        "reconReturnPeriodStart": "042021",
        "pullReturnPeriodEnd": "052022",
        "reconReturnPeriodEnd": "052022"
    }

}
```

### Response Status Codes

| HTTP Status Code | Description                       |
| ---------------- | --------------------------------- |
| 201              | Triggered ingestion successfully. |
| 400              | Bad request.                      |
| 401              | Unauthorized                      |
| 500              | Internal Server Error             |

### Response Schema

| Parameter     | Data Type   | Field Validations                                           | Description                                                                            |
| ------------- | ----------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| workflowId    | String      | NA                                                          | Workflow Id to track the status of the triggered workflow.                             |
| status        | String      | <p>Enum: WORKFLOW\_IN\_PROGRESS,</p><p>WORKFLOW\_FAILED</p> | Status of the workflow.                                                                |
| errors        | List\<JSON> | NA                                                          | Array of Error Objects. If there are no errors, then this field will be an empty list. |
| userInputArgs | Object      | NA                                                          | User Input for the request.                                                            |

**Error Object**

| Parameter       | Data Type | Field Validations                                                                                                                                                                                                         | Description                                    |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| errorCode       | String    | <p>Enum: AUTHORIZATION\_FAILED, </p><p>WORKFLOW\_ALREADY\_IN\_PROGRESS,LICENSE\_EXPIRED, QUOTA\_EXCEEDED, PERMISSION\_DENIED, INTERNAL\_ERROR, INVALID\_TEMPLATE, GSTIN\_TOKEN\_INACTIVE, INVALID\_REQUEST\_PARAMETER</p> | API Error Code                                 |
| errorMessage    | String    | NA                                                                                                                                                                                                                        | Name of the field if it is a validation error. |
| errorValues     | Array     | NA                                                                                                                                                                                                                        | List of error values.                          |
| errorResolution | String    | NA                                                                                                                                                                                                                        | Possible resolution.                           |

#### User Input Arguments Object&#x20;

| templateId             | String | NA             | Template Id                                                       |
| ---------------------- | ------ | -------------- | ----------------------------------------------------------------- |
| pan                    | String | NA             | PAN for which the reconciliation is triggered.                    |
| gstins                 | String | NA             | List of GSTINs for which reconciliation is triggered. considered. |
| reconType              | String | NA             | Type of Reconciliation trigger.                                   |
| pullReturnPeriodStart  | String | Format: MMYYYY | Start Return Period for 2A Pull                                   |
| pullReturnPeriodEnd    | String | Format: MMYYYY | End Return Period for 2A Pull                                     |
| reconReturnPeriodStart | String | Format: MMYYYY | Start Return Period for recon                                     |
| reconReturnPeriodEnd   | String | Format: MMYYYY | End Return Period for recon                                       |
| returnType             | String | NA             | <p><br>Type of return</p>                                         |

### Sample Response (Success)

HTTP Status Code - 201 Created

```json
{
    "workflowId": "68ed4fd2-06c2-4f1c-a80f-31514d203d5d",
    "status": "WORKFLOW_IN_PROGRESS",
    "errors": [],
    "userInputArgs": {
        "templateId": "60e5613ff71f4a7aeca4336b",
        "sheetName": null,
        "groupId": null,
        "metadata": null,
        "pan": "AAFCD5862R",
        "gstins": [],
        "reconType": "MAX_ITC_2A_PR",
        "pullReturnPeriodStart": "062023",
        "pullReturnPeriodEnd": "072023",
        "reconReturnPeriodStart": "062023",
        "reconReturnPeriodEnd": "072023",
        "enableVoucherMerge": false,
        "convertErpChannelValidationAsWarning": false,
        "reconResultFilter": null,
        "returnType": "GSTR2A"
    }
}
```

### Sample Response (Error)

HTTP Status Code - 401 Unauthorized

```
{
    "workflowId": null,
    "status": null,
    "errors": [
        {
            "errorCode": "AUTHORIZATION_FAILED",
            "errorMessage": "Invalid Auth Token",
            "errorField": null,
            "errorValues": null,
            "errorResolution": null
        }
    ],
    "userInputArgs": null
}
```

### API Validations

Currently there are no known validations.

### API Constraints

We place the following four constraints as a ‘fair usage policy’ on our APIs:

1. ERP Trigger workflow cannot be triggered more than 24 times per day/PAN in Production and 48 times per day/PAN in SaaS sandbox environments from a single workspace
2. Customer is expected to use ingestion API for transferring historic data instead of triggering recon
3. Customer is expected to use ingestion API for transferring historic data instead of triggering recon


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cleartax.in/cleartax-docs/max-itc-api/max-itc-api-reference/max-itc-apis/trigger-max-itc-workflow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.