Custom Sources API Developer Guide

Overview

The Custom Sources API allows you to define and manage tenant-specific data sources in Demandbase.

Custom Sources extend the standard Demandbase data import framework by enabling you to:

• Create custom source definitions
• Control source priority and merge behavior
• Map external fields to Demandbase fields
• Import Account and Person data attributed to your source
• Preserve source attribution throughout the platform

This API is intended for organizations integrating external systems, ETL pipelines, data warehouses, enrichment services, or proprietary business systems into Demandbase.

Key Concepts

Custom Source

A Custom Source represents a customer-defined origin of imported data.

Examples:

• Snowflake Revenue Feed
• Internal CRM Export
• Partner Intent Stream
• ERP Account Sync
• Customer Success Platform

Each source includes:

Source Attribution

All imported data is attributed to the Custom Source used during import.

Source attribution is visible throughout the platform, including:

• Profiles
• Reporting
• Merge operations
• Data lineage workflows

Merge Priority

Priority determines how field values propagate during merge operations.

Lower numeric values represent higher priority.

Example:

In this example, CRM values take precedence over enrichment values during merge operations.

Supported Objects

The following object types currently support Custom Sources:

Authorization: Bearer <access-token>
Content-Type: application/json

API Workflow

The standard workflow consists of four steps:

1. Create a Custom Source
2. Define field mappings
3. Import data
4. Verify attribution

Step 1 — Create a Custom Source

Create a source definition using the Custom Sources API.

Endpoint

POST /custom_source/

Request Body

{
  "name": "Snowflake Revenue Feed",
  "description": "Revenue enrichment pipeline",
  "priority": 55
}

Request Fields

Example Response

{
  "id": 12345,
  "name": "Snowflake Revenue Feed",
  "description": "Revenue enrichment pipeline",
  "priority": 55,
  "sourceGroup": "custom",
  "createdAt": "2026-04-13T12:00:00Z"
}

Retrieve Custom Sources

Retrieve configured Custom Sources for your tenant.

Endpoint

GET /custom_source/

Example Response

[
  {
    "id": 12345,
    "name": "Snowflake Revenue Feed",
    "priority": 55
  },
  {
    "id": 12346,
    "name": "ERP Sync",
    "priority": 70
  }
]

Retrieve a Specific Custom Source

Endpoint

GET /custom_source/{id}

Example

GET /custom_source/12345

Update a Custom Source

Endpoint

PUT /custom_source/{id}

Example Request

{
  "description": "Updated revenue enrichment feed",
  "priority": 60
}

Delete a Custom Source

Endpoint

DELETE /custom_source/{id}

Field Mapping

Before importing data, define mappings between source fields and Demandbase fields.

Discover Available Fields

Use the required fields endpoint to discover supported Demandbase fields.

Endpoint

GET /data_import/{objectType}/requiredFields/{sourceType}

Example

GET /data_import/account/requiredFields/custom

Example Response

[
  {
    "fieldName": "name",
    "description": "Account name",
    "dataType": "String"
  },
  {
    "fieldName": "website",
    "description": "Account website",
    "dataType": "String"
  }
]

Suggested Field Mappings

Automatic Field Creation

If a CSV column header does not have an explicit field mapping, Demandbase automatically creates a field by:

1. Lowercasing the header
2. Replacing spaces with underscores

Example:

Data Import

After configuring field mappings, import data using the standard Demandbase data import framework.

Retrieve Supported Sources

Retrieve supported source types for a given object type.

Endpoint

GET /data_import/{objectType}/sources

Example

GET /data_import/account/sources

Example Response

[
  {
    "sourceType": "custom",
    "sourceName": "Snowflake Revenue Feed"
  }
]

Import via API

Use the standard Demandbase Data Import APIs to import records associated with your Custom Source.

Imports support:

• Account records
• Person records

Import via UI

You can also import data using the Demandbase UI:

1. Navigate to Data Import
2. Select object type
3. Choose your Custom Source
4. Upload CSV or configure import
5. Run import

Validation Rules

Source Name Rules

The source name:

• Cannot be blank
• Maximum length: 100 characters
• Cannot contain < or >
• Cannot begin with:
  • =
  • +
  • -
  • @
  • tab (\t)
  • carriage return (\r)
• Must be unique within the tenant
• Cannot conflict with built-in integration names

Description Rules

The description:

• Is optional
• Defaults to the source name if omitted
• Maximum length: 300 characters
• Cannot contain < or >
• Cannot begin with:
  • =
  • @

Priority Rules

Tenant Limits

Error Handling

All API errors return the following format:

{
  "error": {
    "code": "<error-code>",
    "message": "<human-readable message>"
  }
}

400 Bad Request

INVALID_FIELD_TYPE

{
  "error": {
    "code": "400-001",
    "message": "Invalid field type."
  }
}

INVALID_SOURCE_GROUP

{
  "error": {
    "code": "400-002",
    "message": "The 'sourceGroup' field is required and must be set to 'custom'."
  }
}

VALIDATION_ERROR

{
  "error": {
    "code": "400-005",
    "message": "Source name cannot contain invalid characters."
  }
}

INVALID_INPUT

{
  "error": {
    "code": "400-006",
    "message": "Invalid request input."
  }
}

404 Not Found

RESOURCE_NOT_FOUND

{
  "error": {
    "code": "404-001",
    "message": "Custom source not found."
  }
}

409 Conflict

DUPLICATE_SOURCE_NAME

{
  "error": {
    "code": "409-001",
    "message": "A custom source with this name already exists."
  }
}

429 Too Many Requests

MAX_SOURCES_LIMIT_REACHED

{
  "error": {
    "code": "429-001",
    "message": "Maximum limit of 50 custom sources per tenant has been reached."
  }
}

500 Internal Server Error

INTERNAL_SERVER_ERROR

{
  "error": {
    "code": "500-001",
    "message": "An unexpected error occurred. Please contact support."
  }
}

Best Practices

Use Stable Source Names

Treat source names as long-lived identifiers.

Recommended:

• salesforce_sync
• snowflake_enrichment
• partner_intent_feed

Establish Clear Priority Strategy

Define source precedence before onboarding multiple systems.

Define Explicit Field Mappings

Explicit mappings provide:

• predictable schemas
• improved governance
• cleaner reporting
• reduced field duplication

Avoid relying exclusively on automatic field creation for production pipelines.

Example End-to-End Workflow

1. Create Source

POST /custom_source/

{
  "name": "partner_intent_feed",
  "description": "Third-party intent provider",
  "priority": 70,
  "sourceGroup": "custom"
}

2. Discover Fields

GET /data_import/account/requiredFields/custom

3. Prepare CSV

Account Name,Account Domain,Intent Score
Acme Inc,acme.com,92
Globex,globex.com,87

4. Import Data

Use:

• Demandbase UI
• Standard Data Import APIs

Associate the import with:

• partner_intent_feed

5. Verify Attribution

After import:

• records display source attribution
• imported fields participate in merge behavior
• reporting reflects source lineage