HeadshotPro / API Docs
API Key

Team Members

Endpoints for listing and managing team members in your organization.

List All Team Members

Returns all team members in your organization with pagination. Supports filtering by member status.

GET /organization/team

Query Parameters

ParameterTypeDefaultDescription
limitinteger50Results per page (max 200)
offsetinteger0Number of results to skip
statusstring-Filter by status: accepted, pending, finished

Request

curl -X GET "https://server.headshotpro.com/api/v2/organization/team?status=finished&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "members": [
    {
      "id": "507f1f77bcf86cd799439011",
      "email": "john@example.com",
      "name": "John Doe",
      "status": "finished",
      "teamId": "team_xyz789",
      "teamName": "Marketing",
      "modelId": "507f1f77bcf86cd799439022",
      "modelStatus": "active",
      "joinedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 25,
    "offset": 0,
    "hasMore": true
  }
}

Member Status Values

StatusDescription
acceptedMember signed up but hasn't started uploading photos
pendingMember is uploading photos or headshots are being generated
finishedHeadshots are ready

List Accepted Members

Returns members who accepted their invite but haven't completed their headshots yet.

GET /organization/team/accepted

Request

curl -X GET "https://server.headshotpro.com/api/v2/organization/team/accepted" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "members": [
    {
      "id": "507f1f77bcf86cd799439011",
      "email": "jane@example.com",
      "name": null,
      "teamId": "team_xyz789",
      "teamName": "Marketing",
      "joinedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "count": 1
}

List Pending Members

Returns members currently in the onboarding or headshot generation process.

GET /organization/team/pending

Request

curl -X GET "https://server.headshotpro.com/api/v2/organization/team/pending" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "members": [
    {
      "id": "507f1f77bcf86cd799439011",
      "email": "bob@example.com",
      "name": "Bob Smith",
      "teamId": "team_abc123",
      "teamName": "Engineering",
      "modelId": "507f1f77bcf86cd799439033",
      "modelStatus": "generatingHeadshots",
      "joinedAt": "2024-01-16T09:00:00.000Z"
    }
  ],
  "count": 1
}

List Finished Members

Returns members with completed headshots. Includes additional fields like photo count and favorite selection.

GET /organization/team/finished

Request

curl -X GET "https://server.headshotpro.com/api/v2/organization/team/finished" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "members": [
    {
      "id": "507f1f77bcf86cd799439011",
      "email": "john@example.com",
      "name": "John Doe",
      "teamId": "team_xyz789",
      "teamName": "Marketing",
      "modelId": "507f1f77bcf86cd799439022",
      "modelStatus": "active",
      "photoCount": 40,
      "hasFavorite": true,
      "finishedAt": "2024-01-15T11:45:00.000Z",
      "joinedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "count": 1
}

Additional Fields for Finished Members

FieldTypeDescription
photoCountintegerNumber of generated headshots
hasFavoritebooleanWhether the user has selected a favorite
finishedAtdatetimeWhen headshot generation completed

Add Members to Team

Adds existing organization members to a specific team. Users must already be part of your organization (through a used invite).

POST /organization/teams/:teamId/members

Request Body

FieldTypeRequiredDescription
emailsarrayYesArray of email addresses to add

Request

curl -X POST "https://server.headshotpro.com/api/v2/organization/teams/team_xyz789/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["john@example.com", "jane@example.com"]
  }'

Response

{
  "success": true,
  "message": "Members added successfully"
}

Error Responses

StatusCodeDescription
400INVALID_REQUESTEmails array is required and must contain at least one email
400INVALID_REQUESTOne or more users not found in organization
404NOT_FOUNDTeam not found

Notes

  • Users must already exist in your organization (their invite must have been used)
  • Adding a user to a team removes them from their previous team (users can only be in one team)
  • To remove a user from a team without adding them to another, you would need to delete the team or contact support

Example: Dashboard Integration

// Node.js example: Build a team dashboard showing member progress
async function getTeamDashboard() {
  const apiKey = process.env.HEADSHOTPRO_API_KEY;
  const baseUrl = 'https://server.headshotpro.com/api/v2';

  // Fetch all member categories in parallel
  const [accepted, pending, finished] = await Promise.all([
    fetch(`${baseUrl}/organization/team/accepted`, {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }).then(r => r.json()),

    fetch(`${baseUrl}/organization/team/pending`, {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }).then(r => r.json()),

    fetch(`${baseUrl}/organization/team/finished`, {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }).then(r => r.json())
  ]);

  return {
    summary: {
      accepted: accepted.count,
      pending: pending.count,
      finished: finished.count,
      total: accepted.count + pending.count + finished.count
    },
    needsReminder: accepted.members, // Users who need a nudge
    inProgress: pending.members,
    completed: finished.members
  };
}

Example: Bulk Team Assignment

// Node.js example: Assign users to teams based on department
const departments = {
  'team_marketing': ['alice@company.com', 'bob@company.com'],
  'team_engineering': ['carol@company.com', 'dave@company.com'],
  'team_sales': ['eve@company.com']
};

for (const [teamId, emails] of Object.entries(departments)) {
  await fetch(`https://server.headshotpro.com/api/v2/organization/teams/${teamId}/members`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ emails })
  });
}
Teams Models