DueFormInstances

Summary:

Forms/DueFormInstances API used to generate forms for set frequency of the time period.

Description: This API will generate the forms those have been passed in the request.

API Name: /Forms/DueFormInstances

HTTP Method: Post

HTTP Status Codes:

	HTTP Status Codes	Description
1	202	Accepted
2	400	Invalid Request
3	401	Returns http status 401 for an invalid credentials
3	500	Internal server error

API Request

	Request Parameter	DataType	Validations	Mandatory	Description
1	Forms	List of DueForm model	Empty list is not allowed	Y
2	x-request-id	string		Y	This is parameter from request header is nothing but jobid
3	ExternalReportingEntity	string		Y	Lfeid of the client

DueForm model

	Request Parameter	DataType	Mandatory	Description
1	ReportingPeriodFromDate	string	Y	Initial date period
2	ReportingPeriodToDate	string	N	Final date period
3	ReportingPeriodicity	string	N	Reporting Period
4	ReportingPeriodNum	string	N	Reporting Period Number
5	ReportingPhase	string	N	Form Amendment or not
6	FormId	string (50)	Y	Tax Form ID
7	LocationId	string (50)	N	This field is optional in the request body. If the form is supporting location-based reporting, then only user needs to pass the locationId which is available/created in the SureTax

API Response

Response Field	Example
Accepted	`202 Accepted`

Reporting Phase

Code	Value	WK Value	Note
STAND	Declaration	Standard (blank)	For any scenario except amendments will get an empty string for reportingPhase.
CORR	Correction	Amendment	For forms that need to be amendment SAP will send CORR for ReportingPhase.

Use cases

Case 1: Non-Location based reporting

1. Consider user wants to create form for period 01-01-2023 to 31-01-2023 for Illinois state. User will require following information for DueFormInstances API: FormId, ReportingPeriodFromDate, ExternalReportingEntity. There are few more optional fields LocationId, ReportingPeriodToDate, ReportingPeriodicity,ReportingPeriodNum,ReportingPhase are available which user can use according to their requirements. In this scenario, user do not require to use these fields. Hence the request body will look like this

    ///      {
    ///        "forms": [
    ///          {
    ///            "formId": "[taxformId]",
    ///            "reportingPeriodFromDate": "[YYYY-MM-DD]"
    ///          }
    ///        ],
    ///        "externalReportingEntity": "[lfeID]"
    ///      }

2. User can get information for all these fields from FormsDue API request as mentioned above.

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

4. 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.

5. When user execute the valid API request, he gets the response in following format:

    202 Accepted

Use case 2: Location based reporting

1. Consider user wants to create form for period 01-01-2023 to 31-01-2023 for Illinois state. User will require following information for Generate API: FormId, ReportingPeriodFromDate, ExternalReportingEntity. There are few more optional fields LocationId, ReportingPeriodToDate, ReportingPeriodicity,ReportingPeriodNum,ReportingPhase are available which user can use according to their requirements. In this scenario, user require to pass locationId. There are two types of forms get generated according to location.

2. Separate form per location – In this type, for every location, separate form gets generated e.g., if there are 4 location, 4 separate forms will get generated.

3. Return get generated for all location in single form - In this type, one form will get generated and within that return, information/sales will be bifurcated by their location.

Hence the request body will look like this:

    ///      {
    ///        "forms": [
    ///          {
    ///            "formId": "[taxformId]",
    ///            "reportingPeriodFromDate": "[YYYY-MM-DD]",
    ///            "locationid": "$[LocationId]"
    ///          }
    ///        ],
    ///        "externalReportingEntity": "[lfeID]"
    ///      }

4. User can get information for all these fields from FormsDue API request.

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

6. 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.

7. When user execute the valid API request, he gets the response in following format:

    202 Accepted

Use Case 3: Setting up amendment flag to the form

Why user require amendment flag in the form:

Amended filing is required when a return is already field with Tax Authority & user wants to generate a new return for the already filed return. In this scenario, user is required to keep the ReportingPhase parameter as "CORR" in the API request. User has this feature because once form status gets changed to FILED, user cannot make any changes and to do so, user needs to ReportingPhase parameter as "CORR"

1. Consider user wants to create form for period 01-01-2023 to 31-01-2023 for Illinois state. User will require following information for Generate API: FormId, ReportingPeriodFromDate, ExternalReportingEntity. There are few more optional fields LocationId, ReportingPeriodToDate, ReportingPeriodicity,ReportingPeriodNum,ReportingPhase are available which user can use according to their requirements. According to the current use case, user needs to send ReportingPhase option as "CORR" as input to in the request body.

2. User can get information for all these fields from FormsDue API request.

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

4. 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.

Hence the request body will look like this:

   ///{
   ///    "forms": [
   ///        {
   ///            "formId": "[taxformId]",
   ///            "reportingPeriodFromDate": "[YYYY-MM-DD]"
   ///        }
   ///    ],
   ///    "externalReportingEntity": "[lfeID]"
   ///}

5. When user execute the valid API request, he gets the response in following format:

    202 Accepted

6.As stated above, for amended filing, the existing generated form must be in Filed state. So, user needs to update the generated forms status to FILED. User can do this using UpdateFilingStatus API request. Using this API, user can change the generated form’s status to FILED.

7.Once the form gets in FILED status, user needs to generate same form for same period with setting ReportingPhase as "CORR". So, the request body will look like this:

   ///{
   ///    "forms": [
   ///        {           
   ///            "FormId": "[formId]",
   ///            "locationid": "$[LocationId]",
   ///            "ReportingPhase": "CORR",
   ///            "reportingPeriodFromDate": "[YYYY-MM-DD]"
   ///        }
   ///    ]
   ///}