Quick Submit
Description
The Quick Submit API allows you to quickly retrieve basic company information and location details for any seed company name and address you provide.
Under the hood, the seed input is cleansed and enriched to ensure there are no missing data elements. After cleansing, the request is submitted to multiple data connectors which aggregate the data relevant to the input. The aggregated data is further processed to triangulate all data elements and generate a confidence score.
Authentication
- This endpoint requires an access_token from the authentication endpoint in the same environment.
- Include it as a bearer token in an Authorization header for the request.
- Access tokens are valid for 12 hours.
Authentication URL:
POST https://boldpenguin-auth-uat.beta.boldpenguin.com/auth/token?grant_type=client_credentials
Accessing the Quick Submit API
Step 1: Get the auth token
- You must submit the shared credentials as a basic authentication header.
- Combine your Client ID and Client Secret separated by a colon, (client_id:client_secret), then apply Base64 encoding.
Sample Authentication Request
POST /auth/token?grant_type=client_credentials HTTP/1.1
Host: boldpenguin-auth-uat.beta.boldpenguin.com
Authorization: Basic OXlXUHY5NTlqV1laWEsxSzVncmRKaW9MbnlYSll4U3Y6TkRVNFFwZ1BaUmFTS0F0elFuNkNOVDd5UkIyakd0ZkNINFVRRUNvblJtaGhKM0t6OE5IMkJBTkVCMkw5a2FOZg==
Cookie: XXXXXX
Sample Authentication Response
{
"access_token": "MMav2m8jTZbbEK48o6CUM94K",
"token_type": "bearer",
"expires_in": 43200,
"refresh_token": "vhKk1DALCT4MWFvvCENSgKmr",
"scope": "",
"uid": "a8ceaae5-7d8a-46b7-8d9a-c01c85edc8d3",
"info": {
"name": "SmartData Integrations Service Client",
"email": null,
"first_name": "SmartData Integrations",
"last_name": "Service Client"
},
"extra": {
"raw_info": {
"user_id": "cfacd9bb-88bf-4e1c-9d78-2221dee96da2",
"tenant_id": "1cfa5f74-2c13-490d-ace1-9dc5c7173d14",
"tenant_name": "kowalski",
"tenant_theme": "default",
"primary_user_group_id": "94a8e3fb-a0ae-41ad-838f-56217f28ac4e",
"user_group_ids": [
"94a8e3fb-a0ae-41ad-838f-56217f28ac4e"
],
"name": "SmartData Integrations Service Client",
"email": null,
"first_name": "SmartData Integrations",
"last_name": "Service Client",
"phone": null,
"permissions": [
"::data/v1:get",
"::company/v1/quick_submit:post",
"::company/v1/company_submit:post"
],
"auth_uid": null,
"created_at": "2021-05-13T14:17:31.001Z",
"completed_steps": [],
"accepted_agreements": [],
"plan_sku": null,
"sub_status": null
}
}
}
Tokens expire after 12 hours, after which point you can use the refresh_token to refresh the token or request a new access token using the steps above.
Step 2: Access the Quick Submit API
Quick Submit URL:
POST https://api-smartdata.di-beta.boldpenguin.com/company/v1/quick_submit?dpid=[data package ID]
Pass the below variables as part of the request
| Request Parameters | Comments |
|---|---|
| Authentication Token | The token we get in STEP 1 |
| API Key | (Shared with the Customer) |
| Request Query Parameters | Pass the Shared Data Package Id as part of the dpid query parameter |
| POST Request Body | The body contains a JSON message which will have Company Name and Address attributes |
Sample Quick Submit Request
POST /company/v1/quick_submit?dpid=kowalski-us-c0001 HTTP/1.1
Host: api-smartdata.di-beta.boldpenguin.com
x-api-key: M4jHKvQcVDaY1sDivJgEe6LIuqArhDin8XldfxoK
Authorization: Bearer MMav2m8jTZbbEK48o6CUM94K
Content-Type: application/json
Content-Length: 119
{
"company_name":"Red River Roofing & Construction, Inc.",
"address":"746 Enterprise Drive, Edmond, OK 73013"
}
Sample Quick Submit Response
{
"tx_id": "kowalski-8bd82aba-7d01-42d4-b851-b0bea1b41540",
"tenant_id": "kowalski",
"user_id": "cfacd9bb-88bf-4e1c-9d78-2221dee96da2",
"tx_start_time": "2021-05-13T20:51:52.362Z",
"tx_end_time": "2021-05-13T20:51:54.310Z",
"response_time_secs": 6.778006,
"seed_input": {
"company_name": "Red River Roofing & Construction, Inc.",
"address": "746 Enterprise Drive, Edmond, OK 73013"
},
"data_package_id": "kowalski-us-c0001",
"c_report_id": "CUS1187A2AAE214E4540",
"l_report_id": "LUS1187A2AAE214FBF35",
"cleansed_input": {
"companyName": "RED RIVER ROOFING & CONSTRUCTION, INC.",
"website": "https://www.redriverroofing.com/",
"phoneNumber": "4053300025",
"confidence_score": 0.6,
"address": {
"streetAddr": "746 ENTERPRISE DR",
"city": "EDMOND",
"state": "OK",
"zipOrPostalCode": "73013",
"country": "US",
"geoPosition": {
"latitude": 35.6312866,
"longitude": -97.494186
}
},
"seedInput": {
"companyName": "Red River Roofing & Construction, Inc.",
"address": {
"streetAddr": "746 Enterprise Drive",
"city": "Edmond",
"state": "OK",
"zipOrPostalCode": "73013",
"country": ""
}
}
},
"data": {
"company_id": "CUS1187A2AAE214E4540",
"company_name": "RED RIVER ROOFING & CONSTRUCTION, INC.",
"dba_aka": [],
"contact_name": [],
"phone_number": "1-4053300025",
"website": "https://www.redriverroofing.com/",
"email_id": "",
"address": "746 Enterprise Dr",
"city": "Edmond",
"state": "OK",
"postal_code": "73013",
"fein": "",
"legal_entity_type": "",
"year_founded": "2000",
"year_in_business": 21,
"annual_revenue": "6657967",
"annual_payroll": "1163503.72",
"total_full_time_employees": "34",
"primary_naics_2012": [{
"code": "238160",
"desc": "Roofing Contractors"
}],
"secondary_naics_2012": [{
"code": "238170",
"desc": "Flashing contractors"
},{
"code": "238170",
"desc": "Siding contractors"
},{
"code": "238220",
"desc": "plumbing, heating, and air-conditioning contractors"
},{
"code": "236220",
"desc": "commercial and institutional building construction"
}],
"country": "US",
"company_description": [],
"ppp_loan_size": ""
},
"scores": {
"website": "86.21",
"year_founded": "72.84",
"year_in_business": "72.84",
"annual_revenue": "69.90",
"annual_payroll": "80.64",
"total_full_time_employees": "80.64",
"primary_naics_2012": "75.59"
}
}
Response Parameters
JSON Parameters
meta data
| Data Elements | Type | Description |
|---|---|---|
| tx_id | String | Unique transaction Id for every request |
| tx_start_time | String | Transaction start time |
| tx_end_time | String | Transaction end time |
| response_time_secs | Float | Transaction response time in seconds |
| data_package_id | String | Reference Id to the subscribed data points |
| tenant_id | String | Tenant Id |
| user_id | String | User Id |
| c_report_id | String | Unique Id generated for the company report |
| l_report_id | String | Unique Id generated for the location report |
seed_input
| Data Elements | Type | Description |
|---|---|---|
| company_name | String | Company name as given in the request |
| address | String | Address as given in the request |
cleansed_input
| Data Elements | Type | Description |
|---|---|---|
| companyName | String | Cleansed Company Name |
| website | String | Company website |
| phoneNumber | String | Company Phone Number |
| confidence_score | Float | Confidence Score for the cleansed address. The value ranges between 0-100 |
| address.streetAddr | String | Cleansed Street Address |
| address.city | String | Cleansed City |
| address.state | String | Cleansed State |
| address.zipOrPostalCode | String | Cleansed Postal Code |
| address.country | String | Cleansed Country |
| address.placeId | String | Places Id from Google Maps |
| address.geoPosition.latitude | Float | Latitude coordinate for the address |
| address.geoPosition.longitude | Float | Longitude coordinate for the address |
connector_crawl_status
| Data Elements | Type | Description |
|---|---|---|
| completed | Integer | Total Connectors that are crawled successfully |
| failed | Integer | Total Connectors that failed to crawled |
| in_progress | Integer | Total Connectors that are still in the process of crawling |
| not_triggered | Integer | Total Connectors that are not triggered |
Data
All the subscribed data points are listed in the "data" : {} object.
For a detailed description of the data points, please refer to the Data Dictionary.
Scores
A score is generated against all the triangulated data points which is shown as part of the "scores":{} object.
Response Codes against Data Point
| Response Code | Type | Description |
|---|---|---|
| NO_DATA | String | Data not found for the data point |
Examples
Example Request
{
"company_name": "Bold Penguin",
"address": "100 E Broad St, Columbus, OH 43215"
}
Example Responses
Sample Successful Response
{
"tx_id": "test-5417ccc8-8f7f-4010-b2e1-9634a671d096",
"tx_start_time": "2021-02-19T16:41:50.466869+00:00",
"tx_end_time": "2021-02-19T16:41:57.131975+00:00",
"response_time_secs": 6.665106,
"data_package_id": "20210120",
"tenant_id": "test",
"user_id": "test",
"c_report_id": "1185927A8FA5C8101",
"seed_input": {
"company_name": "Bold Penguin",
"address": "100 E Broad St, Columbus, OH 43215"
},
"cleansed_input": {
"companyName": "Bold Penguin",
"website": "http://boldpenguin.com/",
"phoneNumber": "(614) 699-2114",
"confidence_score": 0.95,
"address": {
"streetAddr": "100 E Broad St 15th floor",
"city": "Columbus",
"state": "OH",
"zipOrPostalCode": "43215",
"country": "US",
"placeId": "ChIJq6q2PjKPOIgRbnZUv4AsHX8",
"geoPosition": {
"latitude": 39.96307950000001,
"longitude": -82.99746379999999
}
}
},
"connector_crawl_status": {
"completed": 5,
"failed": 0,
"inprogress": 0,
"not_triggered": 3
},
"data": {
"company_id": "1185927A8FA5C8101",
"company_name": "Bold Penguin",
"phone_number": "6146992114",
"website": "www.boldpenguin.com",
"address": "100 E BROAD ST",
"city": "COLUMBUS",
"state": "OH",
"postal_code": "43215",
"primary_naics_2017": [
{
"code": "524210",
"desc": "Life insurance agencies"
}
],
"secondary_naics_2017": [
{
"code": "524298",
"desc": "All Other Insurance Related Activities"
},
{
"code": "531210",
"desc": "Offices of Real Estate Agents and Brokers"
},
{
"code": "524291",
"desc": "Claims Adjusting"
}
],
"year_founded": "2018",
"annual_revenue": "34458426",
"total_full_time_employees": "59",
"primary_naics_2012": [
{
"code": "524210",
"desc": "Insurance Agencies and Brokerages"
}
],
"secondary_naics_2012": [
{
"code": "524298",
"desc": "Insurance exchanges"
},
{
"code": "524210",
"desc": "Agencies, insurance"
},
{
"code": "524210",
"desc": "Brokerages, insurance"
},
{
"code": "524210",
"desc": "Brokers' offices, insurance"
},
{
"code": "524210",
"desc": "Insurance agencies"
},
{
"code": "524210",
"desc": "Insurance brokerages"
},
{
"code": "524210",
"desc": "Life insurance agencies"
},
{
"code": "531210",
"desc": "Offices of Real Estate Agents and Brokers"
},
{
"code": "524291",
"desc": "Claims Adjusting"
}
]
},
"scores": {
"primary_naics_2017": "82.42",
"year_founded": "75.59",
"annual_revenue": "75.59",
"total_full_time_employees": "75.59",
"primary_naics_2012": "82.42"
}
}
Sample Error Response
{
"error_code": "ERR_100",
"error_description": "address is not valid",
"seed_input": {
"company_name": "The Laundry Lady, Inc.",
"address": "8505 Elizabeth St.,Punta Gorda,OK 33950,US"
},
"tx_id": "test-ef35d41f-9914-4608-a363-6b14728fa63c",
"tx_start_time": "2021-01-19T17:16:31.598573+00:00",
"tenant_id": "test",
"user_id": "test"
}
Error Codes
| Error Code | Type | Error Category | Description |
|---|---|---|---|
| ERR_100 | String | INVALID_INPUT | The input from the request which is invalid or unable to read |
| ERR_200 | String | API_ERROR | Any exception which is not handled as part of the business logic while processing the request |
| ERR_300 | String | INTEGRATION_ERROR | Errors while communicating with the downstream services |
| ERR_400 | String | DB_ERROR | Communication failures with the databases |
| ERR_700 | String | TIMEOUT_ERROR | The request wait timeouts |
| ERR_800 | String | SERVICE_UNAVAILABLE | Error when the dependent services are unavailable |
| ERR_900 | String | UNKNOWN | Any error which does not fall in to the above categories |