getUserByExternalId

The getUserByExternalId method allows you to retrieve a specific user from the Teamwork Graph using their external ID. This is useful for fetching individual users when you know their external identifier.

Method signature

1
2
getUserByExternalId(request: GetUserByExternalIdRequest): Promise<GetUserByExternalIdResponse>

Parameter: request

• Type: GetUserByExternalIdRequest
• Required: Yes
• Description: The request containing the external ID.

1
2
// GetUserByExternalIdRequest object:
{
  externalId: string; // externalId: The external identifier of the user
}

Usage examples

Basic user retrieval

1
2
import { graph } from '@forge/teamwork-graph';
const request = {
  externalId: 'user-123'
};
const response = await graph.getUserByExternalId(request);
if (response.success) {
  console.log('User found:', response.user);
} else {
  console.error('Error retrieving user:', response.error);
}

Accessing user properties

1
2
const response = await graph.getUserByExternalId({
  externalId: 'user-123'
});
if (response.success && response.user) {
  const user = response.user;
  console.log('User ID:', user.id);
  console.log('Display Name:', user.displayName);
  console.log('Username:', user.userName);
  console.log('Nickname:', user.nickname);
  if (user.name) {
    console.log('Full Name:', user.name.formatted);
    console.log('First Name:', user.name.givenName);
    console.log('Last Name:', user.name.familyName);
  }
  if (user.emails) {
    const primaryEmail = user.emails.find(email => email.primary);
    console.log('Primary Email:', primaryEmail?.value);
  }
  if (user.extendedProfile) {
    console.log('Job Title:', user.extendedProfile.jobTitle);
    console.log('Department:', user.extendedProfile.department);
    console.log('Organization:', user.extendedProfile.organization);
    console.log('Location:', user.extendedProfile.location);
  }
}

Request limits

Only one externalId per request.

Request validation

The method validates the following:

• externalId required: The externalId field must be a non-empty string.
• Only contains one externalId: The request only contains one externalId.

Error handling

Response

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

1
2
// GetUserByExternalIdResponse
{
  success: boolean;           // Indicates if the operation was successful
  user?: User;               // The retrieved user (if found)
  error?: string;            // Error message (if operation failed)
  originalError?: unknown;   // Original error object (if available)
}

User object structure

The returned User object contains comprehensive user information:

1
2
type User = {
  id: string;                    // Internal user ID (ARI)
  externalId: string;            // External identifier
  userName?: string;             // Username
  name?: UserName;               // Structured name information
  nickname?: string;             // User's nickname
  displayName?: string;          // Display name
  photos?: UserPhoto[];          // User profile photos
  emails?: UserEmail[];          // User email addresses
  extendedProfile?: UserExtendedProfile; // Additional profile information
  meta?: {                       // Metadata
    resourceType: string;
    created: string;
    lastModified: string;
    location: string;
  };
};

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.GetUserByExternalIdRequest = {
  externalId: 'user-123'
};

// Type-safe response handling
const response = await graph.getUserByExternalId(request);
if (response.success && response.user) {
  // TypeScript knows user exists here and provides proper typing
  const user = response.user;
  // Access user properties safely with full type support
  console.log('User ID:', user.id);
  console.log('Display Name:', user.displayName);
  if (user.emails) {
    // TypeScript knows emails is an array of UserEmail
    const primaryEmail = user.emails.find(email => email.primary);
    console.log('Primary Email:', primaryEmail?.value);
  }
}

The type system ensures:

• request.externalId must be a string
• response.user is properly typed as User when success is true
• All user properties have correct types and optional/required status
• Compile-time validation prevents type mismatches