deleteUsersByExternalId

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
 }

Usage examples

Basic bulk deletion

1
2
import { graph } from '@forge/teamwork-graph';
const request = {
  externalIds: ['user-123', 'user-456']
};
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']
};
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

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']
};

// 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