Developers
Headshot Infrastructure for Your Tech Stack
Manage contacts, automate capture sessions, and receive finished headshots via webhook — all through the Scale Headshots REST API.
REST API
Build Headshots Into Your Workflow
The Scale Headshots API gives you programmatic access to manage contacts, create capture sessions, track submissions, and receive finished headshots via webhook — all from your existing systems.
- • Manage contacts with custom attributes and list assignments
- • Webhook notifications when headshots are ready
- • Cursor-based pagination for large teams
- • Bearer token authentication with long-lived API keys
- • Interactive Postman collection
// Create a contact
POST /api/v2/contacts
{
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@company.com",
"studio_ids": ["stu_abc123"]
}
// Create a capture session
POST /api/v2/studio_sessions
// Webhook: headshot ready
{
"topic": "SUBMISSION_COMPLETE",
"submission_id": "sub_xyz789"
}
Endpoints
REST API
The v2 API follows REST conventions with Bearer token authentication and cursor-based pagination. Every response is JSON.
Contacts
/api/v2/contacts List all contacts with filters and pagination
/api/v2/contacts Create a contact with custom attributes
/api/v2/contacts/:contact_id Retrieve a single contact
/api/v2/contacts/:contact_id Update contact details
Submissions
/api/v2/submissions List all submissions with pagination
/api/v2/submissions/:submission_id Retrieve a single submission
Studio Sessions
/api/v2/studio_sessions Generate a studio capture session
Integrations
Connect to the Tools You Already Use
HRIS & People Platforms
Use POST /api/v2/contacts to auto-create contacts when employees are onboarded. Attach custom_attributes for department and role. When the SUBMISSION_COMPLETE webhook fires, sync the finished headshot back to Workday, BambooHR, or Rippling.
CRM Systems
Keep contact photos current in Salesforce, HubSpot, or any CRM. Use list_ids to organize contacts by team or region, and listen for SUBMISSION_COMPLETE to push new headshots into contact records automatically.
Badge & ID Systems
When a headshot clears AI enhancement, the SUBMISSION_COMPLETE webhook delivers the final image. Feed it directly to badge printers, ID card systems, or access control platforms — no manual downloads.
Intranet & Internal Tools
Use GET /api/v2/submissions with cursor pagination to bulk-sync headshots to company directories, org charts, and communication tools. Filter by studio_id to keep everything organized.
Webhooks
Real-Time Event Notifications
Get notified instantly when a headshot is processed and ready for delivery. Set up webhooks in your admin portal and start automating downstream workflows.
Configure your webhook URL
Set up your endpoint in Account > Developers in the admin portal.
Team member captures a photo
AI enhancement begins automatically — background removal, lighting correction, and upscaling.
We POST to your URL
When processing completes, we send a SUBMISSION_COMPLETE event with the submission details.
Validate authenticity
Check the X-Authenticity-Token JWT header against the secret from your admin portal.
// SUBMISSION_COMPLETE webhook
POST https://your-app.com/webhooks
// Headers
X-Authenticity-Token: eyJhbG...
// Body
{
"topic": "SUBMISSION_COMPLETE",
"submission_id": "sub_xyz789",
"studio_id": "stu_abc123",
"contact_id": "ctn_def456"
}
Every webhook includes a signed JWT in the X-Authenticity-Token header. Validate it using the secret from your admin portal to ensure request authenticity.
Ready to integrate?
Start building headshot automation into your stack.