Data Ingestion API

The Data Ingestion API is a high-volume, low-latency, highly available service. Use it to ingest large amounts of person and person-related data with minimal delay.

Data Ingestion requests execute asynchronously. To retrieve request status, subscribe to events from the Marketo Observability Data Stream.

The API provides interfaces for five object types:

Read the Data Ingestion API documentation.

Authentication

The Data Ingestion API uses the same OAuth 2.0 authentication method as the Marketo REST API to generate an access token. Pass the access token in the X-Mkto-User-Token HTTP header. You cannot pass it as a query parameter.

The following example passes an access token in the header:

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

Permissions

Data Ingestion uses the Marketo REST API permissions model and does not require additional permissions. Each endpoint requires a specific existing permission, as shown in the following table.

Supported Object Types

Headers

Data Ingestion supports the following custom HTTP headers.

Request

Response

Requests

Send data to the server with the HTTP POST method.

Include the data in the request body as application/json.

Use the domain mkto-ingestion-api.adobe.io.

The path begins with /subscriptions/MunchkinId, where MunchkinId is specific to your Marketo instance. Find your Munchkin ID in the Marketo Engage UI under Admin > My Account > Support Information. The remainder of the path specifies the resource.

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

Example URL for Lists:

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

Responses

Every response returns a unique request ID in the X-Request-Id header.

Example of request ID via header:

X-Request-Id: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Success

A successful call returns status 202 and no response body.

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 fails, it returns a non-202 status and a response body with error details. The application/json response body contains one object with error_code and message members.

The following error codes are reused from Adobe Developer Gateway.

Data Ingestion API-specific error codes contain three segments: the three-digit status returned by Adobe Developer Gateway, a zero “0”, and three additional digits.

Retries

When the service detects a transient error, it retries the operation. A retry occurs primarily when a dependent service times out or is temporarily unavailable.

The service uses the following retry intervals:

Endpoints

Ingestion endpoints are available for Persons, Custom Objects, Companies, Program Members, and Lists. Each endpoint section defines the request and provides an example.

Persons

Use this endpoint 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

Use this endpoint 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 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

Use this endpoint to sync company records. It 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

Lists (Add to List)

Endpoint used to add leads to a static list. Leads are identified by their Marketo lead ID.

Headers

Request body

Each object in the input array contains:

Required permissions are Read-Write Lead.

Lists add to list example

Request

POST /subscriptions/{munchkinId}/lists

Headers

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

Body

{
   "listId": 1001,
   "leads": [
      {
         "leadId": 10001
      },
      {
         "leadId": 10002
      },
      {
         "leadId": 10003
      }
   ]
}

Response

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Lists add to list validation rules

Lists (Remove from List)

Endpoint used to remove leads from a static list. Leads are identified by their Marketo lead ID.

Headers

Request body

Each object in the input array contains:

Required permissions are Read-Write Lead.

Lists remove from list example

Request

POST /subscriptions/{munchkinId}/lists/remove

Headers

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

Body

{
   "listId": 1001,
   "leads": [
      {
         "leadId": 10001
      },
      {
         "leadId": 10002
      }
   ]
}

Response

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

Lists remove from list validation rules

Limits

The Data Ingestion API has the following guardrails:

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

Data Ingestion API vs REST API

The Data Ingestion API differs from other Marketo REST APIs in the following ways: