GET DueForms

Description

This API retrieves the open obligations from the partner/external system.

This API provides access to retrieve current open obligations from the partner or external system. Open obligations represent pending or ongoing tasks, commitments, or responsibilities within the system.

ALT

Endpoint

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

• Method: GET

Request Parameters

Parameter	Type	Required	Description
externalReportingEntity	String(max length 255)	Yes	Partner/External system ID
startDateForReportingPeriod	Date (yyyy-mm-dd)	No	Obligations from reporting period start date
limit	Integer	No	Number of results to return (default: all)
offset	Integer	No	Offset for pagination (default: 0)

Response Structure

{
  "data": [
    {
      "reportingYear": "String",
      "reportingCountry": "String",
      "reportingPeriodFromDate": "String",
      "reportingPeriodToDate": "String",
      "dueDate": "String",
      "formId": "String",
      "reportingPeriodicity": "String",
      "reportingPeriodNum": "String",
      "submissionMode": "String"
    }
  ]
}

API Contract

Permitted Values

submissionMode
- M: Manual
- A: Automatic/Electronic
reportingPeriodicity
- Code: Frequency
  - B: Bi-weekly
  - W: Weekly
  - M: Monthly
  - BM: Bi-Monthly
  - Q: Quarterly
  - HY: Half Yearly
  - Y: Yearly

Constraints

dueDate, reportingPeriodFromDate, and reportingPeriodToDate are dates in the format yyyy-mm-dd.
reportingYear: max length 4 characters.
reportingCountry: max length 3 characters, must contain ISO-3166-1 standard country code.
formId: max length 255 characters.
reportingPeriodNum: max length 2 characters.
The API must return obligations in chunks.
The API must return all the due forms with the Reporting period beginning with a date less than or equal to the Current date.
The API must return the Reporting Period Number based on the Fiscal Year Variant configured for the report.
If a form is configured as location-based reporting, the API must return only 1 entry for each form per period, irrespective of the number of locations configured for the form.

Special Parameters Handling

startDateForReportingPeriod: This parameter indicates from which date obligations must be returned. Obligations with reportingPeriodFromDate greater or equal to startDateForReportingPeriod must be returned. Format: yyyy-mm-dd.
limit and offset: Parameters used for pagination.

Example URL The following URL fetches due forms for an external reporting entity: /DueForms?startDateForReportingPeriod=2021-01-01&externalReportingEntity=000000069&limit=100&offset=0

Examples for Reporting Period Number

Monthly Periodicity:
- For Jan 2022, Reporting Period Number: 01
- For Feb 2022, Reporting Period Number: 02
- ...
- For Dec 2022, Reporting Period Number: 12
- For Jan 2023, Reporting Period Number: 01 (restarts for each fiscal year)
Quarterly Periodicity:
- For Jan 2022 – March 2022, Reporting Period Number: 01
- For April 2022 – June 2022, Reporting Period Number: 02
- ...
- For Oct 2022 - Dec 2022, Reporting Period Number: 04
- For Jan 2023 – March 2023, Reporting Period Number: 01 (restarts for each fiscal year)

Sample Response

{
    "data": [
        {
            "reportingYear": 2020,
            "reportingCountry": "US",
            "reportingPeriodFromDate": "2020-01-01",
            "reportingPeriodToDate": "2020-01-31",
            "dueDate": "2020-02-20",
            "formId": "EX_FormA1",
            "locationId": "",
            "reportingPeriodicity": "M",
            "reportingPeriodNum": "01",
            "submissionMode": "M"
        },
        {
            "reportingYear": 2020,
            "reportingCountry": "US",
            "reportingPeriodFromDate": "2020-02-01",
            "reportingPeriodToDate": "2020-02-29",
            "dueDate": "2020-03-20",
            "formId": "EX_FormB2",
            "locationId": "",
            "reportingPeriodicity": "M",
            "reportingPeriodNum": "02",
            "submissionMode": "M"
        },
        {
            "reportingYear": 2020,
            "reportingCountry": "US",
            "reportingPeriodFromDate": "2020-03-01",
            "reportingPeriodToDate": "2020-03-31",
            "dueDate": "2020-04-20",
            "formId": "EX_FormC3",
            "locationId": "",
            "reportingPeriodicity": "M",
            "reportingPeriodNum": "03",
            "submissionMode": "M"
        }
    ]
}

Sample request [CURL]

curl --location 'https://exampleapi.example.net/v1.0/api/Forms/DueForms?startDateForReportingPeriod=2023-01-01&ExternalReportingEntity=EX123456&ReportingPeriodFromDate=2023-01-01&ReportingPeriodToDate=2023-01-31' \
--header 'Authorization: Bearer exampleToken1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz' \
--header 'Cookie: incap_ses_1607_1234567=exampleCookieValue1; incap_ses_8216_1234567=exampleCookieValue2; nlbi_1234567=exampleCookieValue3; visid_incap_1234567=exampleCookieValue4'