Skip to main content

Universal Submit

Description​

Universal Submit is part of the Universal Submit API package. This API allows you to submit prospect data for further processing. Data can be in .eml, .doc, .pdf, or .xlsx formats.

Authentication and Credentials​

Obtain a Bearer Token

The Universal Submit API uses the Insurance Intelligence Authenticate API to obtain a bearer token using your client_id, client_secret, and API key. The bearer token obtained from the Authentication API can be used to authenticate requests using the Universal Submit API.

Your Bold Penguin project team will provide you with a unique client_id and client_secret for each environment as well as an API key and Data Package ID (dp_id).

Accessing the Universal Submit API​

Direct Submission for File Sizes Greater Than 10MB​

  • The Universal Submit API requires the file (eml/doc/pdf/xls etc.) to be passed along with the request for processing.
  • The below endpoint will work for file sizes less than 10MB.
  • To accommodate handling of files with sizes 10 MB or more the process of triggering the Universal Submit API is broken down into multiple steps as below.

Obtain File Upload URL

  • The call to the below endpoint will return a URL where the file can be uploaded.
  • The URL is valid for 5 minutes
  • The tx_id returned as part of the response is required to communicate with submit, status check, and inquiry APIs in the context of the submission.

Endpoint​

Staging​

https://api-smartdata.di-beta.boldpenguin.com/universal/v4/universal-submit/file-upload-url

Production​

https://api.ii.boldpenguin.com/universal/v4/universal-submit/file-upload-url

Pass the following variables as part of the request

Request ParametersDescription
Authentication TokenThe token obtained via the Authentication API
API KeyProvided by Bold Penguin
filenameFull name including extension of the file that is being uploaded

Sample File Upload URL Request​

POST /universal/v4/universal-submit/file-upload-url 
Host: api-smartdata.di-beta.boldpenguin.com
x-api-key: xxxxxxxxxxxxxxxxxx
Authorization: Bearer xxxxxxxxxxxxxxxxxx
Content-Type: application/json
Content-Length: 70

{
    "filename":"Your_Test_File.eml"
}

Sample File Upload URL Response​

{
    "tx_id": "ca7496f7-a933-48d5-bccf-b1dd10f2b9e6",
    "upload_url": "https://plb.di-beta.boldpenguin.com/file-transfer/upload-file?data=AAAAuAECAwB4KBTA570fKFbYe1Mk3uskjyVUYNCRanx2YpT7T1sYaigBlA1trG8UX%2BFBHhxdQ3IoDgAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDJgGaPjP3tnH9pTYAAIBEIA7LwAtmiX4MtCIyxhTNHeodgNHM2drgOYnvRLhqGhG8sKRa2Kc6YTePGfW6YSq7KNYVDqNDLkFMbVAKN5nQUFBQUFCaE1qQ2dvQ06jVnpiSTFCeDdVT2tIMk1Pd01lbWhtOVNWclF0TmxpekFsazRoeThEZng1X1ZmeTZjVHhNeUp0ckFLLUpxUGpMeUhUcjVIUU1WR21seHJ6cE9tQnBGZjA1WFpleFdoRDZFVVRqMDhydnhhQWZSMzNDWlJEM1FMdW5jSVRMdkJJeHM5TDNWMlVvbGpGbUFncGNzTWRfUTJUVFRHQXY0ZmtyVjMzNXJRRzY1dW5nSFhQTEhmU29KUWVsWmRvelJtM1NMcTdmU3JteWxmTHZMeDTNWTJkTHdVMEtoeC03V3ZCV08xNG9xaG9zOU9GWWUwc1d2QU1aOHVFTG45T3dXQ0hlZEFGN2hsRXFjbmxlUTJhdG44SWRvY0wwT0JEdm14dTBVQWg5c21yQnZIYXZoczE3MTk4VUI5M3owMVhmRkJFMkNkSXo3MmZvUWpYUmJsb254NFl5LTVDWHpVVFdpQzV3NE10ZW9qdVE9"
}

Upload the File

Use the upload_url obtained in the Upload URL Request to send the file.

Sample File Upload Request​

PUT /file-transfer/upload-file?data=AAAAuAECAwB4KBTA570fKFbYe1Mk3uskjyVUYNCRanx2YpT7T1sYaigBlA1trG8UX%2BFBHhxdQ3IoDgAAAH4wfAYJKoZIhvcNAQcGoG81bQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDJgGaPjP3tnH9pTYAAIBEIA7LwAtmiX4MtCIyxhTNHeodgNHM2drgOYnvRLhqGhG8sKRa2Kc6YTePGfW6YSq7KNYVDqNDLkFMbVAKN5nQUFBQUFCaE1qQ2dvQ0ZjVnpiSTFCeDdVT2tIMk1Pd01lbWhtOVNWclF0TmxpekFsazRoeThEZng1X1ZmeTZjVHhNeUp0ckFLLUpxUGpMeUhUcjVIUU1WR21seHJ6cE9tQnBGZjA1WFpleFdoRDZFVVRqMDhydnhhQWZSMzNDWlJEM1FMdW5jSVRMdkJJeHM5TDNWMlVvbGpGbUFncGNzTWRfUTJUVFRHQXY0ZmtyVjMzNXJRRzY1dW5nSFhQTEhmU29KUWVsWmRvelJtM1NMcTdmU3JteWxmTHZMeDNNWTJkTHdVMEtoeC03V3ZCV08xNG9xaG9zOU9GWWUwc1d2QU1aOHVFTG45T3dXQ0hlZEFGN2hsRXFjbmxlUTJhdG44SWRvY0wwT0JEdm14dTBVQWg5c21yQnZIYXZoczE3MTk4VUI5M3owMVhmRkJFMkNkSXo3MmZvUWpYUmJsb254NFl5LTVDWHpVVFdpQzV3NE10ZW9qdVE9 HTTP/1.1
Host: plb.di-beta.boldpenguin.com
Content-Length: 231
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="Your_Test_File.eml"
Content-Type: <Content-Type header here>

(data)
----WebKitFormBoundary7MA4YWxkTrZu0gW

Sample File Upload Request Response​

{
    "data": "s3://<bucket-name>"
}

Trigger the File Processing Flow

If the document is pre-classified, then some processing time can be saved by passing the document_type as part of the request. If the document is not pre-classified, the flow tries to classify the document first before the processing starts. Below listed are the endpoints for these two variations

Endpoint​

Staging​

https://api-smartdata.di-beta.boldpenguin.com/universal/v4/universal-submit/file/{tx_id}

Production​

https://api.ii.boldpenguin.com/universal/v3/universal-submit/file/{tx_id}

Pass the following variables as part of the request

Request ParametersDescription
Authentication TokenThe token obtained via the Authentication API
API KeyProvided by Bold Penguin
tx_idThe tx_id returned as part of the get file upload URL request
document_type (Optional)Supported file types are:
ACORD (any ACORD form)
SOV (Statement of Values)
CLAIM_BDX (claims bordereau)
PREM_BDX (premium bordereau)
x-callback-url (Optional)This is an optional header parameter. The endpoint where the document processing completion notification needs to be pushed
x-auth-url (Optional)The endpoint to get the authentication token for communicating with the call back API. The prerequisite here is that the credentials to get the token are configured within the system

Sample Universal Submit Request​

POST /universal/v4/universal-submit/file/ca7496f7-a933-48d5-bccf-b1dd10f2b9e6 
Host: api-smartdata.di-beta.boldpenguin.com
x-api-key: xxxxxxxxxxxxxxxxxx
Authorization: Bearer 5ZhAzSrQCuyYct367GqfSnwE

Sample Universal Submit Response​

{
    "tx_id": "ca7496f7-a933-48d5-bccf-b1dd10f2b9e6",
    "tx_start_time": "2022-05-31T19:48:46.356876+00:00",
    "tx_end_time": "2022-05-31T19:48:52.370923+00:00",
    "response_time_secs": 6.014047,
    "tenant_id": "kowalski",
    "status": "Scheduled"
}

Once the submission is completed, extracting the data from the document is a long running process. The different stages of the flow will transition the status of the transaction as shown here:

Submission Flow​

Submission_in_progress -> Scheduled -> Started -> Completed or Failed.

Direct Submission for File Sizes Less Than 10MB​

Documents that are less than 10MB in size can be submitted directly for processing without requiring the provisioning of a URL.

Submit the File for Processing

Endpoint​

Staging​

https://api-smartdata.di-beta.boldpenguin.com/universal/v4/universal-submit/file

Production​

https://api.ii.boldpenguin.com/universal/v3/universal-submit/file

Pass the following variables as part of the request

Request ParametersDescription
Authentication TokenThe token obtained via the Authentication API
API KeyProvided by Bold Penguin
Content-Typemultipart/form-data
Content-Dispositionform-data; name="file"; filename="file"
document_type (Optional)Supported file types are:
ACORD (any ACORD form)
SOV (Statement of Values)
CLAIM_BDX (claims bordereau)
PREM_BDX (premium bordereau)
x-callback-url (Optional)This is an optional header parameter. The endpoint where the document processing completion notification needs to be pushed
x-auth-url (Optional)The endpoint to get the authentication token for communicating with the call back API. The prerequisite here is that the credentials to get the token are configured within the system

Sample Universal Submit Request​

POST /universal/v4/universal-submit/file 
Host: api-smartdata.di-beta.boldpenguin.com
x-api-key: xxxxxxxxxxxxxxxxxxxxx
x-tenantId: kowalski
Authorization: Bearer 6TGW73tr93LFNmwNwqCFSxKW
Content-Length: 258
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="GT SOV Sample 01.xlsx"
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

(data)
----WebKitFormBoundary7MA4YWxkTrZu0gW

Sample Universal Submit Response​

{
    "tx_id": "7f782ee1-805c-41b7-9b8e-ea698d9a42c0",
    "tx_start_time": "2022-05-18T17:43:46.615680+00:00",
    "tx_end_time": "2022-05-18T17:43:46.802139+00:00",
    "response_time_secs": 0.186459,
    "tenant_id": "kowalski",
    "status": "Submission_in_progress"
}

Once the submission is completed, extracting the data from the document is a long running process. The different stages of the flow will transition the status of the transaction as shown here:

Submission Flow​

Submission_in_progress -> Scheduled -> Started -> Completed or Failed.

Accessing the Universal Submit Status Check API​

Once the file has been submitted for processing, the submission flow status can be checked using the Universal Submit Status Check API.

Endpoint​

Staging​

https://api-smartdata.di-beta.boldpenguin.com/universal/v4/universal-submit/status/{tx_id}

Production​

https://api.ii.boldpenguin.com/universal/v3/universal-submit/status/{tx_id}

Pass the following variables as part of the request

Request ParametersDescription
Authentication TokenThe token obtained via the Authentication API
API KeyProvided by Bold Penguin
tx_idThis ID is returned as part of the Universal Submit response

Sample Universal Submit Status Check Request​

GET /universal/v4/universal-submit/status/ca7496f7-a933-48d5-bccf-b1dd10f2b9e6 
Host: api-smartdata.di-beta.boldpenguin.com
x-api-key: xxxxxxxxxxxxxxxxxxxxxxx
Authorization: Bearer 5ZhAzSrQCuyYct367GqfSnwE

Sample Universal Submit Status Check Response​

{
    "tx_id": "ca7496f7-a933-48d5-bccf-b1dd10f2b9e6",
    "tenant_id": "kowalski",
    "user_id": "9009f7fd-8920-4960-b2fb-f8c5b4bcaed4",
    "tx_start_time": "2022-05-31T19:50:11.673863+00:00",
    "tx_end_time": "2022-05-31T19:50:11.676083+00:00",
    "response_time_secs": 0.00222,
    "tx_status": "Started"
}

The status will change from Pending and move through to Started and then it will be Completed, Review_required or Failed. There will also be a c_report_id and l_report_id generated on successful submission of data for enrichment

Accessing the Universal Submit Status Details API​

You can access details of a submission to the Universal Submit API by providing the appropriate tx_id.

Endpoint​

Staging​

https://api-smartdata.di-beta.boldpenguin.com/universal/v4/universal-submit/status/{tx_id}/details

Production​

https://api.ii.boldpenguin.com/universal/v3/universal-submit/status/{tx_id}/details
Request ParametersDescription
Authentication TokenThe token obtained via the Authentication API
API KeyProvided by Bold Penguin
tx_idThis ID is returned as part of the Universal Submit response

Sample Universal Submit Status Details Request​

GET /universal/v4/universal-submit/status/ca7496f7-a933-48d5-bccf-b1dd10f2b9e6/details 
Host: api-smartdata.di-beta.boldpenguin.com
x-api-key: xxxxxxxxxxxxxxxxxxxx
Authorization: Bearer 5ZhAzSrQCuyYct367GqfSnwE

Sample Universal Submit Status Details Response​

{
    "tx_id": "ca7496f7-a933-48d5-bccf-b1dd10f2b9e6",
    "tenant_id": "kowalski",
    "user_id": "9009f7fd-8920-4960-b2fb-f8c5b4bcaed4",
    "tx_start_time": "2022-05-31T20:01:53.435725+00:00",
    "tx_end_time": "2022-05-31T20:01:53.439098+00:00",
    "response_time_secs": 0.003373,
    "tx_status": "Completed",
    "seed_document": "Your_Test_File.eml",
    "total_number_of_documents": 1,
    "documents": [
        {
            "document_name": "Your_Test_File.eml",
            "document_id": "bd78ba10-61f0-4238-be9f-a2fa45f9abd3",
            "errors": [],
            "classified_documents": [
                {
                    "document_id": "d3149882-5c1a-420a-b904-c42348a23459",
                    "document_name": "Your_Test_File.eml",
                    "document_type": "EML",
                    "number_of_pages_or_sheets": 1,
                    "startTime": "2022-05-31T19:55:44.582000",
                    "status": "Succeeded",
                    "review_id": "09db4e29-b39c-423c-b60b-15b0fc0f721d",
                    "endTime": "2022-05-31T19:58:27",
                    "review_url": "https://riskgenius-internal.di-beta.boldpenguin.com/genius-review/09db4e29-b39c-423c-b60b-15b0fc0f721d"
                }
            ]
        }
    ]
}

Universal Submit Status Response Structure​

Sample Universal Submit Status Response​

  • The HTTP response code would be 200 OK for all the successful requests ` Any failures because of authentication, authorization, service unavailable, rate limits exceeded; would return the standard HTTP error response codes
  • Since there could be multiple documents as part of the request, the response will have metadata recorded for every document. This is arranged based on the classification of the documents. Any exceptions while processing the document are recorded at the document level under the classified_documents
  • The tx_status aggregate represents the status of the submitted request. The values could be: SUBMISSION IN PROGRESS, SCHEDULED, STARTED, REVIEW_REQUIRED,COMPLETED, or FAILED . The transaction level status is marked as REVIEW_REQUIRED even if one of the documents is processed successfully
  • The structure of an error message will have an error_code and error_description. The error_description will have details about the exception. The details of different error codes are defined below.
{
    "tx_id": "<txid>",
    "seed_document": "<file_name>",
    "total_number_of_documents": "<number>",
    "tx_start_time":"<datetime>",
    "tx_end_time":"<datetime>",
    "total_processing_time": "<number>",
    "tx_status":"<status>",
    "documents": [
        {
            "document_name": "<doc_name>",
            "document_id": "<doc_id>",
            "errors": [{// error before processing
                "error_code": "<err_code>",
                "error_description": "<err_description>"
            }],
            "classified_documents": [
                {
                    "document_type": "<doc_type>",
                    "number_pages_or_sheets": "<number>",
                    "processing_time": "<number>",
                    "status": "<status>",
            "review_id": "<document_review_id>",
                    "review_url": "<document_review_url>",

                    "errors": [{// if error while document processing
                        "error_code": "<err_code>",
                        "error_description": "<err_description>"
                    }]
                }
            ]
        }
  }

Supported Error Codes​

Error CategoryHTTP Error CodeError CodeError Description
SECURITY_ERROR401Unauthorized
403Access Forbidden
429RATE_LIMIT_REACHED
BAD_REQUEST400ERR_0100INVALID_INPUT
ERR_0101INVALID_INPUT_SIZE_EXCEEDS_RANGE
ERR_0102UNSUPPORTED_MEDIA_TYPE
ERR_0103MISSING_MANDATORY_INPUT
ERR_0104DATA_NOT_FOUND
INTERNAL_SERVER500ERR_0200INTERNAL_SERVER
ERR_0201INTEGRATION_ERROR
ERR_0202CONNECTION_ERROR
ERR_0203TIMEOUT_ERROR
ERR_0204IO_ERROR
ERR_0205DB_ERROR
ERR_0300DOC_PROCESSING_ERROR
ERR_0301DOC_CLASSIFICATION_ERROR
ERR_0302DOC_EXTRACTION_ERROR
ERR_0303DATA_ENRICHMENT_ERROR
ERR_0401AI_CLEANSER_ERROR
ERR_0402AI_MATCHER_ERROR
SERVICE_UNAVAILABLE503