Data Extractions: Step-by-step

Step 1: Upload your application form

Send a request to  [.h-endpoint-link]POST /files[.h-endpoint-link] with the following body:

• file:  [.h-code][content of uploaded file][.h-code]

Note that the endpoint also takes an additional “type” field in the request body, which you can leave null for this workflow

Retrieve the corresponding file id from the API response.

Example response:

POST /files

Copied

{
  "file": {
    "id": "d7c4579a-5450-4e79-bcfc-e918b3c8a564",
    "format": "pdf",
    "file_name": "herald_quote_summary_d7c4579a-5450-4e79-bcfc-e918b3c8a564",
    "text": "Application Prefill",
    "created_at": "2022-08-11",
    "size": 2470,
    "status": "available",
    "associations": null
  }
}
 

‍

Step 2: Create a data extraction

Create a data extraction from the uploaded file via [.h-endpoint-link]POST /data_extractions[.h-endpoint-link] endpoint.

Example request:

POST /data_extractions

Copied

{"file_id": "d7c4579a-5450-4e79-bcfc-e918b3c8a564",}
 

You should expect a response that looks like the following, where status is pending and parameter values are null.  This response indicates that your file is being processed.

Example response:

POST /bind_applications

Copied

{
  "data_extraction": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "pending",
    "risk_values": [
      {
        "risk_parameter_id": "rsk_14b8_fein",
        "value": "XX-XXXXXXX"
      }
    ],
    "coverage_values": [
      {
        "coverage_parameter_id": "cvg_wsz8_gl_general_aggregate_limit",
        "value": 2000000
      }
    ],
    "created_at": "2023-10-11T21:51:52.737Z",
    "updated_at": "2023-10-11T21:51:52.737Z"
  }
}
 

‍

Step 3: Get your extraction results

Once the data extraction has been processed (expect <5s wait time), you can send a request to [.h-endpoint-link]GET /data_extractions/{data_extraction_id}[.h-endpoint-link] with the extraction_id to retrieve results. This can be accomplished either via polling intermittently for asynchronous updates or listening on webhooks.

The response body should include the set of risk and coverage values that have been extracted based on all applicable information in the PDF.

Example response:

POST /bind_applications

Copied

{
    "quote_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
 

‍

[Optional] Step 4: Create an application with the extracted data

Once you’ve completed the extraction, you have the option to make a POST request to [.h-endpoint-link]/data_extractions/{data_extraction_id}/applications[.h-endpoint-link] with the extraction_id and relevant products to create a new application which will contain automatically contain any parameters from the data extraction that are relevant for that application.

The response from this endpoint will be the same as one from the general [.h-endpoint-link]POST /application[.h-endpoint-link] endpoint, containing an application object and a quote exit object.

‍

[Optional] Step 5: View all extractions associated with a file

In the event you created multiple extractions on the same file object (for example, when you were unsatisfied with the results from an earlier extraction), you have the option to review all historical extractions associated with a file by querying the [.h-endpoint-link]GET /data_extractions[.h-endpoint-link] endpoint with a file id.

If you expect a large number of extractions associated with the file, you can also include a limit and a pageparameter in the request to specify requirements for pagination.

‍

[Optional] Simulate pre-fill workflow in HeRB

You can also test the above workflow in HeRB by clicking the “Extract data from a file” link.

‍