ClearTax Docs
Subscribe for Updates
  • Introduction to ClearTax APIs
  • ☁️Clear Finance Cloud
    • Introduction to Clear Finance Cloud
    • Learn Clear Finance Cloud Basics
      • API client
      • Access token
      • FTP client
      • How to get Custom Upload Template ID?
    • CFC API Reference
      • Resources and Masters
        • Sale Document Line Object
        • Purchase Document Line Object
      • Generate Access Token API
      • Ingestion API
        • Ingest Documents via File
          • Get Pre-signed URL
          • Upload File to Storage
          • Trigger File Ingestion
          • Get File Ingestion Status
        • (Deprecated) Ingest Documents via JSON
    • Notifications
  • 🇮🇳GLS API
    • GLS API Reference
      • Resources and Masters
      • Advanced Ingestion API Reference
        • Get Pre-signed URL
        • Upload File to Storage
        • Create Ingestion Activity
        • Get Ingestion Activity Status
  • 🇮🇳GST API
    • Introduction to GST API
    • GST 2.0 API Reference
      • Upload Documents
    • GST FTP Magnet
  • 🇮🇳Max ITC API
    • Introduction to Max ITC API
    • Getting Started with Max ITC API
    • Max ITC API Reference
      • Resources and Masters
        • Input and output templates
        • Error Code Master
        • Learn Max ITC API Architecture
      • Max ITC APIs
        • Fetch Max ITC Configuration
        • Upload Purchase Documents
          • Ingest PR via File
          • (Deprecated) Ingest PR via JSON
        • Trigger Max ITC Workflow
        • Get Max ITC Results
        • Postman Collection
    • Max ITC FTP Magnet
  • 🇮🇳TDS API
    • Introduction to TDS API
    • TDS API Reference
      • Resources and Masters
        • Deduction Document Line Objects
        • Output Template(Error)
      • TDS APIs
        • Upload Deductions
          • Ingest Deductions via File
            • Get Pre-signed URL
            • Upload File to Storage
            • Trigger File Ingestion
            • Get File Ingestion Status
          • (Deprecated) Ingest Deductions via JSON
  • 🇮🇳E-Invoicing API
    • Introduction to E-Invoicing API
    • Learn E-Invoicing API Basics
      • How to get E-Invoicing User Auth Token?
      • How to scan the E-Invoice QR code?
      • How to add GSTIN to E-Invoicing?
        • Clear IRP API Credentials
    • Learn E-waybill API Basics
    • E-Invoicing API Reference
      • Setting up your account
      • Clear Schema
        • Generate IRN
        • Cancel IRN
        • Get E-Invoice PDF
        • Get E-Invoice by IRN
        • Generate E-Waybill by IRN
        • Generate E-Waybill for Non-IRN documents
        • Bulk Generate E-Waybill for Non-IRN documents
        • Cancel E-Waybill
        • Get E-Waybill PDF
        • Update E-Waybill Transporter ID
        • Update E-Waybill Part-B
        • Extend E-Waybill Validity
        • Generate/Regenerate Consolidated EWB
        • Get Consolidated EWB PDF
        • Initiate Multi-Vehicle E-Waybills
        • Update EWB Status from NIC
        • Download E-waybills by Others
        • Get E-Waybill Download Status
        • Get E-Waybills
        • Get latest E-Waybill status from Government
        • Generate B2C Payment QR Code
          • Generate B2C Payment QR Code (Lite)
        • Get Signed PDF
        • Sign PDF API Base 64 Encoded
        • Send an E-Invoice via Email
        • Get Invoice Details
      • Government Schema
        • Generate IRN
        • Cancel IRN
        • Get Invoice by IRN
        • Generate E-Waybill by IRN
      • Resources and Masters
        • E-Invoice Object
        • Country Code Master
        • State Code Master
        • Pincode Master
        • Pincode State Mapping Pattern
        • Port Code Master
        • Currency Code Master
        • UQC Master
        • Tax Rates
        • Error Codes
    • E-Invoicing FTP Magnet
  • 🇮🇳Invoicing API
    • Invoicing API Reference
      • Create an Invoice
      • Create Document (Non-Sale)
      • Download PDF of a Document
      • Get Document details
      • Resources and Master
        • Country Master
        • State Master
        • Pincode Master
        • Port Master
        • Currency Master
        • Unit Master
        • Document Types
        • Supply Types
  • 🇲🇾E-INVOICING MALAYSIA API
    • E-Invoicing Malaysia API Reference
      • Resources and Masters
        • Error resolution guide
        • Frequently asked questions (FAQs)
        • E-Invoice Object
      • Generate Access Token API
      • Malaysia E-Invoicing APIs
        • Generate E-Invoice for a Document
        • Status Check for Submitted E-Invoice
        • Cancel E-Invoice
        • Upload E-Invoice
        • Get Documents
        • Get E-Invoice PDF
        • Get Document via UUID
        • Delete Invoice
        • Send Bulk Email
        • Search Taxpayer Tin API
  • E-Invoicing FTP Magnet (XML)
  • E-Invoicing FTP Magnet (Excel)
  • 🇸🇦E-Invoicing KSA API
    • Introduction to E-Invoicing KSA API
    • Learn E-Invoicing KSA API Basics
      • How to get E-Invoicing KSA Auth Token?
      • How to add a VAT number to KSA E-Invoicing Account?
      • How to add Branch for existing Vat to KSA E-Invoicing Account ?
      • How to register a device for a VAT?
      • How to generate OTP on ERAD Portal?
      • How to get Print Template ID?
      • KSA E-Invoicing Integration Architecture
    • E-Invoicing KSA API Reference
      • Resources and Masters
        • E-Invoice Object
        • Error Details Object
        • Data Types
        • Code Lists
        • Common Errors and Resolution
      • Authentication
      • Generate Access Token API
      • KSA E-Invoicing APIs
        • Generate E-Invoice
          • Additional Standard (B2B) E-Invoice Examples
          • Additional Simplified (B2C) E-Invoice Examples
        • Generate E-Invoice Async
        • Generate E-Invoice via XML
        • Send Signed E-Invoice XML To ZATCA
        • Get Bulk Invoice Lite
        • Get Invoice
        • Get E-Invoice PDF
        • Get E-Invoice PDF/A-3 with PDF API
        • Register Device
        • Get PCSID Generation Status
        • Renew PCSID
        • Generate E-Invoice (Phase I)
        • Generate QR Code (Phase I)
        • Generate Device ID
        • Generate CSID and PCSID
        • Send E-Invoice via Email
        • Add Business units API
    • E-Invoicing KSA FTP Magnet
    • E-Invoicing KSA XML reporting FTP Magnet
  • 🧩Add-ons and Extensions
    • SAP Add-on
      • SAP Connectivity Checklist
        • Steps to import SSL/TLS certificates in SAP
        • Steps to check ICM settings in SAP
        • Steps to test connectivity in SAP
        • Steps to troubleshoot connectivity issues in SAP
    • Tally Add-on
  • Microsoft Dynamics 365(F&O)
  • General
    • Go-Live Cutover Activity Checklist
    • How to check DNS resolution?
    • How to check hostname reachability?
    • How to check if hostname is trusted?
    • How to get the SSL certificate of a host?
  • ⭐GST GSP API
    • Introduction to GST GSP API
    • Getting Started with GST GSP API
    • GST GSP API Reference
      • Sample API
    • Migrating from Karvy GST GSP
  • ⭐E-Waybill GSP API
    • Introduction to E-Waybill GSP API
    • Getting Started with EWB GSP API
      • How to register EWB GSP on NIC?
      • Sandbox GSTIN for EWB GSP
    • E-Waybill GSP API Reference
      • Sample API
    • Migrating from Karvy EWB GSP
  • ⭐E-Invoicing GSP API
    • Introduction to E-Invoicing GSP API
    • Getting Started with EINV GSP API
      • How to register EINV GSP on IRP?
      • Sandbox GSTIN for EINV GSP
    • E-Invoicing GSP API Reference
      • Sample API
  • Subscribe for Updates
  • 🚫(Deprecated) GST 1.0 API
    • (Deprecated) Introduction to GST API
    • (Deprecated) Learn GST API Basics
    • (Deprecated) Getting Started with GST API
      • (Deprecated) How to set up ClearTax account?
      • (Deprecated) How to authenticate API requests?
      • (Deprecated) How to upload an invoice from File?
      • (Deprecated) How to create custom import template?
    • (Deprecated) GST 1.0 API Reference
      • Taxpayer Information
      • (Deprecated) Invoices
      • (Deprecated) Bills of Supply
      • (Deprecated) Credit Debit Notes (CDN)
      • (Deprecated) Advances
      • (Deprecated) Resources and Masters
        • (Deprecated) How to read GST error response
        • (Deprecated) Unit of Measurement master
        • (Deprecated) State master
        • (Deprecated) Document Classification/Section Name master
      • (Deprecated) Items
      • (Deprecated) Contacts
      • (Deprecated) GST File Upload API Reference
  • 🚫Deprecated E-Waybill API
    • (Deprecated) Introduction to E-Waybill API
    • (Deprecated) Learn E-Waybill API Basics
    • (Deprecated) Getting Started with E-Waybill API
    • (Deprecated) E-Waybill API Reference
      • (Deprecated) Resources and Masters
        • (Deprecated) Unit Master
        • (Deprecated) State Master
        • (Deprecated) Error Master
      • (Deprecated) E-Waybill JSON API Reference
        • (Deprecated) Generating E-Waybill
        • (Deprecated) Getting E-Waybill
        • (Deprecated) Updating E-Waybill
        • (Deprecated) Extending Validity of E-Waybill
        • (Deprecated) Multi-vehicle E-Waybill
        • (Deprecated) Printing E-Waybill
        • (Deprecated) Cancelling E-Waybill
        • (Deprecated) Generating Consolidated E-Waybill
        • (Deprecated) Getting Consolidated E-Waybill
        • (Deprecated) Regenerating Consolidated E-Waybill
        • (Deprecated) Printing Consolidated E-Waybill
      • (Deprecated) E-Waybill File Upload API Reference
        • (Deprecated) Creating or Updating Documents
        • (Deprecated) Getting Upload Status
        • (Deprecated) Getting Upload Validation
        • (Deprecated) Getting Upload History
        • (Deprecated) Rate Limiting & Best Practices
    • (Deprecated) E-Waybill FTP Magnet
Powered by GitBook
On this page
  • Max ITC API
  • Request Method
  • Request URL
  • Request Headers
  • Request Path Params
  • Request Query Params
  • Request Body
  • Example
  • Sample Request
  • Response Status Codes
  • Response Schema
  • Sample Response (Success)
  • Sample Response (Error)
  • API Validations
  • API Constraints

Was this helpful?

  1. Max ITC API
  2. Max ITC API Reference
  3. Max ITC APIs

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

Mandatory.

User auth token.

Request Path Params

There are no path parameters for this API.

Request Query Params

There are no query parameters for this API.

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

If no data needs to be ingested, provide fileListas an empty list. The API will run reconciliation against the data already available in Clear system.

Parameter
Data Type
Field Validations
Description

s3FileUrl

String

NA

Mandatory. Pre-Signed URL used to upload the file to storage.

userFileName

String

NA

Mandatory.

Filename used when generating the Pre-signed URL.

User Input Arguments Object

Parameter
Data Type
Field Validations
Description

gstins

List<String>

NA

Optional. List of GSTINs for which reconciliation will be triggered.

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.

pan

String

NA

Mandatory. PAN for which the reconciliation will be triggered.

pullReturnPeriodStart

String

Format: MMYYYY

Mandatory. Start Return Period for 2A Pull in MMYYYY format. Example : 042021 if the return period is April 2021.

pullReturnPeriodEnd

String

Format: MMYYYY

Mandatory. End Return Period for 2A Pull in MMYYYY format. Example : 042021 if the return period is April 2021.

reconReturnPeriodStart

String

Format: MMYYYY

Mandatory. Start Return Period for recon in MMYYYY format. Example : 042021 if the return period is April 2021.

reconReturnPeriodEnd

String

Format: MMYYYY

Mandatory. End Return Period for recon in MMYYYY format. Example : 042021 if the return period is April 2021

enableVoucherMerge

Boolean

NA

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]

templateId

String

NA

Mandatory. Template ID of the file uploaded. For a purchase document, the system template ID is "60e5613ff71f4a7aeca4336b".

reconType

Enum

Enum:

MAX_ITC_2A_PR, MAX_ITC_2B_PR, MAX_ITC_6A_PR, MAX_ITC_8A_PR

Mandatory. Type of Reconciliation to trigger.

reconResultFilter

Object

NA

Optional. Pass filtering criteria to filter response.

returnType

String

NA

MAX_ITC_2A_PR, MAX_ITC_2B_PR, MAX_ITC_8A_PR, MAX_ITC_6A_PR

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.

Return Period will be accepted only in MMYYYY format.

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

Mandatory

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]

negative

Boolean

NA

Optional : Negates the filtering criteria

source

String

Valid source string

Mandatory

Should be “metadata”

VoucherNos Object

Parameter
Data Type
Field Validations
Description

values

Array

NA

Mandatory

Should be an array of voucher numbers

E.g. [“voucher1”, “voucher2”]

negative

Boolean

NA

Optional : Negates the filtering criteria

source

String

Valid source string

Mandatory

Should be one of “pr” or “govt”

ReturnPeriod Object

Parameter
Data Type
Field Validations
Description

values

Array

Format: MMYYYY

Mandatory

Return period of the document

negative

Boolean

NA

Optional : Negates the filtering criteria

source

String

Valid source string

Mandatory

Should be one of “pr” or “govt”

MyGSTIN Object

Parameter
Data Type
Field Validations
Description

values

Array

Valid GSTIN number

Mandatory

Should be an array of GSTIN numbers

E.g. ["23AAAAAAAAAA123"]

negative

Boolean

NA

Optional : Negates the filtering criteria

source

String

Valid source string

Mandatory

Should be one of “pr” or “govt”

VendorCode Object

Parameter
Data Type
Field Validations
Description

values

Array

NA

Mandatory

Should be array of vendor codes

E.g. ["V1"]

negative

Boolean

NA

Optional : Negates the filtering criteria

source

String

Valid source string

Mandatory

Should be one of “pr” or “govt”

SupplierPan Object

values

Array

Valid GSTIN number

Mandatory

Should be an array of supplier PAN numbers

E.g. - [“CXXPS1795P”]

negative

Boolean

NA

Optional : Negates the filtering criteria

source

String

Valid source string

Mandatory

Should be one of “pr” or “govt”

Example

  1. Not in “Missing in PR”

reconResultFilter:{
    "matchStatus": {
        "values": ["missing_in_pr"], 
        "negative": true,
        "source": "metadata",
    }
}
  1. Not in “Missing in PR” & “Not in supplier pan = [“abcd…”]” (“abcd..” is PAN for which recon is triggered)

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:

{
  "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": "AAACO2563P",
    "pullReturnPeriodStart": "062023",
    "pullReturnPeriodEnd": "072023",
    "reconReturnPeriodStart": "062023",
    "reconReturnPeriodEnd": "072023",
    "reconType": "PAN_2A_PR_MAX_ITC",
    "templateId": "60e5613ff71f4a7aeca4336b"
  }
}

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

Enum: WORKFLOW_IN_PROGRESS,

WORKFLOW_FAILED

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

Enum: AUTHORIZATION_FAILED,

WORKFLOW_ALREADY_IN_PROGRESS,LICENSE_EXPIRED, QUOTA_EXCEEDED, PERMISSION_DENIED, INTERNAL_ERROR, INVALID_TEMPLATE, GSTIN_TOKEN_INACTIVE, INVALID_REQUEST_PARAMETER

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

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

Type of return

Sample Response (Success)

HTTP Status Code - 201 Created

{
    "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

Previous(Deprecated) Ingest PR via JSONNextGet Max ITC Results

Last updated 10 months ago

Was this helpful?

🇮🇳