Due Forms

Description: Fetch all the Due forms for a specific DueFrom to DueTo period for the Due Forms.

API Name: /Forms/DueForms

HTTP Method: GET

HTTP Status Codes:

HTTP Status Codes Description
1 200 Ok
2 204 No Content
3 400 Bad Request
4 500 Internal Server Error 
/// OK [200]
{
  "Data": {
      "Result": [{
              "LocationId": "",
              "ReportingYear": "2024",
              "ReportingCountry": "US",
              "ReportingPeriodFromDate": "2023-07-01",
              "ReportingPeriodToDate": "2023-12-31",
              "DueDate": "2024-01-31",
              "ReportingPeriodicity": "HY",
              "ReportingPeriodNum": "02",
              "FormId":"CO_DR0100",
              "SubmissionMode":"M"
              },
              {
              "LocationId": "",
              "ReportingYear": "2024",
              "ReportingCountry": "US",
              "ReportingPeriodFromDate": "2023-07-01",
              "ReportingPeriodToDate": "2023-12-31",
              "DueDate": "2024-01-31",
              "ReportingPeriodicity": "M",
              "ReportingPeriodNum": "12",
              "FormId":"TX_01-115-116-Combo",
              "SubmissionMode":"M"
              }
      ]
  }
 }

/// No Content example [204]
/// For this case, only the http status code 204 will be returned.

Bad Request example [400]

    {
       "Errors": [
       {
        "Field": "StartDateForReportingPeriod",
        "FieldValue": 2023-13-01,
        "Message": "StartDateForReportingPeriod should be in yyyy-MM-dd format."
        }
        ]
    }

Internal Server Error example [500]  
{
       "Errors": [
       {
        "Field": "",
        "FieldValue": "",
        "Message": "JobId already exists"
        "TraceId": "a0635e0e-8f5b-4cf4-a75c-0000baa5e471"
        }
    ]
    }

API Request

Request Parameter DataType Validations Mandatory Description
1 StartDateForReportingPeriod String Y This parameter will be passed to indicate from which date Due forms must be returned. This means all the Due forms with reportingPeriodFromDate >= startDateForReportingPeriod must be returned
2 ReportingPeriodFromDate String N Date range for which forms are fetched
3 ReportingPeriodToDate String N The period range for which the forms are due to
4 ExternalReportingEntity String Y Lfeid of the client
5 IncludeLocations Boolean N Flag to include locations for form
6 Offset Int N An integer indicating the distance (displacement) between the beginning of the object and a given element or point, presumably within the same object
7 Limit Int N This is the maximum number of values the array can hold i.e. array of forms

DueForGenerationRequest

Response Parameter DataType Validations Mandatory Description
1 ReportingPeriodFromDate string YYYY-MM-DD N
2 ReportingPeriodToDate string YYYY-MM-DD N When user do not pass ToDate, current date will get considered.

API Response

Response Parameter DataType Description
1 LocationId string (50) Location
2 ReportingYear int Request year
3 ReportingCountry string (2) Code of the country
4 ReportingPeriodFromDate datetime Initial date period
5 ReportingPeriodToDate datetime Final date period
6 DueDate datetime Due Date of form
7 FormID string (50) Tax Form ID
8 ReportingPeriodicity string (2) Reporting Period
9 ReportingPeriodNum string (2) Reporting Period Number
10 SubmissionMode string (100) FilingMethod type

FilingMethod Values

  1. For following submission method, submissionMode value will be M (Manual): EFile(default), Web Upload, Paper filing
  2. For following submission method, submissionMode value will be A (Automatic): Server to Server

ReportingPeriodicity

Code Frequency
M Monthly
BM Bi-Monthly
Q Quarterly
HY Half Yearly
Y Yearly

Examples for Reporting Period number -

1. When form is set with monthly periodicity and its Fiscal year variant start from January to Dec. In such case below will be the value for reporting period number:

For Jan 2022, Reporting Period number - 01 For Feb 2022, Reporting Period number - 02 and So on till For Dec 2022, Reporting Period number – 12 For Jan 2023, Reporting Period number – 01 Note - numbers will be for each fiscal year which means it will again start from 01 when fiscal year changes.

2. When form is set with monthly periodicity and its Fiscal year variant starts from April to March. In such case below will be the value for reporting period number:

For April 2022, Reporting Period number - 01 For May 2022, Reporting Period number - 02 and so on till For March 2023, Reporting Period number – 12 For April 2023, Reporting Period number – 01

3. When form is set with Quarterly periodicity, and its Fiscal year variant starts from Jan to Dec. In such case below will be the value for reporting period number:

For Jan 2022 – March 2022, Reporting Period number - 01 For April 2022 – June 2022, Reporting Period number - 02 and so on till For Oct 2022- Dec 2022, Reporting Period number – 04 For Jan 2023 – March 2023, Reporting Period number – 01

4. When form is set with Quarterly periodicity, and its Fiscal year variant starts from April to March. In such case below will be the value for reporting period number:

For April 2022-June 2022, Reporting Period number - 01 For July 2022-Sep 2022, Reporting Period number - 02 and so on till For Jan 2023-March 2023, Reporting Period number – 04 For April 2023- June 2023, Reporting Period number – 01

Note: Limit and Offset parameters in request body are optional parameters.They are not required parameters. The limit has been set to default 100. The offset needs to be 0 by default. You can increase offset value.

Consider the following forms with the following reportingperiodfrom and reportingperiordtodate for below Case 1 to Case 5

Form 1 - 01-01-2021 -1-31-2021

Form 2 - 01-02-2021 - 02-28-2021

Form 3 - 01-03-2021 - 03-31-202

Form 4 - 01-04-2021 - 04-30-2021

Form 5 - 01-05-2021 - 05-31-2021

Form 6 - 01-06-2021 - 06-30-2021

Consider the current date to be 5/1/2021

Case 1. Get forms Due for sending only StartDateForReportingPeriod in the request

1. User requires one input passed as header viz. UserId. This values must be encrypted in base64 format. So, user has to convert the actual into base64 encrypted value.

2. To execute the API request, user requires bearer token as well as an authorization. If user do not hold the bearer token, then user do not have permission to execute the API request.

3. When user execute the valid API request(DueForms?startDateForReportingPeriod=2021-01-01&externalReportingEntity=‘000000069’&limit=100&offset=0), he gets the response in following format:

Only forms 1-4 will qualify.

Form 1 - 01-01-2021 -1-31-2021

Form 2 - 01-02-2021 - 02-28-2021

Form 3 - 01-03-2021 - 03-31-202

Form 4 - 01-04-2021 - 04-30-2021

/// OK [200]
{
  "Data": {
      "Result": [{
              {
              "LocationId": "",
              "ReportingYear": "2021",
              "ReportingCountry": "US",
              "ReportingPeriodFromDate": "01-01-2021",
              "ReportingPeriodToDate": "1-31-2021",
              "DueDate": "2021-01-31",
              "ReportingPeriodicity": "M",
              "ReportingPeriodNum": "12",
              "FormId":"TX_01-115-116-Combo",
              "SubmissionMode":"M"
              },
			  {
              "LocationId": "",
              "ReportingYear": "2021",
              "ReportingCountry": "US",
              "ReportingPeriodFromDate": "01-02-2021",
              "ReportingPeriodToDate": "02-28-2021",
              "DueDate": "2021-01-31",
              "ReportingPeriodicity": "M",
              "ReportingPeriodNum": "12",
              "FormId":"TX_01-115-116-Combo",
              "SubmissionMode":"M"
              },
			  {
              "LocationId": "",
              "ReportingYear": "2021",
              "ReportingCountry": "US",
              "ReportingPeriodFromDate": "01-03-2021",
              "ReportingPeriodToDate": "03-31-2021",
              "DueDate": "2021-01-31",
              "ReportingPeriodicity": "M",
              "ReportingPeriodNum": "12",
              "FormId":"TX_01-115-116-Combo",
              "SubmissionMode":"M"
              },
			  {
              "LocationId": "",
              "ReportingYear": "2021",
              "ReportingCountry": "US",
              "ReportingPeriodFromDate": "01-04-2021",
              "ReportingPeriodToDate": "04-30-2021",
              "DueDate": "2021-01-31",
              "ReportingPeriodicity": "M",
              "ReportingPeriodNum": "12",
              "FormId":"TX_01-115-116-Combo",
              "SubmissionMode":"M"
              }
              }
      ]
  }
 }

Case 2. Get forms Due for startDateForReportingPeriod=2021-01-01 & reportingperiodfromdate = 2021-01-01

1. User requires one input passed as header viz. UserId. This values must be encrypted in base64 format. So, user has to convert the actual into base64 encrypted value.

2. To execute the API request, user requires bearer token as well as an authorization. If user do not hold the bearer token, then user do not have permission to execute the API request.

3. When user execute the valid API request(/DueForms?startDateForReportingPeriod=2021-01-01 & reportingperiodfromdate = 1-1-2021 &externalReportingEntity=‘000000069’&limit=100&offset=0), he gets the response in following format:

Only forms 1 will qualify. In this we send back all forms which have a reportingperiodfromdate = 2021-01-01 and reportingperiodenddate within 2021-01-01 to current date of 5/1/2021

Form 1 - 2021-01-01 - 2021-01-31

/// OK [200]
{
  "Data": {
      "Result": [{
              "LocationId": "",
              "ReportingYear": "2021",
              "ReportingCountry": "US",
              "ReportingPeriodFromDate": "2021-01-01",
              "ReportingPeriodToDate": "2021-01-31",
              "DueDate": "2021-01-31",
              "ReportingPeriodicity": "M",
              "ReportingPeriodNum": "12",
              "FormId":"TX_01-115-116-Combo",
              "SubmissionMode":"M"
              }
      ]
  }
 }

Case 3. Get forms Due for startDateForReportingPeriod=2021-01-01 & reportingperiodtodate = 2021-04-30

1. User requires one input passed as header viz. UserId. This values must be encrypted in base64 format. So, user has to convert the actual into base64 encrypted value.

2. To execute the API request, user requires bearer token as well as an authorization. If user do not hold the bearer token, then user do not have permission to execute the API request.

3. When user execute the valid API request(/DueForms?startDateForReportingPeriod=2021-01-01 & reportingperiodtodate = 2021-04-30 &externalReportingEntity=‘000000069’&limit=100&offset=0), he gets the response in following format:

Only forms 4 will qualify. In this, we send back all forms which have a reportingperiodtodate sent in the request current date is not considered.

Form 4 - 2021-04-01 - 2021-04-30-

/// OK [200]
{
  "Data": {
      "Result": [{
              "LocationId": "",
              "ReportingYear": "2021",
              "ReportingCountry": "US",
              "ReportingPeriodFromDate": "2021-04-01",
              "ReportingPeriodToDate": "2021-04-30",
              "DueDate": "2021-01-31",
              "ReportingPeriodicity": "M",
              "ReportingPeriodNum": "12",
              "FormId":"TX_01-115-116-Combo",
              "SubmissionMode":"M"
              }
      ]
  }
 }

Case 4. Get forms Due for startDateForReportingPeriod=2021-01-01 & reportingperiodfromdate = 2021-01-01& reportingperiodtodate = 2021-04-30

1. User requires one input passed as header viz. UserId. This values must be encrypted in base64 format. So, user has to convert the actual into base64 encrypted value.

2. To execute the API request, user requires bearer token as well as an authorization. If user do not hold the bearer token, then user do not have permission to execute the API request.

3. When user execute the valid API request(/DueForms?startDateForReportingPeriod=2021-01-01 & reportingperiodfromdate = 2021-01-01& reportingperiodtodate = 2021-04-30 &externalReportingEntity=‘000000069’&limit=100&offset=0), he gets the response in following format:

4. In this, reportingperiodfromdate = 2021-01-01, & reportingperiodtodate = 2021-4-30 and within the range from 2021-01-01 to current date.

5. None of the forms will qualify since none of the forms have reportingperiodfromdate and reportingperiodtodate that exactly match the request filters.

///No content [204]
{
  
 }

Case 5. Get forms Due for startDateForReportingPeriod=2021-01-01 & reportingperiodfromdate = 2021-04-01& reportingperiodtodate = 2021-04-30

1. User requires one input passed as header viz. UserId. This values must be encrypted in base64 format. So, user has to convert the actual into base64 encrypted value.

2. To execute the API request, user requires bearer token as well as an authorization. If user do not hold the bearer token, then user do not have permission to execute the API request.

3. When user execute the valid API request(/DueForms?startDateForReportingPeriod=2021-01-01 & reportingperiodfromdate = 2021-04-01 & reportingperiodtodate = 2021-04-30 &externalReportingEntity=‘000000069’&limit=100&offset=0), he gets the response in following format:

Only forms 4 will qualify. Only form 4 will qualify since the reportingperiodfromdate and reportingperiodtodate exactly match the request filters

Form 4 - 2021-04-01 - 2021-04-30

/// OK [200]
{
  "Data": {
      "Result": [{
              "LocationId": "",
              "ReportingYear": "2021",
              "ReportingCountry": "US",
              "ReportingPeriodFromDate": "2021-04-01",
              "ReportingPeriodToDate": "2021-04-30",
              "DueDate": "2021-01-31",
              "ReportingPeriodicity": "M",
              "ReportingPeriodNum": "12",
              "FormId":"TX_01-115-116-Combo",
              "SubmissionMode":"M"
              }
      ]
  }
 }