Invites

Endpoints for inviting team members to create their AI headshots.

List All Invites

Returns all invitations in your organization, including pending and completed invites.

GET /organization/invites

Request

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

Response

{
  "success": true,
  "invites": [
    {
      "email": "john@example.com",
      "status": "completed",
      "modelId": "507f1f77bcf86cd799439011",
      "teamId": "team_xyz789",
      "teamName": "Marketing",
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "email": "jane@example.com",
      "status": "pending",
      "teamId": null,
      "teamName": null,
      "createdAt": "2024-01-14T09:00:00.000Z"
    }
  ]
}

Invite Status Values

Status	Description
`pending`	Invite sent, user hasn't signed up yet
`accepted`	User signed up but hasn't uploaded photos
`revoked`	Invite was revoked
`uploading`	User is in the onboarding/upload process
`generating`	AI is generating headshots
`completed`	Headshots are ready
`deleted`	User/model was deleted

Create Invite

Send an invitation to a team member. An email will be sent with instructions to complete their AI headshot session.

POST /organization/invites

Request Body

Field	Type	Required	Description
`email`	string	Yes	Email address to invite
`teamId`	string	No	Team ID to assign the user to

Request

curl -X POST "https://server.headshotpro.com/api/v2/organization/invites" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "teamId": "team_xyz789"
  }'

Response

{
  "success": true,
  "input": {
    "email": "user@example.com"
  },
  "message": "Invite sent",
  "link": "https://www.headshotpro.com/auth/signup?invite=abc123",
  "id": "abc123",
  "teamId": "team_xyz789"
}

Notes

Credits are consumed when the user uploads photos, not when the invite is created
Invite links expire after 30 days
Duplicate invites to the same email are rejected
Spam protection: Pending invites are capped at credits × 2 to prevent abuse

Error Responses

Status	Code	Description
400	`INVALID_REQUEST`	Invalid email format
400	`INVALID_REQUEST`	User with this email already invited
402	`INSUFFICIENT_CREDITS`	Not enough credits
404	`NOT_FOUND`	Team not found
429	`INVITE_LIMIT_EXCEEDED`	Too many pending invites

Get Invite by Email

Check the status of an invitation for a specific email address.

GET /organization/invites/:email

Request

curl -X GET "https://server.headshotpro.com/api/v2/organization/invites/user@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "invite": {
    "email": "user@example.com",
    "status": "uploading",
    "modelId": "507f1f77bcf86cd799439011",
    "teamId": "team_xyz789"
  }
}

Revoke Invite

Revokes an invitation and deletes associated anonymous users and models.

POST /organization/invites/revoke

Request Body

Field	Type	Required	Description
`email`	string	Yes	Email address of invite to revoke

Request

curl -X POST "https://server.headshotpro.com/api/v2/organization/invites/revoke" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

Response

{
  "success": true,
  "message": "Invite revoked",
  "input": {
    "email": "user@example.com"
  }
}

Notes

Revoking deletes both the invite and any associated model
Credits are refunded for unused invites
This action cannot be undone