Overview
Groundspeed turns unstructured data from common insurance documents into structured data that can be quickly and easily analyzed to power data driven decision making for insurance carriers.
At a high level, clients work with Groundspeed to configure how they will send documents to Groundspeed for processing, and receiving back the structured data from said documents once they've been processed.
Key Concepts
The following concepts within our platform are important to understand.
- File - An individual file that may contain multiple documents (ex - email files that contain attachments, zip files, etc).
- Document - An individual document is the lowest level concept of a file.
- Account - A collection of files/documents that are intended to be processed together. Typically this is documents that pertain to the same insured party (hence it’s called an “Account”).
- Project - The customer configuration of ingest and delivery methods.
- Strategy - The way in which the data is presented in the extract. This is configured at the project level.
- Extract - The artifact that is generated from the data captured within an account.
- Manifest File - A manifest file which contains supplementary information regarding the source files may be included in the zip file.
Account
Accounts within Groundspeed are intended to represent a collection of files that represent the detail of a single insured party.
Extract
An extract is a zip file that typically contains two or more files.One is the extracted structured data, and the other is the error report which contains any errors encountered processing the data, or documents that were considered out of scope within the account.
Manifest File
A manifest file is an optional file that is included with a submission that is used to describe the documents contained within the submission, and override or supplement the data extracted from the submission with data from the manifest.
Naming Convention
A manifest file which contains supplementary information regarding the source files may be included in the zip file. The manifest file must be a csv file in the root directory of the zip file and be named as follows:
- The file needs to start with the word manifest followed by two underscores “__”
- Each manifest file can have multiple “file_name” values.
- But each “file_name” can only have one row of input for each column.
- Column headers must be provided for all manifest information included in the manifest file that the client would like to include in the extract.
Manifest File Format
Each row of the manifest file will be matched to a source file in the zip. The manifest file should have the following information:
| Field | Description | Required |
|---|---|---|
| file_name | The name of the source file | Yes |
| doc_id | Client specified doc id for each source file | Optional |
| customer_account_id | Client specified account id for each source file | Optional |
| customer_account_name | The name of the account assigned by the customer | Optional |
| project_id | Source file listed under project name | Optional |
| submission_effective_date | Date used to allocate claims to the correct policy year. If loss date is before submission_effective_date then the claim is assigned to the previous policy year, if after, then policy year is set to loss date year. Must be in the format “MM/DD” | Optional |
| fill_effective_date | When an effective date is not present, use this date to fill in the effective date. Must be in the format “MM/DD/YYYY”. | Optional |
| fill_valuation_date | When a valuation date is not present, use this date to fill in the valuation date. Must be in the format “MM/DD/YYYY” | Optional |
| fill_line_of_business | When an LOB is not present, use this value to fill in the LOB. | Optional |
| fill_insurance_carrier | When a carrier is not present, use this value to fill in the carrier. | Optional |
| fill_policy_number | When a policy is not present, use this value to fill in the policy number. | Optional |
Sending and Receiving Files from Groundspeed
Groundspeed supports receiving accounts via three different methods: Email, SFTP, and API.
Document Ingestion
Groundspeed systems can ingest documents in one of three ways. Each of which is described in detail below.
Documents can be sent in a zip file container. The list of support file types that can be contained within a zip file are listed below:
- .jpg, .bmp, .gif, .pdf, .tif, .tiff, .doc, .docx, .xlsx, .xls, .csv, .xlsb, .xlsm, .xps, .oxps, .eml, .msg, .zip.
Files fail to ingest to Groundspeed system? Please see FAQ section
API
This is the entrypoint for all document processing requests into the Groundspeed pipeline.
Postman Collection
Request Parameters
Example Request
curl -X POST \ https://intake.groundspeed.com/api/v1/process \ -H 'cache-control: no-cache' \ -H 'content-type: multipart/form-data; boundary=----FormBoundary' \ -H 'x-api-key: $API_KEY' \ -F accountId=$ACCOUNT_ID \ -F projectId=$PROJECT_ID \ -F file=@/path/to/testfile.zip \ -F callbackUrl=https://dummy-url.com
Clients that wish to send documents to Groundspeed can do so via our rapid fusion email pipeline. Users are issued a dedicated email address (XXX@groundspeedrapidfusion.com) which they can send accounts to as email attachments. In some cases, documents may already be in email form, and the underwriter can just forward the email to Groundspeed.
Setup
In order for a customer to send documents via email to Groundspeed, we will need the following information as to configure our intake and delivery system:
- The domain you wish to send from, so that we can have it whitelisted.
- For example, if your email is abc@lala.com, your domain would be lala.com
- We will then provide the email address to use to send us your documents.
- Only include the email address provided by Groundspeed in the “To” selection while sending emails to Groundspeed.
- Please note that if an email is sent to the improper address, it will be rejected and will not be ingested by our system.
Security
- Groundspeed’s email intake solution only allows emails that are sent over a Transport Layer Security (TLS) encrypted connection.
- All the emails delivered by Groundspeed’s email delivery solution will be sent over a connection with Transport Layer Security (TLS) encryption.
Sending an email
- Email Body
- All text in the body is converted to a pdf and treated as a file that will go through our ingestion process. Feel free to put anything that is appropriate for an email (note that images will not be lost in conversion and ingestion).
- Attachments Any attached files will be ingested alongside the email that is sent.
- Attachments have a 30mb limit.
- The list of supported file types are: .jpg, .bmp, .gif, .pdf, .tif, .tiff, .doc, .docx, .xlsx, .xls, .csv, .xlsb, .xlsm, .xps, .oxps, .eml, .msg, .zip.
- Attachments that are not supported will not be ingested.
- Directions for Sending an Account
- Zip all the files for a given account.
- Attach that zip file to the email.
- Send one account per email.
Example Ingest Email
- The address being sent to
- Key-value pairs in email subject
- Email body that will be converted into an ingestible file
- Attachments to be added and extracted
Data Delivery
API - JSON
Groundspeed returns data back to the user's registered callback URL. Users must share the callback URL and the appropriate authorization details to ensure that the data can be returned successfully. Users also have the ability to overwrite the registered default callback URL as part of the request.
Postman Collection
Response Payload
Example Response
API - ZIP
A delivery callback mechanism for uploading a result is also available. This requires deploying a HTTP service capable of receiving a POST method with a multipart/form payload including the payload of a zip file.
Postman Collection
Response Payload
Example Response
curl -X POST -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate' \ -H 'Connection: keep-alive' -H 'Content-Length: 385' \ -H 'Content-Type: multipart/form-data; boundary=9610effdb6e2da9d69bc6b5649353ed2' \ -H 'User-Agent: python-requests/2.21.0' -H 'x-api-key: test' \ -d '--9610effdb6e2da9d69bc6b5649353ed2 Content-Disposition: form-data; name="accountId" 1 --9610effdb6e2da9d69bc6b5649353ed2 Content-Disposition: form-data; name="projectId" 1 --9610effdb6e2da9d69bc6b5649353ed2 Content-Disposition: form-data; name="file"; filename="example.zip" Content-Type: application/zip Binary contents goes here --9610effdb6e2da9d69bc6b5649353ed2-- ' http://localhost:47303/upload
SFTP Method
Data Reference
Groundspeed has four key data products. Each of which is listed below with it's data points described in detail. 
means Groundspeed derived when data not present in source document, 
means field is sourced from a 3rd party provider and is only available in our Premium subscription tier. More details in Child Attributes.
- Setup and Clearance
- Loss Run
- Exposure
- Submission
Insurance data can come in multiple forms, and it's possible that the same data could be captured in multiple places, creating duplicate data. Groundspeed mitigates this risk by making reasonable best efforts to identify duplicate data and omit it from the extracted data that's delivered.
Handling duplicate data is tricky because introducing deduplication measures introduces the possibility that data is omitted when it may in fact just be similar.
As a general rule, Groundspeed systems look for explicitly duplicate data, and prefer to share data that isn't clearly duplicate. We take this approach to ensure that data is not ignored, and provide downstream consumers the opportunity to remove or ignore data at their own discretion.
- Claim Detail Duplication Detection: The Groundspeed claim detail duplication detection logic works to identify individual claim records that are duplicates.
- Groundspeed defines certain loss run fields to be checked, if all defined fields match in the records, a duplicate is detected.
- Such defined fields include loss run policy details, claim details, and financials.
- Claim Summary Duplication Detection: The Groundspeed claim summary duplication detection logic works to identify claim summary records that are duplicates.
- Groundspeed defines certain loss run summary fields to be checked, if all policy fields (such as policy number, claim count etc.) match, and at least one of the financial fields match in the records, a duplicate is detected.
- Such defined fields include loss run summary details and financials.
- Occurrence Identification: The Groundspeed claim occurrence identification logic aims to identify a singular occurrence from which claims originated. Examples include an auto accident, a hail storm, or an explosion at a factory which resulted in multiple claims.
To learn more about de-duplication process, please see FAQ section