DataConnectorIngestApi Metadata Type in SFDX

Architectural Overview#

The DataConnectorIngestApi metadata type configures Ingestion API connection endpoints and data contracts within Salesforce Data Cloud. The Ingestion API provides a push-based integration pattern allowing external applications, microservices, mobile applications, and IoT fleets to transmit real-time telemetry or bulk batches directly into Data Cloud Data Lake Objects (DLOs).

In an enterprise integration architecture, DataConnectorIngestApi establishes the schema blueprint (derived from OpenAPI/JSON schema specifications). When client applications authenticate via a Connected App using OAuth 2.0 client credentials or JWT bearer flows, Data Cloud validates incoming payload structures against this metadata definition prior to landing records in staging lake storage.

Directory and File Suffix Conventions#

In SFDX source format, DataConnectorIngestApi metadata files are located in the dataConnectorIngestApis directory within your package directory:

Key Metadata Fields#

Declarative XML and Manifest Examples#

Source Format XML (Mobile_Telemetry_Connector.dataConnectorIngestApi-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<DataConnectorIngestApi xmlns="http://soap.sforce.com/2006/04/metadata">
    <developerName>Mobile_Telemetry_Connector</developerName>
    <masterLabel>Mobile App Telemetry Ingest API</masterLabel>
    <description>Receives high-velocity mobile customer interaction events via Ingestion API.</description>
    <status>Active</status>
    <sourceType>Streaming</sourceType>
</DataConnectorIngestApi>

Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Mobile_Telemetry_Connector</members>
        <name>DataConnectorIngestApi</name>
    </types>
    <version>68.0</version>
</Package>

Retrieval and Deployment Commands#

Use the Salesforce CLI to retrieve and deploy DataConnectorIngestApi components:

# Retrieve all Ingestion API connectors from the target org
sf project retrieve start --metadata DataConnectorIngestApi

# Retrieve a specific Ingestion API connector by name
sf project retrieve start --metadata DataConnectorIngestApi:Mobile_Telemetry_Connector

# Deploy Ingestion API connector metadata to target environment
sf project deploy start --metadata DataConnectorIngestApi:Mobile_Telemetry_Connector

Senior Architect Best Practices and Gotchas#

• Schema Immutability Considerations: Once an Ingest API connector is deployed and actively streaming data to linked Data Streams, modifying field types in the schema contract can disrupt ongoing ingestion pipelines. Always introduce versioned schema objects rather than in-place breaking changes.
• Pair with Connected App Security: DataConnectorIngestApi governs the schema contract, while a Connected App handles transport authentication. Ensure deployment pipelines coordinate both assets and assign appropriate permissions via PermissionSet.
• Data Kit Packaging: For ISVs and enterprise multi-org templates, encapsulate DataConnectorIngestApi within a DataPackageKitDefinition so subscribers can install ingestion schemas without manual field recreation.

Frequently asked questions

What is the role of DataConnectorIngestApi in Data Cloud?

It defines the connector schema and OpenAPI specification used to ingest streaming and bulk data from external applications via the Ingest API.

Where are DataConnectorIngestApi files stored in SFDX projects?

They are stored in force-app/main/default/dataConnectorIngestApis/ with the file suffix .dataConnectorIngestApi-meta.xml.

Can DataConnectorIngestApi support both streaming and bulk modes?

Yes. Ingestion API connectors support streaming ingestion for real-time telemetry and bulk mode for periodic file uploads.

How do you deploy DataConnectorIngestApi components across orgs?

You deploy them using the sf project deploy start command or bundle them inside Data Cloud Data Kits for repeatable multi-org rollout.