Skip to content

Long Running Tasks#

While working with enriched APIs, certain operations can lead to asynchronous (deferred) responses; for example “bulk creation or e-invoice” or “fetching of taxpayer details in bulk”.

Such APIs will give a reference token (a unique id) to fetch the status and download the deferred detailed / consolidated response.

Data against the reference token is accessible for the period of 7 days from generation of the reference token

Status API#

This API is used to fetch the current status of the long-running-tasks.

Route

/enriched/tasks/{flynn-version}/status/{task-id}

  • active ‘flynn-version’: v1.0
  • method: GET

URL Parameters#

Name Description Type
flynn-version version of the API
for example, v1.0		 string
task-id Reference ID provided in the response of a long-running operation string

Headers#

All required headers to make an authenticated API call.

Tip

The only valid value for the header key accept is application/json.

Also, since no request body is sent, header key Content-type is optional.

Response#

200#

When data.task.status = completed, you then proceed to Downloads API to fetch the results.

Sample Response Body

{
  "data": {
    "task" : {
        "id": "123e4567-e89b-12d3-a456-426655440000",            
        "status": "processing"            
    }
  }
}

Download API#

This API is used to download the processed response of the long-running-tasks. Download API response is unique for each API. Check out for detailed-documentation in the respective APIs.

Route

/enriched/tasks/{flynn-version}/download/{task-id}

  • active ‘flynn-version’: v1.0
  • method: GET

URL Parameters#

Name Description Type
flynn-version version of the API
for example, v1.0		 string
task-id Reference ID provided in the response of a long-running operation string

Headers#

All required headers to make an authenticated API call.

Tip

The only valid value for the header key accept is application/zip.

Also, since no request body is sent, header key Content-type is optional.

Response#

200#

If and only if data.task.status = completed for Status API then only download or result API call will yield a successful response.

Errors#

Http Status Code: 400

{
  "data" : {
    "id" : "abddf894-2677-46bc-9ff1-e90a15424c67",
    "jobs" : {
      "total" : 1,
      "pending" : 0
    },
    "status" : "completed"
  }
}
Response Status Description
400 Invalid task status
404 Invalid task-id or task-id not found

Result API#

This API is used to fetch the processed response of the long-running-tasks. Result API response is unique for each API. Check out for detailed-documentation in the respective APIs.

Route

/enriched/tasks/{flynn-version}/result/{task-id}

  • active ‘flynn-version’: v1.0
  • method: GET

URL Parameters#

Name Description Type
flynn-version version of the API
for example, v1.0		 string
task-id Reference ID provided in the response of a long-running operation string

Headers#

All required headers to make an authenticated API call.

Tip

The only valid value for the header key accept is application/json.

Also, since no request body is sent, header key Content-type is optional.

Response#

200#

If and only if data.task.status = completed for Status API then only result API call will yield a successful response.

Errors#

Http Status Code: 404

{
  "error" : {
    "message" : "err-resource-not-found",
    "type" : "ResourceNotFound",
    "args" : {
      "task-id" : "abddf894-2667-46bc-9ff1-e90a15424c67"
    }
  }
}
Response Status Description
400 Invalid task status
404 Invalid task-id or task-id not found

Pages API#

This API is used to fetch the page result of the long-running-tasks.

Route

/enriched/tasks/{flynn-version}/result/{task-id}/page/{page-number}

  • active ‘flynn-version’: v1.0
  • method: GET

URL Parameters#

Name Description Type
flynn-version version of the API
for example, v1.0		 string
task-id Reference ID provided in the response of a long-running operation string
page-number page number (0 to max page number) as per the status API int

Headers#

All required headers to make an authenticated API call.

Tip

The only valid value for the header key accept is application/json.

Also, since no request body is sent, header key Content-type is optional.

Response#

200#

If and only if data.task.status = completed for Status API then only result API call will yield a successful response. Make sure you have relevant page number as per the status API - it states max number of pages generated for the task.

Errors#

Http Status Code: 404

{
  "error" : {
    "message" : "err-resource-not-found",
    "type" : "ResourceNotFound",
    "args" : {
      "task-id" : "abddf894-2667-46bc-9ff1-e90a15424c67"
    }
  }
}
Response Status Description
400 Invalid task status
404 Invalid task-id or task-id not found or invalid page-number