API Overview

The HeadshotPro V2 API exposes six resource groups under the base URL:

https://server.headshotpro.com/api/v2/organization

All endpoints require a Bearer API key. Responses always include a success boolean, with a data payload on success or error + code on failure.

Resources at a glance

How it works

1. Check your credit balance before starting a campaign to confirm you have enough credits for the invites you plan to send.
2. Create teams (optional) to group members by department or location.
3. Send invites — each invite dispatches an email with a signup link. Credits are consumed when the invited user uploads their photos, not when the invite is sent.
4. Track progress by listing members filtered by status (accepted, pending, finished) or by querying model status directly.
5. Retrieve photos once a model reaches active status. Use the org-wide favorites endpoint to pull all selected headshots in one call.

Organization

GET  /organization          → org name, website, team list
GET  /organization/credits  → current credit balance

Invites

GET   /organization/invites           → all invites with status
POST  /organization/invites           → send a new invite
GET   /organization/invites/:email    → look up a specific invite
POST  /organization/invites/revoke    → revoke an invite and refund credits

Invite status flow: pending → accepted → uploading → generating → completed

Credits are refunded when you revoke an unused invite.

Team Members

GET  /organization/team              → all members (filterable by status)
GET  /organization/team/accepted     → signed up, haven't uploaded photos yet
GET  /organization/team/pending      → photos uploaded, headshots being generated
GET  /organization/team/finished     → headshots ready (includes photoCount, hasFavorite)

All list endpoints support limit and offset for pagination (max 200 per page).

Teams

GET     /organization/teams              → all teams
POST    /organization/teams              → create a team
PUT     /organization/teams/:teamId      → rename a team
DELETE  /organization/teams/:teamId      → delete a team
POST    /organization/teams/:teamId/members  → add existing members to a team

Deleting a team does not delete its members — they remain in the organization without a team assignment.

Models

Models represent individual AI headshot sessions. Each member who completes onboarding has one model.

GET     /organization/models              → all models (filterable by status, teamId)
GET     /organization/models/:modelId     → single model details
DELETE  /organization/models/:modelId     → delete a model (irreversible)

Model status flow:

onboarding → waiting → pending → generatingHeadshots → active

Photos

Photo URLs are signed and expire after 24 hours. Fetch fresh URLs by calling the endpoint again.

GET   /organization/models/:modelId/photos               → all photos for a model
GET   /organization/models/:modelId/photos/favorite      → the member's selected favorite
GET   /organization/models/:modelId/photos/:photoId      → single photo with all URL variants
POST  /organization/models/:modelId/photos/download      → batch signed download URLs
GET   /organization/photos/favorites                     → all org favorites with member context

The include=all query parameter returns main, thumbnail, and original URL variants. Default is main only.

The organization favorites endpoint is designed for use cases like team directories, "Our Team" pages, and Slack/Teams profile syncing.

Webhooks

Instead of polling the models endpoint, configure a webhook URL in Admin Dashboard > API to receive push notifications when model events occur.

Webhooks are signed with HMAC-SHA256 using your webhook secret. Verify the X-HeadshotPro-Signature header on every incoming request. Failed deliveries retry up to 3 times; your endpoint must respond with HTTP 200 within 10 seconds.

Good to know

• All list endpoints support limit (default 50, max 200) and offset for cursor-style pagination.
• The POST /organization/models/:modelId/photos/download endpoint accepts an optional photoIds array — omit it to get download URLs for all photos on the model.
• Organization favorites (GET /organization/photos/favorites) supports filtering by teamId, making it straightforward to build per-team photo exports.
• There are no per-endpoint rate limits — all endpoints share the same 300 req/min pool (1,000 for Enterprise).

Related

• API Getting Started