GET FormInstances

Description

This API endpoint retrieves comprehensive details regarding a specific generated form instance. It provides clients with essential information such as form ID, name, format, size, availability of logs, visualization support, and current status.

ALT

Endpoint

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

• Method: GET

Request Parameters

Parameter Type Required Multiple values
id String (max length 32) Yes Yes, comma-separated

Response Structure

{
  "data": {
    "formInstances": [
      {
        "id": "String",
        "name": "string",
        "format": "string",
        "size": "string",
        "isLogAvailable": "string",
        "isChangeLogAvailable": "string",
        "visualization": "string",
        "status": "string"
      }
    ]
  }
} `

API Contract

Permitted Values

visualization

Code Value
1 Preview Supported
2 Preview and Edit Supported
None

status

Code Value
GEN Generated Successfully
GWE Generated with Errors
GEF Generation Failed
SOK Content Accepted by Government
SDE Content Declined by Government
STG Submitted to Government

Field Specifications

  • id: Max length 32, ID of the generated form instance.
  • name: If the form is generated, max length 100. The name can be one of the below (in the order specified). In the case of location-based reporting, the name is concatenated with the location Id separated by underscore (example "name": "Denver Sales/Use Tax Return_$webSales where $webSales is the location and "Denver Sales/Use Tax Return" is the name below order).
    • File Name - If the file name is different from the form name, otherwise the form name is pupulated. In case of location-based forms, location is appended to the form name.
    • Document name, if available.
    • Document Id
    • Empty
  • format: If the form is generated, max length 4, is the Mime type of the form. The format returned is the legal format mandated by the tax authorities. If no legal format exists, the default format is returned.
  • size: If the form is generated, max length 30, is the size of the generated form in Bytes.
  • isLogAvailable: If the form is generated, max length 1, value is "TRUE" if any generation log is available for the form instance, else returns "FALSE".
  • isChangeLogAvailable: If the form is generated, max length 1, returns "TRUE" if any change log is available for the form instance, else returns "FALSE".
  • visualization: If the form is generated indicates whether preview/edit is supported for the form instance.
  • status: If the form is generated. Generation status for form API returns the details for the form instances even if the corresponding externalReportingEntity is inactive.

Sample Response

{
    "data": {
        "formInstances": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "name": "Example Sales and Use Tax Return",
                "format": "pdf",
                "size": "1024",
                "isLogAvailable": true,
                "isChangeLogAvailable": true,
                "visualization": "1",
                "status": "GEN"
            }
        ]
    }
}

Sample request [CURL]

curl --location 'https://exampleapi.example.net/v1.0/api/Forms/FormInstances?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' \