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/
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 '@' symbolteamId
(optional): Team ID to assign the user to a specific teamisDevelopment
(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 successfullymodelId
: Unique identifier for the AI modelstatus
: Current model state, set to "onboarding" indicating a new user flowisDevelopment
: (only present when true
) Indicates the model is running in development/test modesignedUrl
: Authentication URL for embedding in your iframeError Responses:
400
: Invalid email format400
: Insufficient credits404
: Organization not found404
: Team not found (when teamId is provided)400
: User with this email already existsRetrieves 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 retrieveResponse:
{
"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 successfullymodelId
: Unique identifier for the AI modelstatus
: Current model state (e.g., "active", "pending", "onboarding")isDevelopment
: (only present when true
) Indicates the model is running in development/test modesignedUrl
: Authentication URL for embedding in your iframeError Responses:
404
: Organization not found404
: Model not foundDeletes 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 deleteResponse:
{
"success": true,
"message": "Model deleted successfully",
"modelId": "MODEL_UNIQUE_ID"
}
Error Responses:
404
: Organization not found404
: Model not found400
: Model is already deletedNotes:
model.deleted
is triggered after successful deletionWhen 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 identifieruid
: Model UID for internal referencetitle
: Human-readable model titletrigger
: Selected gender for this modelstatus
: Current model status (see status values below)isDevelopment
: (only present when true
) Indicates the model is running in development/test mode with accelerated processingfinishedAt
: Timestamp when model processing completed (null if not finished)deletedAt
: Timestamp when model was deleted (null if not deleted)inviteExpiresAt
: Expiration timestamp for model accesscreatedAt
: Model creation timestamporganization
: Organization ID that owns the modelSupported Events:
model.created
: Triggered when a new whitelabel model is createdmodel.status.updated
: Triggered when a model's status changesmodel.deleted
: Triggered when a model is deletedModel Status Values:
onboarding
: User is completing the initial setupwaiting
: User completed onboarding, waiting for training to startpending
: Model is being trained on their photo'sgeneratingHeadshots
: Training finished, AI is generating headshotsactive
: Headshots are ready and availablefailed
: Training or generation failed (failed models will auto-restart)deleted
: Model has been deletedSigned URLs:
Credit Usage:
GET /model/get/:modelId
) does not consume creditsEmail Handling:
user+1@example.com
)Webhook Delivery: