Data Ingestion API

The Data Ingestion API is a high volume, low latency, highly available service designed to handle ingestion of large amounts of person and person related data efficiently and with minimal delays.

Data is ingested by submitting requests that execute asynchronously. Request status can be retrieved by subscribing to events from the Marketo Observability Data Stream.

Interfaces are offered for four object types: Persons, Custom Objects, Companies, and Program Members. The record operation is “insert or update” only, except for Program Members which also supports delete.

Authentication

The Data Ingestion API uses the same OAuth 2.0 authentication method as Marketo REST API to generate an access token, but the access token must be passed via HTTP header X-Mkto-User-Token. You cannot pass the access token via a query parameter.

Example Access Token via Header:

X-Mkto-User-Token: 11606815-aa7a-405a-80a1-f9683efa528b:ab

Permissions

Data Ingestion uses the same permissions model as the Marketo REST API, and does not require any additional special permissions to use, though specific permissions are required for each endpoint.

Supported Object Types

Headers

Data Ingestion makes use of the following custom HTTP headers.

Request

Response

Requests

Use the HTTP POST method to send data to the server.

The data representation is included in the request body as application/json.

The domain name is: mkto-ingestion-api.adobe.io

The path begins with /subscriptions/MunchkinId where MunchkinId is specific to your Marketo instance. You can find your Munchkin ID in the Marketo Engage UI under Admin > My Account > Support Information. The remainder of the path is used to specify the resource of interest.

Example URL for Persons:

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/persons

Example URL for Custom Objects:

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/customobjects/purchases

Example URL for Companies:

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/companies

Example URL for Program Members:

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/programmembers

Responses

All responses return a unique request ID via the X-Request-Id header.

Example of request ID via header:

X-Request-Id: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Success

When a call is successful, a 202 status is returned. No response body is returned.

Example of Success Response:

HTTP/1.1 202 Accepted
X-Request-Id: e3d92152-0fb1-444a-8f8f-29d5a2338598
Content-Length: 0
Date: Wed, 18 Oct 2023 18:56:49 GMT

Error

When a call produces an error, a non-202 status is returned along with a response body with additional error detail. The response body is application/json and contains a single object with members error_code and message.

Below are reused error codes from Adobe Developer Gateway.

Below are error codes that are unique to the Data Ingestion API and are comprised of 3 segments. The first three digits are the status (returned by Adobe Developer Gateway), followed by a zero “0”, followed by three digits.

Retries

When a transient error is detected, the service retries the operation three times. The first retry occurs after a 5 minute wait period, the second after 30 more minutes, and finally the third after 30 more minutes. Retries happen for various reasons, primarily when a dependent service times out or is temporarily not available.

Endpoints

Ingestion endpoints are available for Persons, Custom Objects, Companies, and Program Members.

Persons

Endpoint used to upsert person records.

Headers

Request body

Permissions required are Read-Write Lead.

Persons example

Request

POST /subscriptions/{munchkinId}/persons

Headers

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Body

{
   "priority": "high",
   "partitionName": "EMEA",
   "dedupeFields": {
      "field1": "email",
      "field2": "firstName"
   },
   "persons":[
      {
         "email": "brooklyn.parker@karnv.com",
         "firstName": "Brooklyn",
         "lastName": "Parker",
         "company": "Karnv"
      },
      {
         "email": "johnny.neal@yvu30.com",
         "firstName": "Johnny",
         "lastName": "Neal",
         "company": "Acme Inc"
      }
   ]
}

Response

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Custom Objects

Endpoint used to upsert custom object records.

Headers

Request body

Required permissions are Read-Write Custom Object.

If a link field to a Person is specified in the request and that Person does not exist, several retries occur. If that Person is added during the retry window (65 minutes), then the update is successful. For example, if the link field is email on Person, and Person does not exist, then a retries occur.

Custom Objects example

Request

POST /subscriptions/{munchkinId}/customobjects/{customObjectAPIName}

Headers

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Body

{
   "dedupeBy": "dedupeFields",
   "priority": "high",
   "customObjects": [
      {
         "email": "brooklyn.parker@karnv.com",
         "vin": "20UYA31581L000000",
         "make": "BMW",
         "model": "3-Series 330i",
         "year": 2003
      },
      {
         "email": "johnny.neal@yvu30.com",
         "vin": "19UYA31581L000000",
         "make": "BMW",
         "model": "3-Series 325i",
         "year": 1989
      }
   ]
}

Response

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Companies

Endpoint used to sync company records. Supports create, update, and upsert operations with deduplication by external company ID or Marketo internal ID.

Headers

Request body

Each company object in the input array supports the following fields:

Required permissions are Read-Write Company.

Companies example

Request

POST /subscriptions/{munchkinId}/companies

Headers

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Body

{
   "action": "createOrUpdate",
   "dedupeBy": "dedupeFields",
   "input": [
      {
         "externalCompanyId": "ext-company-001",
         "company": "Acme Corporation",
         "industry": "Technology",
         "numberOfEmployees": 5000,
         "annualRevenue": 100000000
      },
      {
         "externalCompanyId": "ext-company-002",
         "company": "Globex Industries",
         "industry": "Manufacturing",
         "numberOfEmployees": 1200
      }
   ]
}

Response

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Companies update-by-ID example

{
   "action": "updateOnly",
   "dedupeBy": "idField",
   "input": [
      {
         "id": 12345,
         "company": "Acme Corporation (Renamed)",
         "numberOfEmployees": 5500
      }
   ]
}

Companies validation rules

Program Members (Sync)

Endpoint used to sync program member status, adding leads to programs or updating their program status.

Headers

Request body

Each object in the programs array contains:

Each object in the members array contains:

Required permissions are Read-Write Lead.

Program Members sync example

Request

POST /subscriptions/{munchkinId}/programmembers

Headers

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Body

{
   "programs": [
      {
         "programId": 1001,
         "status": "Member",
         "members": [
            {
               "leadId": 10001
            },
            {
               "leadId": 10002
            }
         ]
      },
      {
         "programId": 1002,
         "status": "Influenced",
         "members": [
            {
               "leadId": 10003
            }
         ]
      }
   ]
}

Response

HTTP/1.1 202
X-Request-ID: e3d92152-0fb1-444a-8f8f-29d5a2338598

Program Members sync validation rules

Program Members (Delete)

Endpoint used to remove leads from programs. This sets the lead’s membership status to "Not in Program" and removes the member from that program.

Headers

Request body

Each object in the programs array contains:

Each object in the members array contains:

Required permissions are Read-Write Lead.

Program Members delete example

Request

POST /subscriptions/{munchkinId}/programmembers/delete

Headers

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Body

{
   "programs": [
      {
         "programId": 1001,
         "members": [
            {
               "leadId": 10001
            },
            {
               "leadId": 10002
            }
         ]
      },
      {
         "programId": 1002,
         "members": [
            {
               "leadId": 10003
            }
         ]
      }
   ]
}

Response

HTTP/1.1 202
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Program Members delete validation rules

Limits

Here is an updated list of guardrails:

These limits apply uniformly across Persons, Custom Objects, Companies, and Program Members. For Program Members, “objects per request” is the total number of lead references across all programs in a single request.

Data Ingestion API vs REST API

Here is a list of differences between Data Ingestion API and other Marketo REST APIs: