EAPs are offered to selected users for testing and feedback purposes. We are currently working with a select group of EAP participants to get their apps production-ready and available for publishing on Marketplace.

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

The deleteUsersByExternalId method allows you to bulk delete multiple users from the Teamwork Graph using their external IDs. This is useful for removing users in batches when you know their external identifiers.

Method signature

1
2
deleteUsersByExternalId(request: DeleteUsersByExternalIdRequest): Promise<DeleteUsersByExternalIdResponse>

Parameter: request

Type: DeleteUsersByExternalIdRequest
Required: Yes
Description: The bulk deletion request containing external IDs.

1
2
 // DeleteUsersByExternalIdRequest object:
 {
   externalIds: string[]; // externalIds: Array of external identifiers of users to delete
   connectionId?: string; // Optional: Connection identifier for multi-connection scenarios
 }

Usage examples

Basic bulk deletion

1
2
import { graph } from '@forge/teamwork-graph';
const request = {
  externalIds: ['user-123', 'user-456'],
  connectionId: 'connection-id-123'
};
const response = await graph.deleteUsersByExternalId(request);
if (response.success) {
  console.log('Deletion results:', response.results);
} else {
  console.error('Error deleting users:', response.error);
}

Handling deletion results

1
2
const request = {
  externalIds: ['user-1', 'user-2', 'user-3', 'user-4'],
  connectionId: 'connection-id-123'
};
const response = await graph.deleteUsersByExternalId(request);
if (response.success && response.results) {
  response.results.forEach(result => {
    if (result.success) {
      console.log(`Successfully deleted user: ${result.externalId}`);
    } else {
      console.error(`Failed to delete user ${result.externalId}: ${result.error}`);
    }
  });
}

Request limits

Maximum external IDs per request: 100
Minimum external IDs per request: 1

Request validation

The method validates the following:

externalIds must be an array: The externalIds field must be a valid array.
externalIds cannot be empty: The externalIds array cannot be empty.
Maximum limit: Cannot exceed 100 externalIds per request.

Error handling

Error message	Description
`externalIds must be an array`	The `externalIds` field is not an array.
`externalIds array cannot be empty`	The `externalIds` array is empty.
`Failed to delete users by external ID`	The API request failed.

Response

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

1
2
 // DeleteUsersByExternalIdResponse
 {
   success: boolean;           // Indicates if the overall operation was successful
   results?: Array<{          // Individual results for each external ID
     externalId: string;      // The external ID that was processed
     message?: string;
     statusCode: number;
   }>;
   error?: string;            // Overall error message (if operation failed)
   originalError?: unknown;   // Original error object (if available)
 }

Type safety

The SDK provides type-safe request and response objects that ensure compile-time validation:

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

// Type-safe request creation
const request: types.DeleteUsersByExternalIdRequest = {
  externalIds: ['user-123', 'user-456'],
  connectionId: 'connection-id-123'
};

// Type-safe response handling
const response = await graph.deleteUsersByExternalId(request);
if (response.success && response.results) {
  // TypeScript knows results exists here
  response.results.forEach(result => {
    // result is properly typed with externalId, message, statusCode, and success
    if (result.success) {
      console.log(`Successfully deleted user: ${result.externalId}`);
      // TypeScript knows statusCode exists
      console.log(`Status: ${result.statusCode}`);
    } else {
      console.error(`Failed to delete user ${result.externalId}`);
      // TypeScript knows message exists
      if (result.message) {
        console.error(`Message: ${result.message}`);
      }
    }
  });
}

The type system ensures:

request.externalIds must be a string array
response.results is properly typed as an array when success is true
Each result object has the correct structure with externalId, message, statusCode, and success properties
Compile-time validation prevents type mismatches