Predictive Insights - Async Bulk API Integration

Overview

This document describes the interface used to score and enrich bulks of leads / accounts with Predictive Insights on asynchronous basis. The interface is based on HTTPS REST API. Calling this API with basic lead information will result in the return of the following information:

  • Contact and company information Name, address, website, contact
  • Predictive Insights’ Score and Rank Group (as defined on Predictive Insights’ platform)
  • Enriched insights (Boolean, Numeric, Text)
  • Contact and company quality flags

The enrichment can be done for any of the customer's markets that were built within Predictive Insights’ SaaS system. Per market and upon request, Predictive Insights will provide the list of Input/Request fields needed for triggering the enrichments and the Output/Response enriched fields that will be sent back.

This document describes the general interface used for integration. The server address is: https://api.mintigo.com.
Access to the API is done in two phases, asynchronously:

  • First of all, you access the “submission” URL, as described below, and supply basic lead information. This call returns immediately with the URL that will return the results of this call, “monitoring” URL.
  • When “monitoring” URL is accessed it returns:
    • Empty data, if the leads were not yet processed.
    • When processing has finished, the URL will return the required information.
    • Information is available on the "monitoring" URL for 10 minutes. After that, Request ID is expired and associated information is cleaned from our internal data structures.

Authentication

The integration does not require special authentication mechanism. The platform generates random string (UUID) that should be used to access the API.

Configuration in Predictive Insights Platform

In order to perform integration with the Bulk API, you need to perform configurations on the Predictive Insights side and then implement the relevant configurations on the platform connecting to the API.

You need to choose the market for integration as well as the list of fields that are required for Input and a list of fields that will be output by the API.

Connect to Predictive Insights platform (as a user in Administrator or Marketing OPs roles) and select the desired market to integrate with. Click on ‘Market Integrations’ option under ‘Other’ to open relevant configuration screen.

Screen Shot 2020-07-31 at 4.10.38 AM.png

For integration with Async Bulk API, choose relevant tab:

Screen Shot 2020-07-31 at 4.11.29 AM.png

Perform the following steps to configure:

  1. Choose input fields for enrichment. Fields that were used for model creation are marked with asterisk. You can map additional fields as well.

  2. Choose your Indicators and other fields that you would like to receive from Predictive Insights.

    1. Marketing Indicators are selected in the ‘Exportable MIs’ section. Please note that you first need to choose exportable indicators in the Enrichment tab of the market.

    2. Record Columns section includes fields like Predictive Score and Rank.

  3. Please click on ‘Activate’ toggle to enable Bulk integration for this market.

  4. Click on ‘Save’.

  5. Click on ‘View Payload’ button. This button opens a popup that provides information relevant for the integration, such as:

    1. API URL URL that should be invoked for enrichment. You will send POST request to this URL.

    2. Sample request JSON. For example: [{"url":{{Edit Me}},"country":{{Edit Me}},"customer_company_name":{{Edit Me}}}]

  6. You are now ready to integrate this market with Async Bulk API. 

Interfaces

Submission URL

Description

This is the API call responsible for the submission of data. The response is returned immediately. Each call provides enrichment for one market. Each bulk request can have up to 1000 leads / accounts. It is possible to issue up to 100 bulk requests at a single time.

Definition

Request Method

POST

Path

/api/enrich_bulk_receiver/<UUID>/

Request URI Parameters 

It is possible to make sure that enriched leads are not persisted in Predictive Insights DB. In order to enable that (default behavior is to persist) you need to append the following URI parameter: non_persist.
For example:
/api/enrich_bulk_receiver/284409371cd8c9a1a2cf27c3a6995 d64?non_persist

Request Content 

SON containing a list of elements, each element containing keys and values according to what you have defined in the configuration:
Key (string)
– The “Mintigo Name” for each of the input fields. All the fields must exist (even if one gets empty value).

Value (string) The value for the key, representing the lead or the account information (all values must be converted to a string) Typically account-related fields would be:

  • customer_company_name (Company name)
  • url (URL)

Typically lead-related fields would be:

  • contact_first_name (First name of the contact)
  • contact_last_name (Last name of the contact)
  • customer_email (Email of the contact)
  • customer_company_name (Company name)
  • url (URL)
Response Content

A URL that should be used for "monitoring" and collection of the results 

 

Response Status Codes

200

Success.

400

Unable to parse the JSON or empty JSON.

404

UUID does not exist.

408

Internal processing error.

412

Market does not have online enrichment enabled.

413

Too many leads are sent in a single JSON request, more than 1000.

413

Too many requests were issued and are being currently processed.

 

Example - Request for lead enrichment:

POST /api/enrich_bulk_receiver/284409371cd8c9a1a2cf27c3a6995d64/ HTTP/1.1 Accept-Encoding: identity
Content-Length: 207
Host: mintigo-edm-lg.appspot.com

Content-Type: application/x-www-form-urlencoded Connection: close
User-Agent: Python-urllib/2.6

[{"contact_first_name": "Elizabeth", "contact_last_name": "Jackson", "customer_company_name": "learning solutions", "customer_email": "Elizabeth.Jackson@learning.com"},

{"contact_first_name": "Jacob", "contact_last_name": "Shama", "customer_company_name": "Mintigo", "customer_email": "jacob@mintigo.com"}]

 

Response:

Date: Wed, 10 Dec 2014 16:03:48 GMT Content-Encoding: gzip X-Frame-Options: SAMEORIGIN
Vary: Cookie

Content-Type: text/html; charset=utf-8
Connection: keep-alive
Strict-Transport-Security: max-age=31536000; includeSubDomains; Content-Length: 100

https://api.mintigo.com/api/enrich_bulk_monitoring/4927c3b34b954485adeb978 0977a9868/8784/

 

Example - Request for account enrichment:

POST /api/enrich_bulk_receiver/284409371cd8c9a1a2cf27c3a6995d64/ HTTP/1.1 Accept-Encoding: identity
Content-Length: 207
Host: mintigo-edm-lg.appspot.com

Content-Type: application/x-www-form-urlencoded Connection: close
User-Agent: Python-urllib/2.6

[{'customer_company_name':'Mintigo','url':'www.mintigo.com'},]

Response is similar to response for lead requests.

Monitoring URL

Description

This is the API call responsible for the collection of results. The response is returned immediately. If processing of the bulk is not done, API will return empty content with HTTP 206 response code. If the processing has finished, API will return JSON with the required enriched information.

As stated above, this data will be available for 10 minutes, after that Request ID is expired and data is removed from our internal data structures.

Definition

Request Method

GET

Path

/api/enrich_bulk_monitoring/<UUID>/<Request ID>/

Request URI Parameters

None

Request Content

None

Response Content

JSON containing a list of elements, each element containing the following keys and values:
Key (string) -
The “Mintigo Name” for the enriched field (please refer to the information provided by Customer Support Team)
Value (string) - The value of the enriched field. For
Boolean values, “True”/”False” values will be returned. The platform may not return one or more of the fields due to lack of qualified data.

The platform will always return all input fields in addition to the enriched fields.

Response Status Codes

200

Success.

206

Response for given Request ID is not ready yet. 

400

Request ID was not found.

404

UUID does not exist.

410

Request ID was expired.

Example 

Request: 

GET /api/enrich_bulk_monitoring/284409371cd8c9a1a2cf27c3a6995d64/ HTTP/1.1
Accept-Encoding: identity
Content-Length: 207

Host: mintigo-edm-lg.appspot.com
Content-Type: application/x-www-form-urlencoded Connection: close
User-Agent: Python-urllib/2.6

Response:

HTTP/1.1 200 OK Content-Type: text/html; charset=utf-8 Cache-Control: no- cache Expires: Fri, 01 Jan 1990 00:00:00 GMT Vary: Cookie Date: Mon, 17 Nov 2014 08:29:47 GMT
Content-Encoding: gzip

Content-Length: 265 Connection: close

[{"customer_email": "Elizabeth.Jackson@
learning.com", "contact_last_name": "Jackson", "number_of_employees_category ": "50 - 100", "industry_categories": "Education", "customer_company_name": " Learning Solutions Inc", "contact_first_name": "Elizabeth", "is_b2b_company": "F alse"}, {"customer_email": "jacob@mintigo.com", "contact_last_name": "Shama" , "number_of_employees_category": "50 - 100", "industry_categories": "Software ", "customer_company_name": "Mintigo Inc", "contact_first_name": "Jacob", "is_ b2b_company": "True"}]

Status URL

Description

Status URL can be used in order to monitor status of all Bulk API tasks that were submitted for processing. Each task can be in one of two states, Running and Done. ‘Running’ state means that task has been submitted for processing or that it is currently being processed. ‘Done’ means that task has been finished and its results are available via Monitoring URL.

Status URL should not be called for each submitted task, instead, it allows end-user to see status of all tasks in a single call.

Definition

Request Method

GET

Path

/api/enrich_bulk_status/<UUID>/ 

Request URI Parameters

None

Request Content 

None

Response Content

JSON containing a list of elements, each element containing the following keys and values:

  • Key (string) URL identifying a submitted task
  • Value (string) Task status, either Running or Done

 

Example 

Request:

GET /api/enrich_bulk_status/284409371cd8c9a1a2cf27c3a6995d64/ HTTP/1.1

Accept-Encoding: identity
Content-Length: 207
Host: mintigo-edm-lg.appspot.com
Content-Type: application/x-www-form-urlencoded Connection: close
User-Agent: Python-urllib/2.6

 

Response:

HTTP/1.1 200 OK Content-Type: text/html; charset=utf-8Cache-Control: no- cache Expires: Fri, 01 Jan 1990 00:00:00 GMT Vary: Cookie Date: Mon, 17 Nov 2014 08:29:47 GMT

Content-Encoding: gzip

Content-Length: 265 Connection: close

 

{"https://api.mintigo.com/api/v1.0/enrich_bulk_monitoring/b18fec61ee8f4412b2 9e05ca5398e97b/98364/": "Running", "https://api.mintigo.com/api/v1.0/enrich_bulk_monitoring/b18fec61ee8f4412b29 e05ca5398e97b/98367/": "Done", "https://api.mintigo.com/api/v1.0/enrich_bulk_monitoring/b18fec61ee8f4412b29 e05ca5398e97b/98365/": "Running", "https://api.mintigo.com/api/v1.0/enrich_bulk_monitoring/b18fec61ee8f4412b29 e05ca5398e97b/98366/": "Running"}

Contributors
Latest Articles
Modeling Data Requirements
Predictive Insights
4 weeks ago
09-08-2020
08-04-2020
Labels (1)