Application Sources

Track the source of risk, coverage, and admin values on an application

The Risk, Coverage, and Admin values on an application can be set in a variety of ways:

To enable developers to better track how a given value was set, we provide the source field on application values. Currently, this field is in beta and is not returned by default. If you would like for it to be returned in your Applications responses, please contact us at support@heraldapi.com.

How it works

When risk, coverage, and admin values are set or updated as a result of a call to one of the endpoints above, the source field will be populated according to the table below.

API EndpointSource Value
POST /applicationsapi_update
PUT /applications/:idapi_update
POST /applications/:id/autofillautofill
POST /applications/:id/data_extractiondata_extraction

Example

Below is an example workflow to highlight the behavior of the source field. The examples below only include risk values, but the same pattern applies to risk, coverage, and admin values.

(1) Create application via POST /applications
Copied
POST /applications
{
  "risk_values": [
    {
      "risk_parameter_id": "rsk_m4p9_insured_name",
      "value": "ACME Company"
    }
  ]
}

response:
{
  "application": {
    ...,
    "risk_values": [
      {
        "risk_parameter_id": "rsk_m4p9_insured_name",
        "value": "ACME Company",
        "source": "api_update",
        ...
      },
      ...
    ]
  }
}
(2) Update application via POST /applications/:id/autofill
Copied
POST /applications/:id/autofill
{
  "autofill_profiles": ["{autofill-profile-id}"]
}

response:
{
  "application": {
    ...,
    "risk_values": [
      {
        "risk_parameter_id": "rsk_m4p9_insured_name",
        "value": "ACME Company",
        "source": "api_update",
        ...
      },
      {
        "risk_parameter_id": "rsk_d6el_secure_backup",
        "value": "yes",
        "source": "autofill",
        ...
      },
      ...
   ]
}
(3) Update application via POST /applications/:id/data_extraction
Copied
POST /applications/:id/data_extraction
{
  "data_extraction_id": "{data-extraction-id}"
}

response:
{
  "application": {
    ...,
    "risk_values": [
      {
        "risk_parameter_id": "rsk_m4p9_insured_name",
        "value": "ACME Company",
        "source": "api_update",
        ...
      },
      {
        "risk_parameter_id": "rsk_d6el_secure_backup",
        "value": "yes",
        "source": "autofill",
        ...
      },
      {
        "risk_parameter_id": "rsk_0ie7_number_of_fte",
        "value": 15,
        "source": "data_extraction",
        ...
      },
      ...
   ]
}
(4) Update application via PUT /applications/:id
Copied
PUT /applications/:id
{
  "risk_values": [
    {
      "risk_parameter_id": "rsk_m4p9_insured_name",
      "value": "ACME Company"
    },
    {
      "risk_parameter_id": "rsk_d6el_secure_backup",
      "value": "no"
    },
    {
      "risk_parameter_id": "rsk_0ie7_number_of_fte",
      "value": 15
    }
  ]
}

response:
{
  "application": {
    ...,
    "risk_values": [
      {
        "risk_parameter_id": "rsk_m4p9_insured_name",
        "value": "ACME Company",
        "source": "api_update",
        ...
      },
      {
        "risk_parameter_id": "rsk_d6el_secure_backup",
        "value": "no",
        "source": "api_update",
        ...
      },
      {
        "risk_parameter_id": "rsk_0ie7_number_of_fte",
        "value": 15,
        "source": "data_extraction",
        ...
      },
      ...
   ]
}

FAQ

  • Q: Do null values have a source?
    • A: No - null values do not have a source and will include source: null
  • Q: What happens if a value is updated and then updated back?
    • A: The source will reflect the endpoint that most recently set the value. So, for example, say a value is set to "1" as a result of calling autofill, then set to "2" by a PUT request, then set back to "1" by a subsequent PUT request. In this case, the final source for the value will be "", since it was most recently set by the PUT call.