API Documentation

API Reference

Authentication

Dr. Headshot uses API keys to allow access to the API. All API requests are scoped to a company account.

A unique API key can be generated by company account owners in the account settings. Once created, the API key will only be shown once, so make sure to store it securely.

Dr. Headshot 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.

Note: The API is available for team accounts. You can generate your API key in the account settings.

API Endpoints

All Dr. Headshot API endpoints start with https://api.drheadshot.com/v2/company-api

Get organization details

GET/v2/company-api/organization

{
  "_id": "507f1f77bcf86cd799439011",
  "companyName": "Acme Corporation",
  "email": "contact@acme.com",
  "website": "https://acme.com"
}

Check credits

GET/v2/company-api/credits

Returns the amount of available upload credits your organization has.

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

Invites a team member by email. An email will be sent to the provided email address with further instructions. You can provide a single email as a string, or multiple emails as an array. The email parameter can also accept comma, semicolon, or newline-separated values.

Request Body:

{
  "email": "user@example.com",
  "label": "Optional label"
}

Response:

{
  "success": true,
  "sent": 1,
  "failed": 0,
  "skipped": 0,
  "invites": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "code": "unique-invite-code",
      "created": 1642684800000,
      "updated": 1642684800000,
      "used": 0,
      "active": true,
      "maxUses": 1,
      "allowedEmails": [
        "user@example.com"
      ],
      "emailInvite": true,
      "inviteUrl": "https://drheadshot.com/app/create/step4?inviteID=unique-invite-code&email=user@example.com"
    }
  ]
}

Revoke an invite

DELETE/v2/company-api/invites/:email

Revokes an invite by email address. The email parameter should be URL-encoded in the path.

Response:

{
  "success": true,
  "message": "Invite revoked successfully"
}

Get all invites

GET/v2/company-api/invites

Gets all invites for the organization.

Response:

{
  "success": true,
  "invites": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "code": "unique-invite-code",
      "created": 1642684800000,
      "updated": 1642684800000,
      "used": 0,
      "maxUses": 1,
      "active": true,
      "allowedEmails": [
        "user@example.com"
      ],
      "label": "Optional label",
      "inviteUrl": "https://drheadshot.com/app/create/step4?inviteID=unique-invite-code&email=user@example.com"
    }
  ]
}

Get invite

GET/v2/company-api/invites/:id

Gets the details of a single invite by invite ID or code.

Response:

{
  "success": true,
  "invite": {
    "_id": "507f1f77bcf86cd799439011",
    "code": "unique-invite-code",
    "created": 1642684800000,
    "updated": 1642684800000,
    "used": 0,
    "maxUses": 1,
    "active": true,
    "allowedEmails": [
      "user@example.com"
    ],
    "label": "Optional label",
    "inviteUrl": "https://drheadshot.com/app/create/step4?inviteID=unique-invite-code&email=user@example.com"
  }
}

Get all photoshoots

GET/v2/company-api/photoshoots?status=pending

Gets all models (photoshoots) for the company account. Optional query parameter status can be set to pending or done to filter results.

Response:

{
  "success": true,
  "photoshoots": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "John Doe",
      "credits": 5,
      "gender": "male",
      "created": 1642684800000,
      "inviteID": "507f1f77bcf86cd799439012"
    }
  ]
}

Get images from photoshoot

GET/v2/company-api/photoshoots/:modelID/images?favorite=1

Gets images for a specific model (photoshoot). Optional query parameter favorite=1 can be used to filter only favorite images.

Response:

{
  "success": true,
  "images": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "original": "https://storage.googleapis.com/drheadshot/images/image.jpg",
      "preview": "https://storage.googleapis.com/drheadshot/images/preview-image.jpg",
      "favorite": 1,
      "ts": 1642684800000
    }
  ]
}