Insert Data

The insert_data() method creates new records in DealCloud objects. Large payloads are split using cellPaginationLimit from config; parallel posts respect create_concurrency (Advanced configuration). HTTP is via intapp-rest-client.

💡

output defaults to "list"; use "pandas" or "polars" when you want a DataFrame back.

Basic Insert

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)
 
# Create records
new_companies = [
    {
        "CompanyName": "Acme Corporation",
        "Industry": 101,  # Choice ID
        "Revenue": 1000000
    },
    {
        "CompanyName": "Beta Industries",
        "Industry": 102,
        "Revenue": 500000
    }
]
 
# Insert and get results with EntryIds
result = dc.insert_data("Company", new_companies)
 
for company in result:
    print(f"Created: {company['CompanyName']} (ID: {company['EntryId']})")

Input Formats

# List of dictionaries
records = [
    {"CompanyName": "Company A", "Industry": 101},
    {"CompanyName": "Company B", "Industry": 102},
]
result = dc.insert_data("Company", records)

Field Mapping

All column names must match field API Names:

# Good: Uses API names
records = [{"CompanyName": "Test", "Industry": 101}]
 
# Bad: Display names won't work
records = [{"Company Name": "Test", "Industry Type": 101}]  # KeyError!

To find API names:

fields = dc.get_fields("Company")
for f in fields:
    print(f"{f.name} -> {f.apiName}")

Reference Field Values

Using DealCloud IDs (Default)

# Reference by EntryId
records = [
    {
        "FirstName": "John",
        "LastName": "Smith",
        "Company": 12345  # Company EntryId
    }
]
result = dc.insert_data("Contact", records)

Using Lookup Values

Use use_dealcloud_ids=False to reference by a lookup field:

# Reference by lookup column value
records = [
    {
        "FirstName": "John",
        "LastName": "Smith",
        "Company": "Acme Corp"  # Will look up by CompanyName
    }
]
 
result = dc.insert_data(
    "Contact",
    records,
    use_dealcloud_ids=False,
    lookup_column="CompanyName"  # Field to match on
)

💡

When using use_dealcloud_ids=False, choice fields accept names instead of IDs: "Industry": "Technology" instead of "Industry": 101

Choice Field Values

# Get choice ID first
fields = dc.get_fields("Company")
industry = next(f for f in fields if f.apiName == "Industry")
tech_id = next(c.id for c in industry.choiceValues if c.name == "Technology")
 
# Use ID
records = [{"CompanyName": "Tech Corp", "Industry": tech_id}]
dc.insert_data("Company", records)

User Field Values

# Get user ID first
users = dc.get_users()
john_id = next(u.id for u in users if u.email == "john@example.com")
 
# Use ID
records = [{"DealName": "Big Deal", "AssignedTo": john_id}]
dc.insert_data("Deal", records)

Multi-Select Fields

# Multiple values as list
records = [
    {
        "DealName": "Joint Venture",
        "Companies": [12345, 67890],  # Multiple company IDs
        "Industries": [101, 102, 103]  # Multiple choice IDs
    }
]
dc.insert_data("Deal", records)

Parameters

Parameter	Type	Default	Description
`object_id`	`str \| int`	Required	Object API name or ID
`data`	`List[dict] \| DataFrame`	Required	Records to insert (accepts pandas or Polars)
`use_dealcloud_ids`	`bool`	`True`	Use IDs vs lookup values
`lookup_column`	`str`	None	Field for lookups (when `use_dealcloud_ids=False`)
`output`	`str`	`"list"`	Output format: `"list"`, `"write_result"`, `"pandas"`, or `"polars"`
`error_handling`	`ErrorHandling`	`FAIL_FAST`	How to handle transport errors in parallel batches
`raise_on_row_errors`	`bool`	`False`	When `True`, raise `DealCloudValidationError` if any row has `"Errors"`
`progress_callback`	`Callable`	None	Progress callback `(current, total)`

Output Formats

# Default: List of dicts
result = dc.insert_data("Company", records)  # output="list"
for record in result:
    print(record["EntryId"])

Return Value

Returns list of inserted records with EntryId populated. When the API returns row-level "Errors" on HTTP 200, those rows are included in the list (default). Use split_row_results, output="write_result", or raise_on_row_errors=True to handle them.

result = dc.insert_data("Company", [{"CompanyName": "New Corp"}])
 
print(result)
# [
#     {
#         "EntryId": 123456,
#         "CompanyName": "New Corp",
#         ...
#     }
# ]

Error Handling

from dealcloud_sdk import ErrorHandling
 
# Stop on first error (default)
try:
    result = dc.insert_data(
        "Company",
        records,
        error_handling=ErrorHandling.FAIL_FAST
    )
except Exception as e:
    print(f"Failed: {e}")

Common Errors

Error Code	Description	Solution
`5006`	Invalid reference	Check Entry ID exists
`5007`	Required field missing	Add required field
`5008`	Invalid choice value	Check choice ID exists
`KeyError`	Unmapped column	Use correct API name

Batch Processing

Large inserts are automatically batched:

# 10,000 records are batched automatically
large_dataset = [{"CompanyName": f"Company {i}"} for i in range(10000)]
result = dc.insert_data("Company", large_dataset)

With Progress Tracking

def on_progress(current, total):
    print(f"Inserted {current}/{total}")
 
result = dc.insert_data(
    "Company",
    large_dataset,
    progress_callback=on_progress
)

Typed Insert

Using Pydantic models:

from pydantic import BaseModel
from typing import Optional
 
class Company(BaseModel):
    EntryId: Optional[int] = None
    CompanyName: str
    Industry: Optional[int] = None
 
new_companies = [
    Company(CompanyName="Acme Corp", Industry=101),
    Company(CompanyName="Beta Inc", Industry=102),
]
 
result = dc.typed_insert_data("Company", new_companies, Company)
 
for company in result:
    print(f"Created {company.CompanyName} (ID: {company.EntryId})")

Best Practices

Batch similar records - Group inserts for efficiency
Validate data first - Check for required fields before insert
Use transactions mentally - All records in a batch succeed or fail together
Handle errors appropriately - Use COLLECT for batch operations
Use lookup values for imports - use_dealcloud_ids=False is easier for external data

Update Data - Updating records
Upsert Data - Insert or update
ID Mapping - External ID mapping

Polars Integration Update Data