GET GenerationRequestStatus

Description

This API endpoint is utilized to continuously check the status of form generation requests until the process reaches its final completion status. It enables clients to monitor the progress of form generation activities until they are successfully completed or terminated.

ALT

Endpoint

• Endpoint: <environment base url>/v1.0/api/Forms/GenerationRequestStatus

• Method: GET

Request Parameters

Parameter Type Required
id String (max length 32) Yes

Response Structure

{
  "data": {
    "requestStatus": "string",
    "formInstances": [
      {
        "id": "String",
        "formId": "string",
        "reportingPeriodFromDate": "string",
        "reportingPeriodToDate": "string",
        "reportingPeriodicity": "string",
        "reportingPeriodNum": "string",
        "reportingPhase": "string",
        "reportingPhaseIndex": "string",
        "locationId": "string",
        "status": "string",
        "generatedOn": "string"
      }
    ],
    "externalReportingEntity": "string"
  }
} `

API Contract

Permitted Values

reportingPhase

Code Value
STAND Declaration
CORR Correction

reportingPeriodicity

Code Frequency
B Bi-weekly
W Weekly
M Monthly
BM Bi-Monthly
Q Quarterly
HY Half Yearly
Y Yearly

status

Code Value
GEN Generated Successfully
GWE Generated with Errors
GOD In Process
GEF Generation Failed

requestStatus

Code Value
1 In Process
2 Completed

Field Specifications

  • id: GUID, mandatory once available, max length 32.
  • formId: Mandatory, max length 255.
  • reportingPeriodFromDate, reportingPeriodToDate: Dates in format yyyy-mm-dd and are mandatory.
  • reportingPhaseIndex: Max length 2.
  • reportingPeriodNum: Max length 2.
  • locationId: Mandatory in case of location-based reporting, max length 1333.
  • externalReportingEntity: Mandatory, max length 255.
  • status: Mandatory.
  • generatedOn: Mandatory in case generation is successful. The regenerated or reset timestamp must be returned in case of regeneration or reset. The timestamp must be in UTC.

Additional Notes

  • The Job-ID passed in GenerationRequestStatus API is the same as what was passed in POST/DueFormInstance API.
  • The response must contain all the requested forms for the generation job. In case a form is still not picked for processing, the id will be blank, but the response must contain other mandatory fields (with status as in process). In the case of location-based forms, the individual entries for all the locations must be returned.

Sample Response

{
    "data": [
        {
            "requestStatus": 1,
            "formInstances": [
                {
                    "id": "123e4567-e89b-12d3-a456-426614174000",
                    "formId": "EX_FormA1",
                    "reportingPeriodFromDate": "2024-01-01",
                    "reportingPeriodToDate": "2024-01-31",
                    "reportingPeriodicity": "M",
                    "reportingPeriodNum": "01",
                    "reportingPhase": "INIT",
                    "locationId": "",
                    "status": "PENDING",
                    "generatedOn": "2024-06-01 10:00:00"
                }
            ],
            "externalReportingEntity": "A000123456"
        }
    ]
}

Sample request [CURL]

curl --location 'https://exampleapi.example.net/v1.0/api/Forms/GenerationRequestStatus?Id=example-id-1234-5678-90ab-cdef12345678' \
--header 'Authorization: Bearer exampleToken1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz' \
--header 'Cookie: incap_ses_1607_1234567=exampleCookieValue1; incap_ses_76_1234567=exampleCookieValue2; incap_ses_8216_1234567=exampleCookieValue3; nlbi_1234567=exampleCookieValue4; visid_incap_1234567=exampleCookieValue5'