Forms/Generate

Summary:

Forms/Generate API used to generate forms with existing relationship with Tax Authority for set frequency of the time period. User gets the response in the form of unique GUID which we can use in further API requests like JobStatus.

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

API Name: /Forms/Generate

HTTP Method: Post

HTTP Status Codes:

API Request

DueForm model

API Response

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 Generate API: TaxAuthorityId, TaxFormId, ReportingFrom. There are two more optional fields LocationId and AmendmentFlag 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": [
    ///          {
    ///            "taxAuthorityId": [taxAuthId],
    ///            "taxFormId": "[formId]",
    ///            "reportingFrom": "[MM/YYYY]"
    ///          }
    ///        ]
    ///      }

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

3. User requires two more inputs passed as header viz. UserId and LFEId. These values must be encrypted in base64 format. So, user has to convert the actual values 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:

    ///      {
    ///        "response": {
    ///            "id": "[Unique GUID]",
    ///            "message": "Generate form created successfully"
    ///          },
    ///        "status": "In Progress",
    ///        "errors": null
    ///      }

6. To know the status of the job, user can execute JobStatus API, and user can pass JobId and LFEId to get the result. JobId is the id user get in the response body of Generate API request.

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: TaxAuthorityId, TaxFormId, ReportingFrom. There are two more optional fields LocationId and AmendmentFlag are available which user can use according to use case. 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.

    ///      {
    ///        "forms": [
    ///          {
    ///            "taxAuthorityId": [taxAuthId],
    ///            "taxFormId": "[formId]",
    ///            "locationid": "$[LocationId]"
    ///            "reportingFrom": "[MM/YYYY]"
    ///          }
    ///        ]
    ///      }

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

5. User requires two more inputs passed as header viz. UserId and LFEId. These values must be encrypted in base64 format. So, user has to convert the actual values 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:

   ///     {
   ///         "response": {
   ///             "id": "[Unique GUID]",
   ///             "message": "Generate form created successfully"
   ///         },
   ///         "status": "In Progress",
   ///         "errors": null
   ///     }

8. To know the status of the job, user can execute JobStatus API, and user can pass JobId and LFEId to get the result. JobId is the id user get in the response body of Generate API request.

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 amendment flag true 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 pass amendment flag of form as true

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: TaxAuthorityId, TaxFormId, ReportingFrom. There are two more optional fields LocationId and AmendmentFlag are available which user can use. According to the current use case. User needs to use AmendmentFlag option as input to in the request body.

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

3. User requires two more inputs passed as header viz. UserId and LFEId. These values must be encrypted in base64 format. So, user must convert the actual values 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": [
   ///        {
   ///            "taxAuthorityId": "[taxAuthId]",
   ///            "taxFormId": "[formId]",
   ///            "reportingFrom": "[MM/YYYY]"
   ///        }
   ///    ]
   ///}

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

   ///{
   ///    "response": {
   ///        "id": "[Unique GUID]",
   ///        "message": "Generate form created successfully"
   ///    },
   ///    "status": "In Progress",
   ///    "errors": null
   ///}

6.To know the status of the job, user can execute JobStatus API, and user can pass JobId and LFEId to get the result. JobId is the id user get in the response body of Generate API request.

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

8.Once the form gets in FILED status, user needs to generate same form for same period with setting amendment flag true. So, the request body will look like this:

   ///{
   ///    "forms": [
   ///        {
   ///            "taxAuthorityId": "[taxAuthId]",
   ///            "taxFormId": "[formId]",
   ///            "locationid": "$[LocationId]",
   ///            "amendmentFlag": "[true]",
   ///            "reportingFrom": "[MM/YYYY]"
   ///        }
   ///    ]
   ///}