Photos

Endpoints for accessing generated AI headshot photos.

List Model Photos

Returns all generated headshot photos for a model with pagination.

GET /organization/models/:modelId/photos

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Results per page (max 200)
`offset`	integer	0	Number of results to skip
`status`	string	`active`	Filter by photo status (`active`, `deleted`)
`likedStatus`	string	-	Filter by user's rating (`none`, `liked`, `loved`)
`include`	string	`main`	URL variants to include (`main`, `all`)

Request

curl -X GET "https://server.headshotpro.com/api/v2/organization/models/507f1f77bcf86cd799439011/photos?likedStatus=loved" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "photos": [
    {
      "id": "507f1f77bcf86cd799439022",
      "status": "active",
      "likedStatus": "loved",
      "createdAt": "2024-01-15T11:45:00.000Z",
      "urls": {
        "main": "https://cdn.headshotpro.com/photos/abc123.jpg?signature=..."
      },
      "expiresAt": "2024-01-16T11:45:00.000Z"
    }
  ],
  "pagination": {
    "total": 40,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

URL Variants

When include=all, the response includes additional URL variants:

{
  "urls": {
    "main": "https://cdn.headshotpro.com/photos/abc123.jpg",
    "thumbnail": "https://cdn.headshotpro.com/photos/abc123_thumb.jpg",
    "original": "https://cdn.headshotpro.com/photos/abc123_original.jpg"
  }
}

Signed URLs

All photo URLs are signed and expire after 24 hours. The expiresAt field indicates when URLs become invalid. Fetch new URLs by calling the endpoint again.

Get Favorite Photo

Returns the user's selected favorite headshot photo.

GET /organization/models/:modelId/photos/favorite

Request

curl -X GET "https://server.headshotpro.com/api/v2/organization/models/507f1f77bcf86cd799439011/photos/favorite" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (with favorite selected)

{
  "success": true,
  "photo": {
    "id": "507f1f77bcf86cd799439022",
    "modelId": "507f1f77bcf86cd799439011",
    "status": "active",
    "likedStatus": "loved",
    "createdAt": "2024-01-15T11:45:00.000Z",
    "urls": {
      "main": "https://cdn.headshotpro.com/photos/abc123.jpg?signature=..."
    },
    "expiresAt": "2024-01-16T11:45:00.000Z"
  }
}

Response (no favorite selected)

{
  "success": true,
  "photo": null,
  "message": "No favorite photo has been selected yet"
}

Get Photo Details

Returns a single photo with signed URLs.

GET /organization/models/:modelId/photos/:photoId

Request

curl -X GET "https://server.headshotpro.com/api/v2/organization/models/507f1f77bcf86cd799439011/photos/507f1f77bcf86cd799439022?include=all" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "photo": {
    "id": "507f1f77bcf86cd799439022",
    "modelId": "507f1f77bcf86cd799439011",
    "status": "active",
    "likedStatus": "loved",
    "createdAt": "2024-01-15T11:45:00.000Z",
    "urls": {
      "main": "https://cdn.headshotpro.com/photos/abc123.jpg",
      "thumbnail": "https://cdn.headshotpro.com/photos/abc123_thumb.jpg",
      "original": "https://cdn.headshotpro.com/photos/abc123_original.jpg"
    },
    "expiresAt": "2024-01-16T11:45:00.000Z"
  }
}

Batch Download Photos

Returns signed download URLs for multiple photos at once.

POST /organization/models/:modelId/photos/download

Request Body

Field	Type	Required	Description
`photoIds`	array	No	Specific photo IDs (omit for all photos)
`include`	string	No	URL variants (`main`, `all`)

Request

curl -X POST "https://server.headshotpro.com/api/v2/organization/models/507f1f77bcf86cd799439011/photos/download" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "photoIds": ["507f1f77bcf86cd799439022", "507f1f77bcf86cd799439023"],
    "include": "all"
  }'

Response

{
  "success": true,
  "downloads": [
    {
      "photoId": "507f1f77bcf86cd799439022",
      "urls": {
        "main": "https://cdn.headshotpro.com/photos/abc123.jpg",
        "thumbnail": "https://cdn.headshotpro.com/photos/abc123_thumb.jpg",
        "original": "https://cdn.headshotpro.com/photos/abc123_original.jpg"
      }
    },
    {
      "photoId": "507f1f77bcf86cd799439023",
      "urls": {
        "main": "https://cdn.headshotpro.com/photos/def456.jpg",
        "thumbnail": "https://cdn.headshotpro.com/photos/def456_thumb.jpg",
        "original": "https://cdn.headshotpro.com/photos/def456_original.jpg"
      }
    }
  ],
  "expiresAt": "2024-01-16T11:45:00.000Z"
}

List Organization Favorites

Returns all favorite photos across your entire organization with member information. Useful for creating team photo galleries or directories.

GET /organization/photos/favorites

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Results per page (max 200)
`offset`	integer	0	Number of results to skip
`teamId`	string	-	Filter by team
`include`	string	`main`	URL variants to include

Request

curl -X GET "https://server.headshotpro.com/api/v2/organization/photos/favorites?teamId=team_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "photos": [
    {
      "id": "507f1f77bcf86cd799439022",
      "modelId": "507f1f77bcf86cd799439011",
      "member": {
        "id": "user_abc123",
        "email": "john@example.com",
        "name": "John Doe",
        "teamId": "team_xyz789",
        "teamName": "Marketing"
      },
      "likedStatus": "loved",
      "urls": {
        "main": "https://cdn.headshotpro.com/photos/abc123.jpg"
      },
      "expiresAt": "2024-01-16T11:45:00.000Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Use Cases

Team directory - Display all team members' headshots on your intranet
Slack/Teams integration - Sync headshots to your workspace
Company website - Create an "Our Team" page
Email signatures - Automate headshot deployment to email systems