API Getting Started

The HeadshotPro API gives team admins and developers programmatic control over their organization's headshot workflow. You can invite members, manage teams, monitor progress, and retrieve generated photos — all without touching the dashboard.

The API follows REST conventions. Every request requires a Bearer token, and every response returns a consistent JSON envelope with a success boolean.

How it works

1. Log in as a Team Owner or Admin and go to Admin Dashboard > API.
2. Click Generate API Key. The key is displayed once — copy it immediately and store it securely.
3. Include the key in the Authorization header on every request:

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

4. Check the success field in every response before processing data.

{
  "success": true,
  "data": { ... }
}

If success is false, the response includes error (human-readable message) and code (machine-readable constant).

Authentication

All V2 endpoints sit under https://server.headshotpro.com/api/v2/organization/... and require the Authorization: Bearer <key> header.

API keys are scoped to your organization. Every action performed with a key is attributed to that organization and subject to its plan limits.

Security rules:

• Never use the API key in client-side or browser code — keep it server-side only.
• Store the key in an environment variable, not in source code.
• If a key is compromised, delete it in Admin Dashboard > API and generate a new one. The old key is invalidated immediately.

Rate limits

Every response includes rate limit headers:

When the limit is exceeded, the API returns HTTP 429 with code RATE_LIMIT_EXCEEDED. Wait until X-RateLimit-Reset, then retry.

Invite spam protection — in addition to the per-minute rate limit, the number of pending invites is capped at credits × 2. For example, 10 credits allows at most 20 pending invites. Invites count as pending until the user completes their headshot session. Revoke unused invites with POST /organization/invites/revoke to free up capacity.

Good to know

• V2 is the current API version. V1 endpoints remain available for backwards compatibility but new integrations should use V2.
• API keys are organization-scoped — one key covers all teams and members within the organization.
• Deleting and regenerating a key immediately invalidates the previous key. Update all dependent systems before rotating.
• Enterprise rate limit upgrades are available — contact sales@headshotpro.com.
• For event-driven workflows, configure a webhook URL in the same API settings page to avoid polling. See Webhooks.

Related

• API Overview