API Reference

Complete method reference for the DealCloud Python SDK. The documentation targets dealcloud-sdk 1.x; the package is available on PyPI (opens in a new tab).

Client Properties

Read-Only Configuration

Property	Type	Description
`site_url`	`str`	DealCloud site URL
`api_url`	`str`	Full API base URL
`auth_scope`	`str`	OAuth2 scope string
`refresh_id_maps`	`bool`	Whether to refresh ID maps on operations
`page_size`	`int`	Default page size
`read_concurrency`	`int`	Read operation parallelism
`delete_page_size`	`int`	Delete batch size

API Endpoint URLs

Property	Type	Description
`api_url_v1`	`str`	Base v1 API URL
`schema_url`	`str`	Schema endpoint URL
`data_url`	`str`	Data endpoint URL
`entrydata_url`	`str`	Entry data endpoint URL
`rows_url`	`str`	Rows endpoint URL
`query_url`	`str`	Query endpoint URL
`views_url`	`str`	Views endpoint URL
`cells_url`	`str`	Cells endpoint URL
`history_url`	`str`	History endpoint URL
`files_url`	`str`	Files endpoint URL
`usermanagement_url`	`str`	User management endpoint URL
`publications_url`	`str`	Publications endpoint URL
`backups_url`	`str`	Backups endpoint URL
`relationship_intelligence_url`	`str`	Relationship Intelligence endpoint URL
`merge_url`	`str`	Merge endpoint URL

Mutable Configuration

Property	Type	Description
`retry_status_codes`	`dict`	HTTP status codes to retry (mutable)
`concurrency_limits`	`ConcurrencyLimits`	Concurrency settings (mutable)
`query_settings`	`QuerySettings`	Pagination settings (mutable)

Client Access

Property	Type	Description
`client`	`RestClient`	Underlying REST client for custom API calls

Schema Caching

Property / Method	Type	Description
`cache_schema`	`bool`	Whether to cache schema (default: True). Set in constructor.
`schema_cache_ttl`	`float`	Schema cache TTL in seconds (default: 300). Set in constructor.
`refresh_schema()`	method	Force refresh of schema and user map; updates cache.
`clear_schema_cache()`	method	Clear schema cache for this site.

Client Initialization

DealCloud

from dealcloud_sdk import DealCloud, DealCloudConfig
 
# Direct initialization
dc = DealCloud(
    site_url="yoursite.dealcloud.com",
    client_id="12345",
    client_secret="your-secret",
    cache_schema=True,       # Default: use schema cache
    schema_cache_ttl=300.0   # Default: 5 minutes
)
 
# Factory methods (prefer full DealCloudConfig)
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)
dc = DealCloud.from_config("dealcloud_config.json")  # Full config file (path)
dc = DealCloud.from_json("config.json")           # Legacy/simple credential file
dc = DealCloud.from_yaml("config.yaml")            # Legacy/simple credential file
# Environment variables only: DealCloud.from_env()

For full configuration (timeouts, retry, query settings), use from_config(config_path) or DealCloudConfig.from_json_file / from_yaml_file plus from_config_object(config). Use from_json() / from_yaml() for legacy or simple credential-only files.

Schema API

Method	Description	Returns
`get_objects()`	Get all objects	`List[Object]`
`get_fields(object_id)`	Get fields for object	`List[Field]`
`get_fields()`	Get all fields	`List[Field]`
`get_fields_by_ids(ids)`	Get specific fields	`List[Field]`
`get_schema()`	Get complete schema	`Schema`
`get_users()`	Get all users	`List[User]`
`get_currencies()`	Get currencies	`List[str]`
`get_field_types()`	Get field types	`List[dict]`
`get_system_field_types()`	Get system field types	`List[dict]`
`get_system_entry_types()`	Get system entry types	`List[dict]`
`get_filter_operations()`	Get filter operations	`List[dict]`
`export_schema_to_excel(path)`	Export schema to Excel	`Path`

Data API - Read

Method	Description	Returns
`read_data(object_id, output)`	Read data	`DataFrame \| List[dict]`
`read_data_streaming(object_id)`	Stream data	`Iterator[dict]`
`aread_data_streaming(object_id)`	Async stream	`AsyncIterator[dict]`
`typed_read_data(model, object_id)`	Typed read	`List[T]`
`typed_read_data_streaming(model, object_id)`	Typed stream	`Iterator[T]`
`typed_aread_data_streaming(model, object_id)`	Async typed stream	`AsyncIterator[T]`
`list_entries(object_id, ...)`	Get entry IDs	`List[int]`
`list_entries_with_filter(object_id, filters)`	Filtered entry IDs (`filters: List[dict]`)	`List[int]`
`get_cells(object_id, ...)`	Cell-level read	`List[dict]`

read_data() Parameters

Parameter	Type	Default	Description
`object_id`	`str \| int`	-	Object API name or ID
`view_id`	`str \| int`	-	View (alternative)
`output`	`str`	Required	`"pandas"`, `"list"`, `"polars"`, or `"polars_lazy"`
`fields`	`List[str]`	All	Fields to fetch
`query`	`str`	None	DealCloud query string
`view_filter`	`List[dict]`	None	Value Later / view filter values
`resolve`	`str`	None	Legacy reference format (`"id"` / `"name"`)
`include_nulls`	`bool`	True	Include null columns
`column_headers`	`str`	`"api"`	Column naming: `"api"`, `"name"`, or `"id"`
`reference_format`	`ReferenceFormat`	FULL	Reference formatting
`reference_cache`	`ReferenceCache`	None	Reference cache
`error_handling`	`ErrorHandling`	FAIL_FAST	Error behavior (e.g. COLLECT)
`progress_callback`	`Callable`	None	Progress callback

Data API - Write

Method	Description	Returns
`insert_data(object_id, data)`	Insert records	`List[dict] \| DataFrame \| BatchResult \| RowsWriteResult`
`update_data(object_id, data)`	Update records	`List[dict] \| DataFrame \| BatchResult \| RowsWriteResult`
`upsert_data(object_id, data, match_field)`	Upsert records	`List[dict] \| DataFrame \| BatchResult \| RowsWriteResult`
`delete_data(object_id, entry_ids)`	Delete records	`List[dict] \| BatchResult`
`write_cells(object_id, data, mode="upsert")`	Write cells	`List[dict] \| BatchResult \| RowsWriteResult`
`delete_cells(object_id, entry_ids, field_ids=None)`	Delete entries via Cells DELETE (body is entry ID list; `field_ids` ignored)	`List[dict] \| BatchResult`
`typed_insert_data(object_id, data, model)`	Typed insert	`List[T]`
`typed_update_data(object_id, data, model)`	Typed update	`List[T]`
`typed_upsert_data(object_id, data, model, match_field)`	Typed upsert	`List[T]`

Write Parameters

Parameter	Type	Default	Description
`object_id`	`str \| int`	Required	Object API name or ID
`data`	`List[dict] \| pd.DataFrame \| pl.DataFrame`	Required	Records (pandas or Polars supported)
`use_dealcloud_ids`	`bool`	True	Use IDs vs lookups
`lookup_column`	`str`	None	Lookup field
`output`	`str`	`"list"`	`"list"`, `"write_result"`, `"pandas"`, or `"polars"`
`error_handling`	`ErrorHandling`	FAIL_FAST	Parallel transport error behavior (`COLLECT` → `BatchResult`)
`raise_on_row_errors`	`bool \| None`	`None`	Raise `DealCloudValidationError` when any row has `"Errors"`; `None` inherits `DealCloudConfig.raiseOnRowErrors`
`progress_callback`	`Callable`	None	Progress callback

Delta Sync

Method	Description	Returns
`get_modified_entries(object_id, since)`	Get modified IDs	`List[ModifiedEntry]`
`aget_modified_entries(object_id, since)`	Async version	`List[ModifiedEntry]`
`sync_delta(object_id, since, output)`	Full delta sync	`DeltaSyncResult`
`build_entry_id_cache(object_id, key_field)`	Build ID cache	`EntryIdCache`
`map_ids(data, cache, external_id_field)`	Map IDs	`List[dict]`

sync_delta() Parameters

Parameter	Type	Default	Description
`object_id`	`str \| int`	Required	Object API name or ID
`modified_since`	`datetime \| str`	Required	Cutoff datetime
`fields`	`List[str]`	All	Fields to fetch
`output`	`str`	`"list"`	`"list"`, `"pandas"`, `"polars"`, or `"polars_lazy"`
`include_deleted`	`bool`	True	Include deleted entries

Template Reports

Template reports use the Data API base URL (GET .../reports/template, POST .../reports/generate, GET .../reports/{requestId}). Methods are on the main DealCloud client. See the DealCloud docs for Template Reports (opens in a new tab).

Method	Description	Returns
`get_report_templates(page_size=None, page_number=None, id=None)`	List available template reports	`List[dict]`
`generate_report(template_id, remove_empty_table=None, entries=None, user_ids=None, filters=None)`	Start report generation	`dict`
`get_report_status(request_id)`	Poll status or retrieve generated output	`dict`

Files API

Paths use entryfiles/{entryId}/fields/{fieldId} (no object in the download URL). Prefer download_file / download_attachment (aliases).

Method	Description	Returns
`download_file(entry_id, field_id, output_path=None, progress_callback=None)`	Streaming download; `output_path` may be local path or fsspec URI	`bytes` or `str` (path)
`download_attachment(...)`	Alias of `download_file`	same
`download_attachment_metadata(entry_id, field_id)`	File metadata	`dict`
`upload_attachment(object_id, content, file_name, ...)`	Upload to attachments object (multipart)	`dict`
`upload_file_to_entry_field(object_id, entry_id, field, content, file_name, ...)`	Upload bytes to existing row field	`dict`
`delete_file(entry_id, field_id)`	Delete attachment	`bool`
`delete_attachment(...)`	Alias of `delete_file`	`bool`
`export_images(output_dir)`	Export images	`ExportResult`
`export_documents(output_dir)`	Export documents	`ExportResult`
`export_files(output_dir)`	Export all files	`ExportResult`
`export_entry_files(object_id, entry_id, output_dir)`	Export entry files	`ExportResult`

User Management

Method	Description	Returns
`get_users()`	List users	`List[User]`
`get_user(user_id)`	Get user	`User`
`create_user(email, first_name, last_name)`	Create user	`User`
`update_user(user_id, ...)`	Update user	None
`deactivate_user(user_id)`	Deactivate	None
`activate_user(user_id)`	Activate	None
`get_groups()`	List groups	`List[Group]`
`get_group_members(group_id)`	Get members	`List[User]`
`add_user_to_group(user_id, group_id)`	Add to group	None
`remove_user_from_group(user_id, group_id)`	Remove from group	None

Backups

Method	Description	Returns
`request_backup()`	Request backup	`str` (backup ID)
`get_backup_status(backup_id)`	Check status	`dict`
`download_backup(backup_id, output_path)`	Download	`bytes` or None
`list_backups()`	List backups	`List[dict]`

History API

Method	Description	Returns
`get_entry_history(object_id, entry_id, start_date=None, end_date=None, field_ids=None, limit=1000, skip=0)`	Change history for a specific entry	`List[dict]`
`get_object_history(object_id, start_date=None, end_date=None, entry_ids=None, field_ids=None, user_ids=None, limit=1000, skip=0)`	All change history for an object type	`List[dict]`
`get_historical_data(object_id, entry_ids, as_of_date, fields=None)`	Data as it existed at a point in time	`List[dict]`

Publications API

Method	Description	Returns
`get_topics()`	List topic name strings	`List[str]`
`poll_events(topics, *, count, time_out_ms, http_timeout_seconds=None)`	Long-poll for events (`time_out_ms` server wait)	`List[dict]`
`stream_poll_events(topics, *, count, time_out_ms, ...)`	Context manager: streaming HTTP response for large poll bodies	`httpx.Response`
`topic_offsets_from_events(events)`	Build acknowledge payload from poll results	`List[dict]`
`acknowledge_topic_offsets(topic_offsets)`	Acknowledge by topic name/offset	`None`
`init_bootstrap(entity_type, entity_format)`	Request bootstrap drain	`None`
`subscribe(topics, *, callback, time_out_ms, poll_interval=5, count=100, auto_acknowledge=True)`	Blocking poll loop	`None`
`subscribe_async(topics, *, callback, time_out_ms, ...)`	Async subscription helper	`None`

Merge API

Method	Description	Returns
`merge_entries(object_id, winner_entry_id, loser_entry_ids, field_overrides=None, delete_losers=True, transfer_relationships=True)`	Merge duplicate entries into winner	`dict`
`merge_preview(object_id, winner_entry_id, loser_entry_ids)`	Preview merge result	`dict`
`find_duplicates(object_id, field_names, ...)`	Find duplicate entries	`List[dict]`

Relationship Intelligence API

Method	Description	Returns
`import_emails(...)`	Bulk email import	`dict`
`import_email(...)`	Single email import	`dict`
`import_meetings(...)`	Bulk meetings import	`dict`
`import_meeting(...)`	Single meeting import	`dict`
`get_processing_status(...)`	Processing status	`dict`
`get_settings()`	RI settings	`dict`

Other APIs

Method	Description	Returns
`list_configured_views()`	List views	`Rows`
`resolve_view(view)`	Resolve view ID or name to metadata row	`dict`
`resolve_view_display_name(view)`	Resolve view ID or name to display name	`str`

Troubleshooting & FAQ Data Models