What is the MSIGHTS Inbound API?

The MSIGHTS Inbound API is a REST API, which is to be used by vendors to upload responses programmatically. The responses uploaded via Inbound API are received in MSIGHTS Data Importer through an Import Record (IR).

Getting Started

To use MSIGHTS Inbound API, the following is needed:

API Credentials - can be provided by your MSIGHTS Client Engagement representative. The credentials are composed of 3 elements: username, password, and format. Please reach out to your representative to have these created

Base Server Address - The base server API address is https://inbound.msights.com. Please note that HTTPS is required. You will not be able to connect through unencrypted HTTP.

How to use the Inbound API?

To submit responses via the MSIGHTS Inbound API, you need to execute the following steps:

Step 1. Obtain the list of required columns

Obtain the latest list of required columns expected by the Data Importer format using the endpoint “Describe a loader format”.

Request

GET /v1/format/describe

Request Parameters

Parameter Name	Type	Description	Required
user	string	Provided as part of the API credentials	Yes
password	string	Provided as part of the API credentials	Yes
format	string	Provided as part of the API credentials	Yes

Sample Response returned by the Endpoint “Describe a loader format”

{
"responseCode": 0,
"responseMessage": "success",
"requestTrackerId": "98df802876c711efaa07763d383c1b2c",
"data": {
 "format": "linkedin_leads",
 "columns": [
{
 "name": "first_name",
 "required": true,
 "minLength": 0,
 "maxLength": 256
},
{
 "name": "email",
 "required": true,
 "minLength": 3,
 "maxLength": 256
},
{
 "name": "job_title",
 "required": false,
 "minLength": 0,
 "maxLength": 100
    }
  ]
 }
}

The list of columns returned by this method should be used to create your /v2/response.json request.

Every column has 4 properties, explained below:

name (String)	The name of the field will be used on the /v1/response.json request payload.
required (Boolean)	Specify if a field is required or not, to accept or reject a response at the Data Importer.
minLength (Integer)	Min length accepted by the field value.
maxLength (Integer)	Max length accepted by the field value.

Step 2: Send the responses through the API in JSON format:

The endpoint “Send data to Inbound API” will be used to send a list of responses to be loaded into the Data Importer loader (also specified in the request). The list of responses should be sent in the request at the property data, which should contain an array of elements. Every element should contain the Data Importer loader format fields including its values. This endpoint requires a header and body.

Request

POST /v2/response.json

Request Header

Header Name	Type	Description	Required
Authorization	string	Basic authorization header, including username and password of the user	Yes
Content Type	string	Default value: application/json	Yes
Accept	string	Default value: application/json	Yes

Request Body

{
"format": "linkedin_leads",
"data": [
 {
"first_name": "John",
"last_name": "Doe",
"email": "jdoe@company.com",
"job_title": "Chief of Marketing"
},
{
"first_name": "Jane",
"last_name": "Fitcher",
"email": "jane.fitcher@supercompany.com"
 }
]
}

Please refer to Appendix A for a complete sample JSON.

Step 3: Receive the API response

Once Step 2 is completed, the API will send a response.

Please see below for potential responses and corresponding meanings that a user will receive:

Response Code	Interpretation	Additional Notes
200 { "responseCode": 0, "responseMessage": "processing data asynchronously.", "requestTrackerId": "98df802876c711efaa07763d383c1b2c" }	Request successfully processed	The response is added to the queue.
400	Bad Request	The receiving server does not recognize or is unable to process the request. No import record will be generated.
401/ 403	Unauthorized	The request is unauthorized. No import record will be generated. These errors are typically associated with authentication.

Step 4: Obtain the status of a request

Every successful request (response code = 200) via the endpoint “Send data to Inbound API” will place the response into an internal queue. Every 5 minutes, all the responses in the queue will be packaged and sent as a single Import Record in Data Importer.

The endpoint “Query the status of a request” will be used to query the status of a request. The RequestTrackerId is the identifier returned by the Send data to Inbound API method. The response will contain the status of the request and the Data Importer Import Record that contains the responses.

Request

GET /v2/status/{RequestTrackerId}

Request Header

Header Name	Type	Description	Required
Authorization	string	Basic authorization header, including username and password of the user	Yes
Content Type	string	Default value: application/json	Yes
Accept	string	Default value: application/json	Yes

Sample Response returned by the Endpoint “Query the status of a request”

{
"responseCode": 0,
"responseMessage": "success",
"requestTrackerId": "5fcbd60876cf11ef84f572547389ed11",
"data": {
 "status": "finished",
"trackerId": "5fcbd60876cf11ef84f572547389ed11",
"dataImporterId": 67887
  }
}

The variable “dataImporterid” is the Import Record created in Data Importer. A single Import Record can hold multiple responses (leads).

Step 5: Confirm that the response has been accepted in the Data Importer

Once the Import Record is generated, the validations will run in Data Importer and the responses within it will be accepted or rejected.

A summary notification with the accepted and rejected records will be sent to the API user’s email. In the event the responses are rejected, the user will need to access Data Importer and run the “error report” to get the details on the rejection reasons.

Below is a screenshot of the summary notification:

Troubleshooting Common Errors

The following table describes the common errors that may be experienced when using the Inbound API and how to fix them. If you have tried the suggestions described below but are still experiencing issues, please contact MSIGHTS Support.

Error Message	Suggestion
Status code 403 Missing authentication token	Confirm that the credentials header is sent.
400	Confirm that all the required columns in the format are included in the JSON. Verify that all data includes open and closed double quotes. Validate the JSON format using a third party such as “JSON formatter and validator”.

Appendix A - Sample JSON Request for Multiple Responses

The following is a sample JSON request that includes three responses that will be sent.

Please note that this sample is based on the "Cross Region - Standard (GDPR)" template/loader.

The data included in this sample is not real and should not be used when trying to connect.

POST https://inbound.msights.com/v2/response.json

Request Headers

Authorization: Basic dXNlckBtc2lnaHRzLmNvbToxMjMzMjFBQkM=

{
"format": "lead_details_loader"
"data": [
{
"company": "Fake Company",
"addr": "1001 Fake Street",
"city": "Minneapolis",
"state": "Minnesota",
"zip": "55404",
"country": "United States",
"salutation": null,
"prefix": null,
"fname": "John",
"lname": "Doe",
"suffix": null,
"title": "Manager- Project Management",
"job_function": "Manager/Head of Dept",
"department": "Product Management",
"phone": "+88844444444",
"extension_phone": null,
"email": "john.doe@fakecompany.com",
"fax": null,
"extension_fax": null,
"data_sharing_consent": "Provided",
"timezone": "Eastern Standard Time - UTC-5:00",
"site_form_url": "https://staging.wisdominterface.com/find-out-how-to-turn-ai-into-real-business-value-us/",
"time": "2024-07-25 15:56:57",
"companysize": "1000 - 4999",
"vendor": "FakeVendor",
"site_name": "FakeVendor",
"offer_code": "OD-00017772031",
"tactic_wbs": "CRM-YA24-INT-2612645",
"offer_title": "AI Webcast Replay: Harness the full potential of Business AI",
"campaign_manager": "Moritz Doe",
"date": "07/22/2024",
"industry": "Wholesale Distribution",
"comments": null,
"consent_language": "English",
"general_marketing_consent": null,
"email_channel_preference": null,
"phone_channel_preference": null
},
{
"company": "Smart Company LLC",
"addr": "19 Main Ave",
"city": "Phoenix",
"state": "Arizona",
"zip": "85027",
"country": "United States",
"salutation": null,
"prefix": null,
"fname": "Sarah",
"lname": "Doe",
"suffix": null,
"title": "Inventory Manager",
"job_function": "Manager/Head of Dept",
"department": "Operations/Business",
"phone": "+12365785",
"extension_phone": null,
"email": "sarah.doe@smartcompany.com",
"fax": null,
"extension_fax": null,
"data_sharing_consent": "Provided",
"timezone": "Eastern Standard Time - UTC-5:00",
"site_form_url": "https://staging.wisdominterface.com/six-ai-use-cases-revolutionizing-supply-chains-and-operations-us/",
"time": "2024-07-25 15:56:56",
"companysize": "10000+",
"vendor": "FakeVendor",
"site_name": "FakeVendor",
"offer_code": "OD-00017772031",
"tactic_wbs": "CRM-YA24-INT-2612645",
"offer_title": "IDC Infobrief: The Importance of AI in Supply Chain and Operations",
"campaign_manager": "Moritz Doe",
"date": "07/22/2024",
"industry": "Wholesale Distribution",
"comments": null,
"consent_language": "English",
"general_marketing_consent": null,
"email_channel_preference": null,
"phone_channel_preference": null
},
{
"company": "Smart Company LLC",
"addr": "19 Main Ave",
"city": "Phoenix",
"state": "Arizona",
"zip": "85027",
"country": "United States",
"salutation": null,
"prefix": null,
"fname": "Sarah",
"lname": "Doe",
"suffix": null,
"title": "Inventory Manager",
"job_function": "Manager/Head of Dept",
"department": "Operations/Business",
"phone": "+12365785",
"extension_phone": null,
"email": "sarah.doe@smartcompany.com",
"fax": null,
"extension_fax": null,
"data_sharing_consent": "Provided",
"timezone": "Eastern Standard Time - UTC-5:00",
"site_form_url": "https://staging.wisdominterface.com/six-ai-use-cases-revolutionizing-supply-chains-and-operations-us/",
"time": "2024-07-25 15:56:56",
"companysize": "10000+",
"vendor": "FakeVendor",
"site_name": "FakeVendor",
"offer_code": "OD-00017772031",
"tactic_wbs": "CRM-YA24-INT-2612645",
"offer_title": "IDC Infobrief: The Importance of AI in Supply Chain and Operations",
"campaign_manager": "Moritz Doe",
 "date": "07/22/2024",
},
{
"company": "Any Company.",
"addr": "5 Airport Dr",
"city": "Brampton",
"state": "Ontario",
"zip": "L6T 4N8",
"country": "Canada",
"salutation": null,
"prefix": null,
"fname": "Will",
"lname": "Doe",
"suffix": null,
"title": "Vice President Sales",
"job_function": "Vice President",
"department": "Sales",
"phone": "+2894158786",
"extension_phone": null,
"email": "willdoe@anycompany.ca",
"fax": null,
"extension_fax": null,
"data_sharing_consent": "Provided",
"timezone": "Eastern Standard Time - UTC-5:00",
"site_form_url": "https://staging.wisdominterface.com/six-ai-use-cases-revolutionizing-supply-chains-and-operations-ca/",
"time": "2024-07-25 15:56:57",
"companysize": "1000 - 4999",
"vendor": "FakeVendor",
"site_name": "FakeVendor",
"offer_code": "OD-00017772031",
"tactic_wbs": "CRM-YA24-INT-2612645",
"offer_title": "IDC Infobrief: The Importance of AI in Supply Chain and Operations",
"campaign_manager": "Moritz Doe",
"date": "07/22/2024",
"industry": "Wholesale Distribution",
"comments": null,
"consent_language": "English",
"general_marketing_consent": "Not Provided",
"email_channel_preference": null,
"phone_channel_preference": null
"companysize": "1000 - 4999",
"vendor": "FakeVendor",
"site_name": "FakeVendor",
"offer_code": "OD-00017772031",
"tactic_wbs": "CRM-YA24-INT-2612645",
"offer_title": "IDC Infobrief: The Importance of AI in Supply Chain and Operations",
"campaign_manager": "Moritz Doe",
"date": "07/22/2024",
"industry": "Wholesale Distribution",
"comments": null,
"consent_language": "English",
"general_marketing_consent": "Not Provided",
"email_channel_preference": null,
"phone_channel_preference": null
  }
 ]
}

Please do not hesitate to reach out to MSIGHTS Support via the messenger chat window at the bottom right-hand corner of your screen or with the button below for any questions, support, or feedback. We'd be happy to help!

MSIGHTS Support