Cell Operations

Cell operations provide low-level access to individual field values via the Cells REST API, as opposed to row-based operations that work with complete records.

💡

Most use cases are better served by row operations (read_data(), insert_data()). Use cell operations when you need fine-grained control over specific field values, or when the Cells endpoints match your integration pattern.

🔗

The SDK HTTP stack is intapp-rest-client. Retries, pooling, and errors follow that client unless noted otherwise.

When to Use Cells

Use Case	Recommended
Read/write complete records	Row operations
Update many rows for a few fields	Cell operations (`write_cells`)
Read specific fields only	Row read with `fields=` on `read_data()`
Delete entire entries by ID	`delete_cells()` (Cells DELETE — see warning below)

Reading Cells

`get_cells()`

Returns cell-level payloads from POST .../entrydata/get (one request object per entry/field pair, chunked to the API limit).

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)
 
# All cells for all entries and all fields (expensive — prefer filters)
cells = dc.get_cells("Company")
 
for cell in cells[:10]:
    print(cell.get("entryId"), cell.get("fieldId"), cell.get("value"))

Filter by field IDs or API names

Use the fields parameter (List[int] for field IDs, or List[str] for field API names). Do not use field_ids= — the SDK parameter name is fields.

# By field ID
cells = dc.get_cells("Company", fields=[12345, 12346])
 
# By field API name
cells = dc.get_cells("Company", fields=["Status", "Revenue"])

Filter by entries

cells = dc.get_cells(
    "Company",
    entry_ids=[100, 101, 102],
    fields=["Status"],
)

Optional query-style parameters (resolve_reference_url, fill_extended_data, wrap_into_arrays, date_time_behavior, currency_code) match the API; see the SDK docstrings on get_cells().

Listing Entries

`list_entries()`

Returns entry IDs for an object (client-side limit / skip optional):

entry_ids = dc.list_entries("Company")
print(f"Found {len(entry_ids)} entries")

`list_entries_with_filter()`

Returns entry IDs matching filter criteria. Pass a filters argument: a list of dicts with fieldId, value, and filterOperation (or operator, which the SDK maps to filterOperation).

# Example: equals on a field (use your field ID and allowed filterOperation values from schema)
active_ids = dc.list_entries_with_filter(
    "Company",
    filters=[
        {"fieldId": 12345, "operator": "equals", "value": "Active"},
    ],
)

For ad-hoc query strings on rows reads, use read_data(..., query=...) instead.

Writing Cells

`write_cells()`

Writes cell data using EntryId plus field API names as columns (or the equivalent list-of-dicts shape). Supports mode: "create" (negative EntryId), "update" (positive EntryId), or "upsert" (default).

cell_updates = [
    {"EntryId": 12345, "Status": [101], "Revenue": 1500000},
    {"EntryId": 12346, "Status": [102], "Revenue": 800000},
]
 
results = dc.write_cells("Company", cell_updates, mode="update")

Returns List[dict], RowsWriteResult (output="write_result"), or BatchResult when error_handling=COLLECT. Row-level "Errors" on HTTP 200 are included in the list by default; pass raise_on_row_errors=True (or set DealCloudConfig.raiseOnRowErrors) to raise DealCloudValidationError instead.

Error handling (`write_cells` / `delete_cells`)

Same two-channel model as Rows writes: error_handling controls parallel transport failures; row "Errors" in HTTP 200 are returned in the payload unless raise_on_row_errors=True.

from dealcloud_sdk import split_row_results
 
result = dc.write_cells("Company", cell_rows, mode="update")
ok_rows, row_errors = split_row_results(result)
 
write_result = dc.write_cells(
    "Company",
    cell_rows,
    mode="update",
    output="write_result",
)
if write_result.has_row_errors:
    for row in write_result.row_errors:
        print(row["EntryId"], row["Errors"])

from dealcloud_sdk import ErrorHandling
 
result = dc.write_cells(
    "Company",
    cell_rows,
    mode="update",
    error_handling=ErrorHandling.COLLECT,
)
print(result.row_errors, result.errors)

from dealcloud_sdk import DealCloudValidationError
 
try:
    dc.write_cells("Company", cell_rows, mode="update", raise_on_row_errors=True)
except DealCloudValidationError as e:
    for row in e.row_errors:
        print(row["EntryId"], row["Errors"])

delete_cells supports the same error_handling / raise_on_row_errors contract as delete_data (single DELETE request).

backlink_dms_document and create_entry_with_store_requests support raise_on_row_errors only (single dict return). For COLLECT or output="write_result", use write_cells or Rows APIs.

Bulk update one field via cell writes

Use EntryId and the field API name as column keys (not raw entryId/fieldId tuples):

from datetime import datetime
 
entry_ids = dc.list_entries("Company")
fields = dc.get_fields("Company")
processed_field = next(f for f in fields if f.apiName == "ProcessedDate")
 
rows = [{"EntryId": eid, processed_field.apiName: datetime.now().isoformat()} for eid in entry_ids]
dc.write_cells("Company", rows, mode="update")

`delete_cells()` — deletes entries

⚠️

delete_cells(object_id, entry_ids) calls the Cells API DELETE endpoint with an array of entry IDs. It removes those entries (rows), not individual field values. The optional field_ids parameter exists for API compatibility but is ignored by the service. To clear a field’s value, use row updates or write_cells; do not use this method for “clear one field.”

# Delete specific entries entirely (irreversible)
dc.delete_cells("Company", entry_ids=[12345, 12346])

Response / request shapes

Typical cell read objects include entryId, fieldId, and value (camelCase as returned by the API). write_cells builds internal store requests from your EntryId rows and resolved field IDs.

Parameters (summary)

`get_cells()`

Parameter	Type	Description
`object_id`	`str \| int`	Object API name or ID
`entry_ids`	`List[int] \| None`	If omitted, all entry IDs for the object are used
`fields`	`List[int] \| List[str] \| None`	Field IDs or field API names; if omitted, all fields
`resolve_reference_url`, `fill_extended_data`, `wrap_into_arrays`, `date_time_behavior`, `currency_code`	various	Passed through per API

`write_cells()`

Parameter	Type	Default	Description
`object_id`	`str \| int`	—	Object API name or ID
`data`	`list[dict] \| pd.DataFrame \| pl.DataFrame`	—	Rows with `EntryId` and field API name columns
`mode`	`"create" \| "update" \| "upsert"`	`"upsert"`	Operation mode
`output`	`str`	`"list"`	`"list"` or `"write_result"`
`error_handling`	`ErrorHandling`	`FAIL_FAST`	Parallel transport error behavior
`raise_on_row_errors`	`bool \| None`	`None`	Raise on row `"Errors"`; `None` inherits config
`progress_callback`	`Callable`	`None`	Batch progress callback

`delete_cells()`

Parameter	Type	Default	Description
`object_id`	`str \| int`	—	Object API name or ID
`entry_ids`	`List[int]`	—	Entries to delete
`field_ids`	`List[int]`	`None`	Ignored by API
`error_handling`	`ErrorHandling`	`FAIL_FAST`	Transport error behavior
`raise_on_row_errors`	`bool \| None`	`None`	Raise on row `"Errors"`; `None` inherits config
`field_ids`	`List[int] \| None`	Ignored by API (do not rely on it)

`list_entries_with_filter()`

Parameter	Type	Description
`object_id`	`str \| int`	Object API name or ID
`filters`	`List[dict]`	Each dict: `fieldId`, `value`, `filterOperation` (or `operator`)

Use Case: Copy one field to another

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)
 
def migrate_field(object_id: str, old_field_api: str, new_field_api: str) -> int:
    fields = dc.get_fields(object_id)
    old_f = next(f for f in fields if f.apiName == old_field_api)
    new_f = next(f for f in fields if f.apiName == new_field_api)
 
    cells = dc.get_cells(object_id, fields=[old_f.apiName])
    rows = [
        {"EntryId": c["entryId"], new_f.apiName: c["value"]}
        for c in cells
        if c.get("value") is not None
    ]
    if rows:
        dc.write_cells(object_id, rows, mode="update")
    return len(rows)

Performance

Chunking — get_cells chunks to the API field limit (10,000 fields per request).
cellPaginationLimit / concurrency — Controlled via DealCloud config (create_concurrency, etc.).
Prefer fields= and entry_ids= on get_cells() to avoid huge payloads.

cells = dc.get_cells(
    "Company",
    entry_ids=[100, 101, 102],
    fields=["Status"],
)

Basic Reads - Row-based reads
Update Data - Row-based updates
Schema API - Field metadata
API Reference: Cells - Consolidated signatures

ID Mapping Delta Synchronization

Cell Operations

When to Use Cells

Reading Cells

get_cells()

Filter by field IDs or API names

Filter by entries

Listing Entries

list_entries()

list_entries_with_filter()

Writing Cells

write_cells()

Error handling (write_cells / delete_cells)

Bulk update one field via cell writes

delete_cells() — deletes entries

Response / request shapes

Parameters (summary)

get_cells()

write_cells()

delete_cells()

list_entries_with_filter()

Use Case: Copy one field to another

Performance

Related

`get_cells()`

`list_entries()`

`list_entries_with_filter()`

`write_cells()`

Error handling (`write_cells` / `delete_cells`)

`delete_cells()` — deletes entries

`get_cells()`

`write_cells()`

`delete_cells()`

`list_entries_with_filter()`