Introducing the Forerunner Academy, a learning platform for floodplain managers
Explore now

Forerunner API Documentation

REST Endpoints

All Forerunner REST endpoints are served from the following domains:

  • https://app.staging.withforerunner.com for staging
  • https://app.withforerunner.com for production

Unless otherwise specified, we expect all requests that POST / PUT data to be of Content-Type: application/json.

Unless otherwise specified, all fields in a request are required.

Authentication

In order to successfully authenticate against the Forerunner API, integrating parties should send an Authorization: Bearer ${AUTH_TOKEN} header with each request. This AUTH_TOKEN will be provided by Forerunner to the integrating party upon request and will be used to associate any API request with the integrating party’s account in Forerunner. AUTH_TOKENs are long-lived, although Forerunner reserves the right to rotate these keys with prior notice if we believe they have been compromised or are affected by any other security-related concerns.

File Endpoints

Submit File

This endpoint is used to submit a file to the Forerunner platform. Since this endpoint accepts a file, data submitted to it must be posted as multi-part form data (i.e. Content-Type: multipart/form-data).

Route: /api/v1/files

Method: POST

Form Data:

fileUpload - the file. Only a single document should be sent at a time.

fileType - the string “Elevation Certificate” (other file types may be forthcoming)

Response:

{
 file: {
   id: string
 },
 errors: [{
   message: string,
   field:
"fileUpload" | "fileType"
 }]
}

Below is an explanation of each of the response’s field:

  • file
    • id: A UUID that uniquely identifies the file in Forerunner.
    • url: The URL that points to the document in Forerunner. Requires authentication.
  • errors: A list of errors identified in the request, if any.
    • message: A human-readable description of the error encountered
    • field: The field the error pertains to.

Substantial Damage / Substantial Improvement Endpoints

Forerunner supports the creation / updating / deletion of substantial damage / substantial improvement (i.e. SI/SD) data.

Submit SI/SD

This endpoint is used to submit an SI/SD entry to Forerunner.

Route: /api/v1/sisd

Method: POST

Request:

{
 type: "improvement" | "damage",
 value: number,
 date: "MM/DD/YYYY",
 description: string,
 propertyMarketValue: number,
 address: string,
 parcelId: string,
 coordinates: [number, number]
};

Below is an explanation of each of the request’s fields:

  • type: Whether the SI/SD is an improvement to the property or damage sustained by the property. Acceptable values are the strings improvement and damage.
  • value: The total value of the improvement or damage, provided as dollars. For instance, if a porch renovation cost $3,451.23, provide 3451.23. This value should be non-negative.
  • date: The date at which the improvement or damage occurred. This should be formatted as “MM/DD/YYYY” (so, a string with 2 digits for the month, 2 digits for the day, 4 digits for the year). For instance, if a porch renovation was done on August 18, 2023, this should be 08/18/2023.
  • description: Optional. A human-readable description of the improvement or damage.
  • propertyMarketValue: Optional. The total property market value of the property impacted by the improvement or damage. Similar to value, this should be provided in dollars.
  • address: Optional if parcelId or coordinates is provided. This is the fully qualified address of the property impacted by the improvement or damage formatted as ${streetNumber} ${streetName} ${streetPostfix}, ${city}, ${state} ${zip}. For instance, you’d provide “2 15th St NW, Washington, DC 20024” for the Washington Monument.
  • parcelId: Optional if address or coordinates is provided. This is the parcel id associated with the property impacted by the improvement or damage. This is often times also referred to as the “parcel number” in GIS systems.
  • coordinates: Optional if parcelId or address is provided. This should be a two-element array containing the property’s numeric latitude and longitude in EPSG:4326, in that order. So, if a property is located at “38.8895° N, 77.0353 W”, provide [38.8895,-77.0353].

Special note: One of address, parcelId, or coordinates is required in order for Forerunner to properly geolocate the SI/SD.

Response:

{
  sisd: {
   id: string,
  },
  property: {
    warnings: [{
      message: string,
   }]
  },
  errors: [{
   message: string,
   field: string
  }]
};

Below is an explanation of each of the response’s fields:

  • sisd: The created SI/SD object. Absent if errors is non-empty.
    • id: A UUID that uniquely identifies the SI/SD in Forerunner’s systems
  • property: The property the SI/SD was associated with in Forerunner.
    • warnings: An array of warnings related to the state of the property’s SI/SD threshold.
      • message: A string describing the warning. For instance, if a property’s total SI/SD value exceeds a critical percentage of the property’s market value during the SI/SD cumulative tracking period, this would read: “The improvement costs recorded for this property meet or exceed your community’s Substantial Improvement threshold. Further action might be necessary to ensure compliance.”
  • errors: An array of errors encountered when processing the request. If errors is non-empty, the sisd object will be absent.
    • message: A human-readable explanation of what the error was. For instance, this could be “unable to geocode address” if an invalid address is given.
    • field: The field that caused the error. For instance, this could be address in the case of an invalid address or value in the case of a negative value.

Special note: Forerunner will do its level best to adequately both geocode the property and also identify that property’s market value if not enough information is provided in the incoming request. If Forerunner cannot do either of these things with confidence, the request will be rejected with all applicable errors. For instance, if the address provide is poorly formatted and no coordinates are provided, the errors array would look like [{ field: "address", message: "Could not standardize address" }]. Similar errors may occur if the coordinates are not within the community’s geographic boundaries within Forerunner or if the parcelId provided does not exist within Forerunner.

Delete SI/SD

This endpoint is used to delete an existing SI/SD entry from Forerunner.

Route: /api/v1/sisd/:id, where :id is the id of the SI/SD to delete.

Method: DELETE

Request: No request body.

Response:

{
  property: {
   warnings: [{
     message: string,
    }]
  }
};

Please see the property field on the “Submit SI/SD” response for more information.

Special note: if the SI/SD did not exist, a bodiless HTTP response with a 404 status code will be returned.

Update SI/SD

This endpoint is used to update an existing SI/SD entry within Forerunner.

Route: /api/v1/sisd/:id , where :id is the id of the SI/SD to update.

Method: PATCH

Request:

{
 type: "improvement" | "damage",
 value: number,
 date: "MM/DD/YYYY",
 description: string | null,
 propertyMarketValue: number,
};

All fields are optional, but at least one field should be present.

Special note: You cannot change the geospatial information of an already-created SI/SD. If an SI/SD was geocoded to the wrong property or if the coordinates on the SI/SD changed for whatever reason, please delete and re-submit the SI/SD instead.

Response: Same as the submit response.

Webhooks

Although not required, integrating with Forerunner’s webhooks allows the integrating party to receive different lifecycle events from Forerunner as things change within Forerunner’s systems.

Headers / Authentication

Every webhook request from Forerunner will include at least the following headers:

Content-Type: application/json
Authorization: Bearer ${AUTH_TOKEN}
User-Agent: axios/0.21.2

All fields are optional, but at least one field should be present.

Special note: You cannot change the geospatial information of an already-created SI/SD. If an SI/SD was geocoded to the wrong property or if the coordinates on the SI/SD changed for whatever reason, please delete and re-submit the SI/SD instead.

Response: Same as the submit response.

Retry Policy

Forerunner will retry any failed webhook request 3 times using an exponential backoff algorithm to avoid overwhelming the target server.

A response is considered a failure if the target server returns a non-2XX response.

Webhook Payloads

Finished Processing

This webhook is sent out whenever a submitted file has fully finished processing and has been vetted for issues. The webhook payload is as follows:

{
 file: {
   id: string,
   status: "canceled" | "completed",
   url: string,
   validationIssues: [
     {
       type: "error" | "warning",
       errorCode: string,
       fieldText: string,
       issue: string,
     },
   ],
 },
};

Below is an explanation of each of the webhook’s fields:

  • id: A UUID that uniquely identifies the file in Forerunner.
  • status: One of either canceled or completed. A document’s processing can be canceled due to a variety of different reasons, such as the contents of the file not matching up with the file type.
  • validationIssues: Any issues with how the document was filled out. These issues do not relate to transcribing or processing the document - rather, they relate to the actual semantic content of the document, such as whether or not a surveyor filled out a require field on an elevation certificate or if a surveyor input a value with the wrong format. For this reason, a canceled document will not have any validationIssues.
    • errorCode: A machine-readable code that uniquely identifies the issue.
    • type: The type of the issue. A type of error indicates that the document was filled out incorrectly in one or more places and requires immediate attention, while a warning type indicates that something looks amiss but not critically so.
    • fieldText: The field / input in the document the issue pertains to. For instance, if the error is about an elevation certificate’s building diagram number, this would read “A7. Building Diagram Number”.
    • issue: A string describing the actual issue. For instance, this would read “Can't be blank” for fields that should not have been left empty when the file was filled out. Combined with fieldText, integrating parties can use issue to compose a human-readable message to show to their users.

Support

Please do not hesitate to reach out to engineering@withforerunner.com with any questions or concerns about the above API.

Ready to increase your community’s resilience?

Request demo
Sign up for our newsletter!

You can unsubscribe at any time. View our Privacy Policy.

Oops! Something went wrong while submitting the form.