Last updated Aug 18, 2025

deleteObjectsByProperties

The Connector SDK APIs are available through Forge's Early Access Program (EAP).

EAPs are offered to selected users for testing and feedback purposes. APIs and features under EAP are unsupported and subject to change without notice. APIs and features under EAP are not recommended for use in production environments.

To use the Connector SDK, you must be part of the Forge connector EAP. You can express interest in joining this EAP through this form.

Overview

The deleteObjectsByProperties method allows you to delete entities from the Teamwork Graph based on specific property criteria. This is useful for removing entities that match certain conditions rather than knowing their exact external IDs.

Method signature

1
2
deleteObjectsByProperties(request: DeleteObjectsByPropertiesRequest): Promise<DeleteObjectsByPropertiesResponse>

Parameter: request

Type: DeleteObjectsByPropertiesRequest
Required: Yes
Description: The properties object containing criteria for object deletion.

1
2
// DeleteObjectsByPropertiesRequest object:
Record<string, string> // A properties object containing key-value pairs for deletion criteria

Usage examples

Basic property-based deletion

1
2
import { graph } from '@forge/teamwork-graph';
const request = {
  environment: 'staging'
};
const response = await graph.deleteObjectsByProperties(request);
if (response.success) {
  console.log('Deletion completed successfully');
} else {
  console.error('Error deleting entities:', response.error);
}

For EAP, deleteObjectsByProperties supports only 1 key-value pair as shown in the above example.

Handling deletion response

1
2
const request = {
  environment: 'staging'
};
const response = await graph.deleteObjectsByProperties(request);
if (response.success) {
  console.log('All matching entities deleted successfully');
} else {
  console.error('Deletion failed:', response.error);
  if (response.originalError) {
    console.error('Original error:', response.originalError);
  }
}

Request limits

Only one property per request.

Request validation

The method validates the following:

Must be an object: The request must be a valid object.
Only contains one property: The property object must only contain one property criteria for deletion.

Error handling

Error message	Description
`properties must be an object`	The request is not an object.
`properties object cannot be empty`	The properties object is empty.
`Property-based deletion failed`	The overall operation failed.

Response

The method returns a promise that resolves to a DeleteObjectsByPropertiesResponse object.

1
2
// DeleteObjectsByPropertiesResponse
{
  success: boolean;           // Indicates if the overall operation was successful
  error?: string;             // Overall error message (if operation failed)
  originalError?: unknown;    // Original error object (if available)
}

Type Safety

The SDK provides type-safe responses that ensure compile-time validation:

1
2
import { types } from '@forge/teamwork-graph';

// Type-safe request creation
const request: types.DeleteObjectsByPropertiesRequest = {
  environment: 'staging'
};

const response = await graph.deleteObjectsByProperties(request);
if (response.success) {
  // TypeScript knows success is true here
  console.log('All matching entities deleted successfully');
} else {
  // TypeScript knows error exists here
  console.error('Deletion failed:', response.error);
  
  // Safely access originalError if available
  if (response.originalError) {
    console.error('Original error details:', response.originalError);
  }
}

The type system ensures:

request must be a valid object with string key-value pairs
response.success is always a boolean
response.error and response.originalError are properly typed when present
Compile-time validation prevents type mismatches