API Reference

HeadshotPro uses API keys to allow access to the API.

All API requests on HeadshotPro are scoped to an Organization. A unique API key can be generated by Team Owners at www.headshotpro.com/app/admin/api.

HeadshotPro expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer API_KEY

All request bodies need to be valid JSON

All HeadshotPro endpoints start with https://server.headshotpro.com/api/v1/

GET: https://server.headshotpro.com/api/v1/organization

Response:

{
    "success": true,
    "organization": {
        "uid": "UNIQUE_ID",
        "name": "Organization Name",
        "website": "https://organization.com",
        "teams": [
            {
                "name": "Team Name",
                "id": "TEAM_UNIQUE_ID"
            }
        ]
    }
}

Returns the amount of available credits your organization has.

GET: https://server.headshotpro.com/api/v1/organization/credits

Response:

{
    "success": true,
    "credits": 100
}

Consumes a credit to invite a team member. An email will be send to the email with further instructions.

POST: https://server.headshotpro.com/api/v1/organization/invite

Request Body:

{
  "email": "USER_EMAIL"
}

Or, if you want to invite a team member to a specific team:

{
  "email": "USER_EMAIL",
  "teamId": "TEAM_ID"
}

Response:

{
  "success": true,
  "input": {
    "email": "EMAIL_ADDRESS"
  },
  "message": "Invite sent",
  "link": "https://www.headshotpro.com/auth/signup?invite=[UNIQUE_ID]",
  "id": "[UNIQUE_ID]",
  "teamId": "TEAM_ID"
}

(Credits are only consumed when a a team member uploads their photos)

POST: https://server.headshotpro.com/api/v1/organization/invite/revoke

Request Body:

{
  "email": "USER_EMAIL"
}

Response:

{
    "success": true,
    "message": "Invite revoked",
    "input": {
        "email": "USER_EMAIL"
    }
}

Gets all invites for the organization

GET: https://server.headshotpro.com/api/v1/organization/invites

Response:

{
  "success": true,
  "invites": [
    {
      "id": "UNIQUE_ID",
      "email": "user1@example.com",
      "valid": true,
      "teamId": "TEAM_ID",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "used": false,
      "link": "https://www.headshotpro.com/auth/signup?invite=UNIQUE_ID"
    },
    {
      "id": "UNIQUE_ID_2",
      "email": "user2@example.com",
      "valid": false,
      "teamId": "TEAM_ID",
      "createdAt": "2024-01-10T14:20:00.000Z",
      "used": true,
      "link": "https://www.headshotpro.com/auth/signup?invite=UNIQUE_ID_2"
    }
  ]
}

Gets the details of an invite

GET: https://server.headshotpro.com/api/v1/organization/invite/id/[UNIQUE_ID]

Response:

{
  "success": true,
  "invite": {
    "email": "email@address.com",
    "status": "pending-invite",
    "teamId": "TEAM_ID"
  }
}

status could be either of the following: 'pending-invite', 'revoked', 'waiting-for-upload', 'active', 'generating-headshots', 'deleted'

If user has used the invite, the returned email in the response will be their active email, not the email that you used to invite them.

Creates a new team within your organization.

POST: https://server.headshotpro.com/api/v1/organization/teams

Request Body:

{
  "name": "Team Name"
}

Response:

{
  "success": true,
  "organization": {
    "uid": "UNIQUE_ID",
    "name": "Organization Name",
    "description": "Organization Description",
    "website": "https://organization.com",
    "teams": [
      {
        "name": "Team Name",
        "id": "TEAM_UNIQUE_ID"
      }
    ]
  }
}

Updates the name of an existing team.

PUT: https://server.headshotpro.com/api/v1/organization/teams/[TEAM_ID]

Request Body:

{
  "name": "Updated Team Name"
}

Response:

{
  "success": true,
  "organization": {
    "uid": "UNIQUE_ID",
    "name": "Organization Name",
    "description": "Organization Description",
    "website": "https://organization.com",
    "teams": [
      {
        "name": "Updated Team Name",
        "id": "TEAM_UNIQUE_ID"
      }
    ]
  }
}

Deletes a team and removes all team members from it. The users will not be removed and will still belong to your organization, but they will have no team assigned to them.

DELETE: https://server.headshotpro.com/api/v1/organization/teams/[TEAM_ID]

Response:

{
  "success": true,
  "organization": {
    "uid": "UNIQUE_ID",
    "name": "Organization Name",
    "description": "Organization Description",
    "website": "https://organization.com",
    "teams": [
      {
        "name": "Other Team Name",
        "id": "TEAM_UNIQUE_ID"
      }
    ]
  }
}

Adds existing organization members to a specific team. You can add multiple members at once, but they must already be part of your organization.

POST: https://server.headshotpro.com/api/v1/organization/teams/[TEAM_ID]/add-members

Request Body:

{
  "emails": ["user1@example.com", "user2@example.com"]
}

Response:

{
  "success": true,
  "organization": {
    "uid": "UNIQUE_ID",
    "name": "Organization Name",
    "description": "Organization Description",
    "website": "https://organization.com",
    "teams": [
      {
        "name": "Team Name",
        "id": "TEAM_UNIQUE_ID"
      }
    ]
  }
}

The Whitelabel API allows you to create and manage anonymous users and models for seamless integration with your own application. This is useful for embedding HeadshotPro functionality directly into your product without requiring users to create accounts on HeadshotPro.

All whitelabel endpoints start with https://server.headshotpro.com/api/v2/organization/whitelabel/

• Your organization must have the whitelabel feature enabled

• A valid webhook URL must be configured in your organization settings

• Sufficient credits in your organization account

Creates an anonymous user and model for whitelabel integration. This endpoint consumes a credit and generates a signed URL that allows the user to access the HeadshotPro interface without creating an account.

POST: https://server.headshotpro.com/api/v2/organization/whitelabel/model/create

Request Body:

{
  "email": "user@example.com",
  "teamId": "TEAM_ID",
  "isDevelopment": false
}

Parameters:

• email (required): Valid email address for the user. Must contain '@' symbol

• teamId (optional): Team ID to assign the user to a specific team

• isDevelopment (optional): Boolean flag for fast testing mode. When set to true, enables accelerated processing using test data instead of actual training and generation. This reduces processing time from ~1 hour to ~3 minutes at zero cost and credit consumption. Default: false

Response:

{
  "success": true,
  "modelId": "MODEL_UNIQUE_ID",
  "status": "onboarding",
  "isDevelopment": false,
  "signedUrl": "https://www.yourproheadshots.com/auth/social?token=AUTH_TOKEN&anonymous=1"
}

Return Values:

• success: Boolean indicating the operation completed successfully

• modelId: Unique identifier for the AI model

• status: Current model state, set to "onboarding" indicating a new user flow

• isDevelopment: (only present when true) Indicates the model is running in development/test mode

• signedUrl: Authentication URL for embedding in your iframe

Error Responses:

• 400: Invalid email format

• 400: Insufficient credits

• 404: Organization not found

• 404: Team not found (when teamId is provided)

• 400: User with this email already exists

Retrieves details for an existing whitelabel model and generates a new signed URL for user access.

GET: https://server.headshotpro.com/api/v2/organization/whitelabel/model/get/[MODEL_ID]

Parameters:

• MODEL_ID (URL parameter): The model ID to retrieve

Response:

{
  "success": true,
  "modelId": "MODEL_UNIQUE_ID",
  "status": "active",
  "isDevelopment": true,
  "signedUrl": "https://www.yourproheadshots.com/auth/social?token=AUTH_TOKEN&anonymous=1"
}

Return Values:

• success: Boolean indicating the operation completed successfully

• modelId: Unique identifier for the AI model

• status: Current model state (e.g., "active", "pending", "onboarding")

• isDevelopment: (only present when true) Indicates the model is running in development/test mode

• signedUrl: Authentication URL for embedding in your iframe

Error Responses:

• 404: Organization not found

• 404: Model not found

Deletes a whitelabel model and removes the associated anonymous user. This operation marks the model as deleted and cleans up related resources.

DELETE: https://server.headshotpro.com/api/v2/organization/whitelabel/model/delete/[MODEL_ID]

Parameters:

• MODEL_ID (URL parameter): The model ID to delete

Response:

{
  "success": true,
  "message": "Model deleted successfully",
  "modelId": "MODEL_UNIQUE_ID"
}

Error Responses:

• 404: Organization not found

• 404: Model not found

• 400: Model is already deleted

Notes:

• Associated anonymous users and model are permanently deleted from the database

• A webhook event model.deleted is triggered after successful deletion

When whitelabel models are created or updated, HeadshotPro will send webhook notifications to your configured webhook URL. Configure your webhook URL in your organization settings.

Webhook Payload Structure:

{
  "event": "model.created",
  "objectType": "model",
  "object": {
    "_id": "MODEL_ID",
    "uid": "MODEL_UID",
    "title": "Model Title",
    "trigger": "male",
    "status": "onboarding",
    "isDevelopment": true,
    "finishedAt": null,
    "deletedAt": null,
    "inviteExpiresAt": "2024-12-31T23:59:59.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "organization": "ORGANIZATION_ID"
  }
}

Object Parameters:

• _id: Unique model identifier

• uid: Model UID for internal reference

• title: Human-readable model title

• trigger: Selected gender for this model

• status: Current model status (see status values below)

• isDevelopment: (only present when true) Indicates the model is running in development/test mode with accelerated processing

• finishedAt: Timestamp when model processing completed (null if not finished)

• deletedAt: Timestamp when model was deleted (null if not deleted)

• inviteExpiresAt: Expiration timestamp for model access

• createdAt: Model creation timestamp

• organization: Organization ID that owns the model

Supported Events:

• model.created: Triggered when a new whitelabel model is created

• model.status.updated: Triggered when a model's status changes

• model.deleted: Triggered when a model is deleted

Model Status Values:

• onboarding: User is completing the initial setup

• waiting: User completed onboarding, waiting for training to start

• pending: Model is being trained on their photo's

• generatingHeadshots: Training finished, AI is generating headshots

• active: Headshots are ready and available

• failed: Training or generation failed (failed models will auto-restart)

• deleted: Model has been deleted

Signed URLs:

• Generated signed URLs are temporary and provide direct access to the HeadshotPro interface

• Users can upload photos, view their headshots, and manage their model through this URL

• No HeadshotPro account creation is required

Credit Usage:

• One credit is consumed when user submits their photo's an finished the onboarding.

• Credits are only consumed upon successful model creation, not when creating a new model

• Getting an existing model (GET /model/get/:modelId) does not consume credits

Email Handling:

• If a user with the provided email already exists, the API will return an error

• To work around this, you can append a unique identifier to the email (e.g., user+1@example.com)

Webhook Delivery:

• Webhooks are delivered with a 5-second delay and up to 3 retry attempts

• Failed webhooks are logged for debugging purposes

• Webhook URLs must respond with HTTP 200 status code for successful delivery