Overview

Spark Hire is a video interviewing platform. Take a look at our tour page to get a quick idea of what Spark Hire does.

Our API allows you to integrate video interviewing into your own applications or existing applicant tracking system. You can create users, jobs, interviews,and more.

The Spark Hire API is a RESTful API. All responses are JSON.

Base URL

All API resources listed in this document should be prefixed with https://api.sparkhire.com/v1.0.

Depending on what you are trying to do, the HTTP methods GET, POST, PUT, or DELETE are used. Not all resources support all HTTP methods.

Authentication

In order to make any requests to the API, you must have a current Spark Hire account and have API access enabled for your account. If you need us to enable API access for you, get in touch.

Once you have been granted access you can generate an API key. Each key is tied to a specific user. Anything that user can see via the website will be available via their API key. If a user is not allowed to access a specific interview, it will not appear in any API requests. If a user is disabled, their API keys are also disabled.

Authentication works via HTTP basic auth. The username should be set as the value of the API key, and the password is ignored.

Important: When developing an integration, please ensure that you are using API keys on the user level. Do not use a single API key for all users as this impacts permissions, email notifications, and audit logs for support. 

GET /resource HTTP/1.1
Content-Type: application/json
Authorization: Basic eW91ciBhcGkga2V5Ong=
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": "stuff"
}

Rate Limiting

Requests are rate limited to ensure the best possible performance of our API. When the rate limit is reached, you will receive a 429 response with a header that tells you how many seconds remain until the limit resets.

Our API implements a rate limit of 400 requests / 1 minute.

This allows for a certain level of burst throughput, but will return the error response after that.

Header Description
X-Rate-Limit-Try-Again-Seconds Number of seconds remaining until the rate limit resets
Warning: We implement other levels of rate limiting in order to further protect the resiliancy of our web application. While we try to keep these responses consistent, the header may not always be present. 
GET /resource HTTP/1.1
Content-Type: application/json
Authorization: Basic eW91ciBhcGkga2V5Ong=
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
Retry-After: 45

{
  "reason": "Too Many Requests",
  "code": "api.too_many_requests"
}

Dates and Timestamps

All dates are returned in the RFC3339 format.

Errors

Whenever an error occurs we will try to return a meaningful error message along with the correct HTTP response code.

These are the HTTP response codes we return most often.

Error messages are always in English, but a lang key is provided to simplify localization in your app.

Code Text Description
200 OK Success!
201 Created New job post, interview, or whatever created.
204 No Content When an action has been performed successfully, but there's nothing to return.
400 Bad Request The request was invalid. An accompanying error message will explain why.
402 Payment Required The request was valid, but cannot be completed until a payment is made.
401 Unauthorized Authentication credentials were missing or incorrect.
403 Forbidden The request is understood, but it has been refused or access is not allowed. The error message will explain why.
405 Method Not Allowed Likely trying to do a PUT or POST to a resource that doesn't support it.
410 Gone This resource is gone. Used to indicate that an API endpoint has been turned off.
500 Internal Server Error Something is broken.
503 Service Unavailable Servers are up, but overloaded with requests. Try again later. 
GET /users HTTP/1.1
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "reason": "You must authenticate to access the API.",
  "code": "api.key_not_set"
}

List Querying

Some lists allow you to pass an optional url query string parameters to help you sort and filter the returned items.

The query string parameters vary between arrays and single values.

If the list supports querying, the various keys and values will be documented in that section. 

GET /interviews?status[]=one_way&range=1-20&orderby=scheduled_desc HTTP/1.1
HTTP/1.1 401 Unauthorized
Content-Type: application/json

Webhooks

Instead of polling the API to look for changes to job posts and interviews, use webhooks. We will notify your server when a change has taken place by POSTing the changed object to your server at the given URL.

For testing, developing, and troubleshooting your webhooks, you may find it easier to use the settings UI:

Webhook management console »

Failing Webhooks

It's important to ensure your webhooks are working and unused ones are cleaned up. Webhooks that fail 15 or more times over 48 hours will be marked as "failing". If the webhooks continue to fail for another 72 hours, they may be automatically disabled.

Replaying a Webhook

To replay a webhook hit the following URL with your webhook Event type to replay the last webhook to your server again. 

GET /webhooks/replay/:event HTTP/1.1
Content-Type: application/json
HTTP/1.1 204 No Content

Receiving Webhooks

In order for webhooks to work, your server needs to be accessible from the internet. We also highly recommend using SSL so payloads will be encrypted over HTTPS.

The following webhook headers will be sent to help you differentiate between event and payload types.

Name Description
X-SparkHire-Event The event type that was triggered
X-SparkHire-Payload The type of the payload. It will be a single job, user, interview, or job post object.
X-SparkHire-User-UUID The UUID of the user that own's the webhook. All data will be sent using this users permissions.
X-SparkHire-Webhook-UUID The UUID of the webhook that caused the webhook to be sent

Webhook Event Types

When we POST a payload to your webhook URL, a header is passed stating the type of event that took place.

Event Type Payload Type Description
InterviewCreated Interview When a new interview has been created.
InterviewAccepted Interview When a job seeker accepts an interview.
InterviewDeleted Interview When an interview is deleted by a company user.
InterviewCompleted Interview When a job seeker completes an interview.
InterviewExpired Interview When an interview deadline passes and the job seeker has not completed it.
InterviewRescheduled Interview When an interview is rescheduled.
InterviewReset Interview When an interview is reset by customer support.
JobCreated Job When a new job has been created.
JobDeleted Job When a job post has been deleted.
JobUpdated Job When a job post has been updated.
InterviewRated Rating When a interview has been rated.

List Webhooks

GET /webhooks

This will pull a list of all of your webhooks.

Property Description
uuid The webhook UUID
description A short description of the webhook
url The URL we hit when a change has occurred
http_auth true or false if the call uses HTTP basic auth, or not 
GET /webhooks HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "173dbaad-a0a2-4ce7-afaa-efba38c23bc0",
    "description": "My first webhook",
    "url": "http://yourdomain.com/sparkhire/webhook",
    "http_auth": false
  },
  {
    "uuid": "0e177569-3a20-4160-84b5-fa451a952b30",
    "description": "Some other webhook",
    "url": "https://otherdomain.com/hook",
    "http_auth": true
  }
]

Creating a webhook

POST /webhooks

This will create a new webhook.

Property Description Required
description A short description of the webhook
✓
url The URL we hit when a change has occurred
✓
http_auth If you want us to hit your server using HTTP basic auth. Formatted like username:password
-
 
POST /webhooks HTTP/1.1
Content-Type: application/json

{
  "description": "My newly created webhook",
  "url": "http://yourdomain.com/sparkhire/webhook",
  "http_auth": "username:password"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "6ec2fd66-6fdf-4e1c-a27b-4759c92332ae",
  "description": "My newly created webhook",
  "url": "http://yourdomain.com/sparkhire/webhook",
  "http_auth": true
}

Deleting a webhook

DELETE /webhooks/:uuid

This will remove the webhook and stop notifying your server. 

DELETE /webhooks/:uuid HTTP/1.1
HTTP/1.1 204 No Content

Me

This route allows you to grab basic information on your current user. It is useful for debugging unauthorized responses from the API.

Get current user

GET /me

Property Description
name Your user name.
email Your user email address.
avatar Your user avatar url.
type Your user type. Either 'company_user' or 'job_seeker'.
company A basic company object or null. 
GET /plan HTTP/1.1
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
  "name": "Company User",
  "email": "example@company.com",
  "avatar": "https://cdn.example.com/avatar.png",
  "type": "company_user",
  "company": {
    "uuid": "b902fc6f-08ff-11e3-b8f7-22000aaa0152",
    "name": "Shermer Staffing",
    "avatar": "https://cdn.example.com/avatar.png"
    "plan": {
      "name": "gold",
      "started_at": "2024-12-21T17:11:02+00:00",
      "renews_at": "2025-01-20T17:11:02+00:00",
      "jobs": {
        "remaining": -1,
        "limit": -1
      },
      "users": {
        "remaining": 0,
        "limit": 10,
        "paid": 0
      },
      "downgrades_to": {
        "name": "bronze",
        "at": "2015-12-25T14:21:30+00:00"
      }
    }
  }
}

Plan

Endpoints for modifying the plan your company is currently on. Upgrading will take place immediately and charge the card on file. Downgrading happens at the end of the billing period. If you are invoiced or don't have a current card on file 40x headers will be returned.

Get the company plan information

GET /plan

Property Description
name The name of the plan you are currently on.
renews The date when the billing period ends.
downgrades_to The plan you will switch to at the end of the billing period. Only here if you've downgraded.
jobs The number of job posts remaining and the monthly limit based on your plan. -1 means infinite.
users The number of user slots remaining, the monthly limit based on your plan, and the number of extra slots you've paid for. -1 means infinite.
features The features and whether they are enabled based on your plan. 
GET /plan HTTP/1.1
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "plan": {
    "name": "gold",
    "started_at": "2024-12-21T17:11:02+00:00",
    "renews_at": "2025-01-20T17:11:02+00:00",
    "jobs": {
      "remaining": -1,
      "limit": -1
    },
    "users": {
      "remaining": 0,
      "limit": 10,
      "paid": 0
    },
    "downgrades_to": {
      "name": "bronze",
      "at": "2015-12-25T14:21:30+00:00"
    },
    "features": {
      "advanced_share_links": true,
      "interview_sms_notifications": false
    }
  }
}

Companies

The companies resource allows you to access your company information that's in Spark Hire. This information is read only in the API. To modify it for your company, log in to Spark Hire and edit your company profile.

Get information about a company

GET /companies/:uuid

Property Description
uuid The company UUID.
name The name of the company.
website The company website.
summary The summary from the company profile page in Spark Hire
avatar The company avatar url.
horizontal_log The company logo url.
social An object of social profile links
location The company's headquarters
video A video object oh youtube embed information
industry A video object oh youtube embed information 
GET /companies/:uuid HTTP/1.1
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "b902fc7f-09ff-11e3-b8f7-22000aaa0152",
  "name": "Shermer Staffing",
  "website": "http://example.com",
  "summary": "Shermer's Best Staffing Company",
  "created_at": "2024-12-06T17:11:02+00:00",
  "updated_at": "2024-12-06T17:11:02+00:00",
  "avatar": "https://cdn.example.com/avatar.png",
  "horizontal_logo": "https://cdn.example.com/logo.png",
  "social": {
    "facebook": "http://facebook.com",
    "twitter": "http://twitter.com",
    "youtube": "http://www.youtube.com",
    "gplus": "http://google.com",
    "pintrest": "http://pinterest.com",
    "rss": "http://blog.example.com"
  },
  "location": {
    "uuid": "5320d1f4-f187-11e3-a0a0-080027880ca6",
    "formatted_address": "Chicago, IL, USA",
    "google_place_id": "CrIJW4QVCddrD4gR0wYydByPhXM"
  },
  "video": {
    "url": "https://www.youtube.com/watch?v=Wyoghwfsge04",
    "mobile": "https://m.youtube.com/details?v=Wyoghwfsge04",
    "embed": "https://www.youtube.com/embed/Wyoghwfsge04",
    "thumbnail": "https://img.youtube.com/vi/Wyoghwfsge04/hqdefault.jpg"
  },
  "industry": {
    "uuid": "686eb7b3-077c-11e4-9074-0a081ad58bf5",
    "name": "Accounting"
  }
}

Company Users

Company users are the users which can log in to your company account on SparkHire.com. Via the API you can create, delete, and modify company users.

List Company Users

GET /users

This resource returns an array of company user objects.

See getting a company user for an explanation of the data returned for each user. 

GET /users HTTP/1.1
HTTP/1.1 200 OK
  Content-Type: application/json

  [
    {
      "uuid": "81e92110-d935-11e2-bdd9-080027733f26",
      "active": true,
      "name": "Calvin Shelton",
      "email": "calvin.shelton@example.com",
      "avatar": "https://cdn.example.com/avatar.png",
      "created_at": "2024-12-06T17:11:02+00:00",
      "updated_at": "2024-12-12T17:11:02+00:00",
      "company": {
        "uuid": "0d2de946-fe53-11e2-ab8f-12313d03fec7",
        "name": "Shermer Staffing",
        "avatar": "https://cdn.example.com/avatar.png"
      }
    }
  ]

Create a Company User

POST /users

You must be using an API key for a user who is an admin on the account to create company users.

When you create a new company user an email is sent to the email provided asking them to click a link to set their password and complete creating their user.

Some plan types charge for additional users.

Property Description Required
name The full name of the user
✓
email The new user’s email address
✓
role The new user’s role can be administrator or standard
✓
 
POST /users HTTP/1.1
Content-Type: application/json

{
  "name": "Calvin Shelton",
  "email": "calvin.shelton@example.com",
  "role": "standard"
}
HTTP/1.1 201 Created
Content-Type: application/json

{
  "uuid": "81e92110-d935-11e2-bdd9-080027733f26",
  "active": true,
  "name": "Calvin Shelton",
  "role": "standard",
  "email": "calvin.shelton@example.com",
  "avatar": "https://cdn.example.com/avatar.png",
  "created_at": "2024-12-06T17:11:02+00:00",
  "updated_at": "2024-12-12T17:11:02+00:00",
  "company": {
    "uuid": "0d2de946-fe53-11e2-ab8f-12313d03fec7",
    "name": "Shermer Staffing",
    "avatar": "https://cdn.example.com/avatar.png"
  }
}

Get a Company User

GET /users/:uuid

Get an individual company user.

Name Description
uuid The users UUID
active Boolean, if the user is active or not
name The users full name
email The users email address
avatar The URL for the users avatar. If the user does not have one, a default is provided.
company Company data for the company that the user belongs to
created_at The timestamp for when the user was created
updated_at The timestamp for when the user was last modified 
GET /users/:uuid HTTP/1.1
HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "uuid": "81e92110-d935-11e2-bdd9-080027733f26",
    "active": true,
    "name": "Calvin Shelton",
    "email": "calvin.shelton@example.com",
    "avatar": "https://cdn.example.com/avatar.png",
    "company": {
      "uuid": "0d2de946-fe53-11e2-ab8f-12313d03fec7",
      "name": "Shermer Staffing",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "created_at": "2024-12-06T17:11:02+00:00",
    "updated_at": "2024-12-12T17:11:02+00:00"
  }

Update a Company User

PUT /users/:uuid

Only a company admin, or the user themself can update a company user object.

You can only update the name and email of the user. Other changes have to be done on the Spark Hire website.

Property Description Required
name The full name of the user
-
 
PUT /users/:uuid HTTP/1.1
  Content-Type: application/json

  {
    "name": "Calvin Shelton",
  }
HTTP/1.1 201 Created
  Content-Type: application/json

  {
    "uuid": "81e92110-d935-11e2-bdd9-080027733f26",
    "active": true,
    "name": "Calvin Shelton",
    "email": "calvin.shelton@example.com",
    "avatar": "https://cdn.example.com/avatar.png",
    "created_at": "2024-12-06T17:11:02+00:00",
    "updated_at": "2024-12-12T17:11:02+00:00",
    "company": {
      "uuid": "0d2de946-fe53-11e2-ab8f-12313d03fec7",
      "name": "Shermer Staffing",
      "avatar": "https://cdn.example.com/avatar.png"
    }
  }

Delete a Company User

DELETE /users/:uuid

You must be using the API key from an account admin to delete company users.

The user will be unable to log in, and any API keys they have will stop working. 

DELETE /users/:uuid HTTP/1.1
HTTP/1.1 204 No Content

User API Key

This endpoint allows administrators to view, create, delete, and modify company user API keys for custom Integrations.

Create a User API key

POST /users/:uuid/integration_key

You must be using an API key for a user who is an admin on the account and have a custom Integration to create User API Keys. 

POST /users/:uuid/integration_key HTTP/1.1
Content-Type: application/json
HTTP/1.1 201 Created
Content-Type: application/json

{
    "key": "efea030e-377b-4ee8-ad72-31a1cfc56d77",
    "description": "Description",
    "type": "external",
    "last_used_at": "2024-12-19T17:11:02+00:00",
    "created_at": "2024-12-06T17:11:02+00:00",
    "updated_at": "2024-12-12T17:11:02+00:00",
    "user": {
        "uuid": "81e92110-d935-11e2-bdd9-080027733f26",
        "email": "calvin.shelton@example.com",
        "name": "Calvin Shelton",
         "avatar": "https://cdn.example.com/avatar.png",
    }
}

Get a User API key

GET /users/:uuid/integration_key

Get an individual company user API key

Name Description
key The users API Key
description The description of the API Key
type The type of the API Key
last_used_at The timestamp for when the API key was last used
created_at The timestamp for when the API key was created
updated_at The timestamp for when the API key was last modified
uuid The users UUID
email The users email address
name The users full name
avatar The URL for the users avatar. If the user does not have one, a default is provided. 
GET users/:uuid/integration_key HTTP/1.1
HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "key": "efea030e-377b-4ee8-ad72-31a1cfc56d77",
    "description": "Description",
    "type": "external",
    "last_used_at": "2024-12-19T17:11:02+00:00",
    "created_at": "2024-12-06T17:11:02+00:00",
    "updated_at": "2024-12-12T17:11:02+00:00",
    "user": {
        "uuid": "81e92110-d935-11e2-bdd9-080027733f26",
        "email": "calvin.shelton@example.com",
        "name": "Calvin Shelton",
         "avatar": "https://cdn.example.com/avatar.png",
    }
}

Update a User API key

PUT /users/:uuid/integration_key

Only a company admin update a company user API key. 

PUT /users/:uuid/integration_key HTTP/1.1
  Content-Type: application/json

HTTP/1.1 201 Created
  Content-Type: application/json

  {
    "key": "efea030e-377b-4ee8-ad72-31a1cfc56d77",
    "description": "Description",
    "type": "external",
    "last_used_at": "2024-12-19T17:11:02+00:00",
    "created_at": "2024-12-06T17:11:02+00:00",
    "updated_at": "2024-12-12T17:11:02+00:00",
    "user": {
        "uuid": "81e92110-d935-11e2-bdd9-080027733f26",
        "email": "calvin.shelton@example.com",
        "name": "Calvin Shelton",
         "avatar": "https://cdn.example.com/avatar.png",
    }
}

Delete a User API key

DELETE users/:uuid/integration_key

You must be using the API key from an account admin to delete company users API Keys.

The user will be unable to use API key they have for the Integration. 

DELETE users/:uuid/integration_key HTTP/1.1
HTTP/1.1 204 No Content

Jobs

Before you can start interviewing, you need to create a job and activate it.

With a Spark Hire subscription you get a certain number of job slots that can be active at any given time. Setting a job to 'active' when creating or updating it uses one of your job slots. You can deactivate a job at any time by setting it's status to 'inactive', but candidates will no longer be able to complete their interviews. You can also create as many 'inactive' jobs as you want.

If you are developing something that will be creating job posts get in touch and we will hook you up with a way to test your code without having to burn job credits.

Get a list of job posts

GET /jobs

This resource returns an array of job objects.

See getting a job for an explanation of the data returned for each user.

Job List Querying

Key Possible Values
status[] active, inactive
orderby title_desc, title_asc, updated_desc, updated_asc, created_desc, created_asc, location_desc, location_asc
range 1-20, 10-30, 50-100 ...ect

Job List Query Example

Example
?orderby=title_desc&range=1-20&status[]=active 
GET /jobs HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "4939419c-930a-40df-b33c-256b7990f81d",
    "status": "active",
    "title": "Sr. Account Executive",
    "created_at": "2024-12-06T17:11:02+00:00",
    "updated_at": "2024-12-11T17:11:02+00:00",
    "status_updated_at": "2024-12-11T17:11:02+00:00",
    "created_by": {
      "uuid": "29fc66c4-f3d1-11e2-ab8f-12313d03fec7",
      "name": "Calvin Shelton",
      "email": "calvin.shelton@example.com",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "status_updated_by": {
      "uuid": "29fc66c4-f3d1-11e2-ab8f-12313d03fec7",
      "name": "Calvin Shelton",
      "email": "calvin.shelton@example.com",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "company": {
      "uuid": "39134c47-16b6-417b-af25-50d1627253db",
      "name": "Shermer Staffing",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "location": {
      "uuid": "5320d1f4-f187-11e3-a0a0-080027880ca6",
      "formatted_address": "Chicago, IL, USA",
    },
    "open_interview": {
      "uuid": "6b4027ef-e4c7-4e0b-9402-5180cb8a638f",
      "link": "http://hire.li/123465",
      "expires_at": "2025-01-20T17:11:02+00:00",
      "status": "active"
    }
  }
]

Get a Single Job Post

GET /jobs/:uuid

Name Description
uuid The users UUID
status Whether the job post is currently 'active' or 'inactive'
title The title of the job post
created_at The timestamp for when the job was created
updated_at The timestamp for when the job was last updated
status_updated_at The timestamp for when specificially the job status was last updated
description The job post description
created_by The company user who created the job post
status_updated_by The user who last changed the job status
company The company data for the company that created the job post
location The location data for where the job is
status The status of the job post
open_interview The open interview associated with this job post
job_video The job video api object associated with this job post 
GET /jobs/:uuid HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "4939419c-930a-40df-b33c-256b7990f81d",
  "status": "active",
  "title": "Sr. Account Executive",
  "created_at": "2024-12-06T17:11:02+00:00",
  "updated_at": "2024-12-11T17:11:02+00:00",
  "status_updated_at": "2024-12-11T17:11:02+00:00",
  "description": "The senior account executive.",
  "created_by": {
    "uuid": "29fc66c4-f3d1-11e2-ab8f-12313d03fec7",
    "name": "Calvin Shelton",
    "email": "calvin.shelton@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "status_updated_by": {
    "uuid": "29fc66c4-f3d1-11e2-ab8f-12313d03fec7",
    "name": "Calvin Shelton",
    "email": "calvin.shelton@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "company": {
    "uuid": "39134c47-16b6-417b-af25-50d1627253db",
    "name": "Shermer Staffing",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "location": {
    "uuid": "5320d1f4-f187-11e3-a0a0-080027880ca6",
    "formatted_address": "Chicago, IL, USA",
  },
  "open_interview": {
    "uuid": "6b4027ef-e4c7-4e0b-9402-5180cb8a638f",
    "link": "http://hire.li/123465",
    "expires_at": "2025-01-20T17:11:02+00:00",
    "status": "active",
    "questions": [
      {
        "uuid": "c9338fca-929f-4869-9246-6661526fa8f0",
        "time_limit": 120,
        "text": "Who do you want to work here?"
      },
      {
        "uuid": "d45a34e5-08da-44c8-8058-d6caeefa088a",
        "time_limit": 180,
        "text": "Describe your ideal work environment."
      }
    ]
  }
}

Create a new job post

POST /jobs

Below is a description of the data to post to the API to create a job post.

Property Description Required
location An object containing 'city', 'state', and 'country'
✓
title The job post title
✓
description The job post description
✓
status Set the job as currently 'active' or 'inactive'
✓

Create Job with Locality - Remote work mode

Example 

{
  "locality": {
    "work_mode": "remote",
    "work_place": ""
  },
  "title": ""Sr. Account Executive",
  "description": "The senior account executive.",
  "status": "active"
}

Create Job with Locality - On Site work mode

Example 

{
  "locality": {
    "work_mode": "on_site",
    "work_place": "Chicago, IL, USA"
  },
  "title": ""Sr. Account Executive",
  "description": "The senior account executive.",
  "status": "active"
}

Create Job with Locality - Hybrid work mode

Example 

{
  "locality": {
    "work_mode": "hybrid",
    "work_place": "Chicago, IL, USA"
  },
  "title": ""Sr. Account Executive",
  "description": "The senior account executive.",
  "status": "active"
}
 
POST /jobs HTTP/1.1
Content-Type: application/json

{
  "location": {
    "city": "Shermer",
    "state": "Illinois",
    "country": "United States"
  },
  "title": "Sr. Account Executive",
  "description": "The senior account executive.",
  "status": "active"
}
HTTP/1.1 201 Created
Content-Type: application/json

{
  "uuid": "4939419c-930a-40df-b33c-256b7990f81d",
  "status": "active",
  "title": "Sr. Account Executive",
  "created_at": "2024-12-06T17:11:02+00:00",
  "updated_at": "2024-12-11T17:11:02+00:00",
  "status_updated_at": "2024-12-11T17:11:02+00:00",
  "description": "The senior account executive.",
  "created_by": {
    "uuid": "29fc66c4-f3d1-11e2-ab8f-12313d03fec7",
    "name": "Calvin Shelton",
    "email": "calvin.shelton@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "status_updated_by": {
    "uuid": "29fc66c4-f3d1-11e2-ab8f-12313d03fec7",
    "name": "Calvin Shelton",
    "email": "calvin.shelton@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "company": {
    "uuid": "39134c47-16b6-417b-af25-50d1627253db",
    "name": "Shermer Staffing",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "location": {
    "uuid": "5320d1f4-f187-11e3-a0a0-080027880ca6",
    "formatted_address": "Chicago, IL, USA",
  }
}

Update a Job Post

PUT /jobs/:uuid

Below is a description of the data to post to the API to create a job post.

Property Description Required
location An object containing 'city', 'state', and 'country'.
-
title The job post title
-
description The job post description
-
status Set the job as currently 'active' or 'inactive'
-
 
PUT /jobs/:uuid HTTP/1.1
Content-Type: application/json

{
  "location": {
    "city": "Shermer",
    "state": "Illinois",
    "country": "United States"
  },
  "title": "Assistant to the Assistant Manager",
  "description": "The assistant to the assistant manager.",
  "status": "inactive"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "4939419c-930a-40df-b33c-256b7990f81d",
  "status": "inactive",
  "title": "Assistant to the Assistant Manager",
  "description": "The assistant to the assistant manager.",
  "created_at": "2024-12-06T17:11:02+00:00",
  "updated_at": "2024-12-11T17:11:02+00:00",
  "status_updated_at": "2024-12-11T17:11:02+00:00",
  "created_by": {
    "uuid": "29fc66c4-f3d1-11e2-ab8f-12313d03fec7",
    "name": "Calvin Shelton",
    "email": "calvin.shelton@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "status_updated_by": {
    "uuid": "29fc66c4-f3d1-11e2-ab8f-12313d03fec7",
    "name": "Calvin Shelton",
    "email": "calvin.shelton@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "company": {
    "uuid": "39134c47-16b6-417b-af25-50d1627253db",
    "name": "Shermer Staffing",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "location": {
    "uuid": "5320d1f4-f187-11e3-a0a0-080027880ca6",
    "formatted_address": "Shermer, IL, USA",
  },
  "open_interview": {
    "uuid": "6b4027ef-e4c7-4e0b-9402-5180cb8a638f",
    "link": "http://hire.li/123465",
    "expires_at": "2025-01-20T17:11:02+00:00",
    "status": "active",
    "questions": [
      {
        "uuid": "c9338fca-929f-4869-9246-6661526fa8f0",
        "time_limit": 120,
        "text": "Who do you want to work here?"
      },
      {
        "uuid": "d45a34e5-08da-44c8-8058-d6caeefa088a",
        "time_limit": 180,
        "text": "Describe your ideal work environment."
      }
    ]
  }
}

Delete a Job Post

DELETE /jobs/:uuid

This will delete a job post and set it to 'inactive'. 

DELETE /jobs/:uuid HTTP/1.1
HTTP/1.1 204 No Content

Interviews

When interviews are created, job seeker users are created and they are emailed instructions.

There are two types of interview. One-way, and Live.

Get a List of Interviews

GET /interviews

The amount of data returned is intimidating, but it's broken down in Getting a Single Interview.

Interview questions are not sent down here to decrease load. To get an interview's questions you have to load the interview by it's uuid.

Interview List Querying

Key Possible Values
type[] one_way and live
status[] accepted, requested, completed, expired, and canceled
range 1-20, 10-30, 50-100 ...ect
orderby scheduled_desc, scheduled_asc, completed_desc, completed_asc, updated_desc, updated_asc, candidate_desc, candidate_asc, company_desc, company_asc, job_desc, job_asc

Interview List Query Example

Example
?orderby=scheduled_desc&range=1-20&type[]=live&status[]=completed&status[]=requested 
GET /interviews HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "bdc9403a-5021-498b-8d1b-d4cc0ef23a44",
    "rating": 0,
    "type": "one_way",
    "status": "completed",
    "created_at": "2024-12-21T17:11:02+00:00",
    "updated_at": "2024-12-21T17:11:02+00:00",
    "scheduled_at": "2025-01-15T17:11:02+00:00",
    "completed_at": "2025-01-01T17:11:02+00:00",
    "job_post": {
      "uuid": "7998f858-915b-4447-bf54-63e44463cc25",
      "title": "Sr. Account Executive",
      "created_at": "2024-12-21T17:11:02+00:00",
      "updated_at": "2024-12-21T17:11:02+00:00",
      "status_updated_at": "2025-01-15T17:11:02+00:00",
      "status": "active",
      "created_by": {
        "uuid": "29fc66c4-f3d1-11e2-ab8f-12313d03fec7",
        "name": "Calvin Shelton",
        "email": "calvin.shelton@example.com",
        "avatar": "https://cdn.example.com/avatar.png"
      },
      "location": {
        "uuid": "5320d1f4-f187-11e3-a0a0-080027880ca6",
        "formatted_address": "Shermer, IL, USA",
      }
    },
    "assigned_to": {
      "uuid": "ad1de611-e40e-4618-a603-ebf59a2c8092",
      "name": "Job Seeker",
      "email": "jobseeker@example.com",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "company": {
      "uuid": "b902fc6f-08ff-11e3-b8f7-22000aaa0152",
      "name": "Shermer Staffing",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "created_by": {
      "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
      "name": "Company User",
      "email": "example@company.com",
      "avatar": "https://cdn.example.com/avatar.png"
    }
  }
]

Get a Single Interview

GET /interviews/:uuid

If you'd like to watch a completed interview you can create a link to https://www.sparkhire.com/interview/{uuid}/watch.

A lot of data is returned, but it breaks down into simple objects.

interview

Name Description
uuid The interview UUID
rating A number between 0 - 5 (could be 3.4, 1.2, etc)
type one_way or live
status accepted, requested, completed, expired, or canceled
created_at Timestamp for when the interview was created
updated_at Timestamp for when the interview was last updated
scheduled_at For a live interview this is the time the interview takes place
completed_at Timestamp for when the interview was completed by the job seeker
share_link The basic share link for this interview.

interview.questions

This is the same thing that is returned by hitting GET /interview/:uuid/questions.

interview.job_post

This is the same thing that is returned by hitting GET /job/:uuid.

interview.assigned_to

This is the user data for the job seeker who the interview is assigned to.

interview.company

This is the company data for the company that the interview belongs to.

interview.created_by

This is the user data for the company user who created the interview. 

GET /interviews/:uuid HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "bdc9403a-5021-498b-8d1b-d4cc0ef23a44",
  "rating": 0,
  "type": "one_way",
  "status": "completed",
  "created_at": "2024-12-21T17:11:02+00:00",
  "updated_at": "2024-12-21T17:11:02+00:00",
  "scheduled_at": "2025-01-15T17:11:02+00:00",
  "completed_at": "2025-01-01T17:11:02+00:00",
  "job_post": {
    "uuid": "7998f858-915b-4447-bf54-63e44463cc25",
    "title": "Sr. Account Executive",
    "created_at": "2024-12-21T17:11:02+00:00",
    "updated_at": "2024-12-21T17:11:02+00:00",
    "status_updated_at": "2025-01-15T17:11:02+00:00",
    "status": "active",
    "created_by": {
      "uuid": "29fc66c4-f3d1-11e2-ab8f-12313d03fec7",
      "name": "Calvin Shelton",
      "email": "calvin.shelton@example.com",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "location": {
      "uuid": "5320d1f4-f187-11e3-a0a0-080027880ca6",
      "formatted_address": "Shermer, IL, USA",
    }
  },
  "assigned_to": {
    "uuid": "ad1de611-e40e-4618-a603-ebf59a2c8092",
    "name": "Job Seeker",
    "email": "jobseeker@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "company": {
    "uuid": "b902fc6f-08ff-11e3-b8f7-22000aaa0152",
    "name": "Shermer Staffing",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "created_by": {
    "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
    "name": "Company User",
    "email": "example@company.com",
    "avatar": "https://cdn.example.com/avatar.png"
  }
  "questions": [
    {
      "uuid": "f8050292-554c-4e2c-8189-9330cfc80234",
      "text": "Why do you want to work here?",
      "completed": true,
      "time_limit": 60,
      "takes": {
        "completed": 0,
        "remaining": 0
    }
  ]
}

Create a new interview

POST /interviews

Property Description Required
type one_way or live
✓
scheduled_at When the interview is due. They cannot complete the interview after this time. Must be within 1 year of the current date.
✓
assigned_to A single user object (name, email) or an array of user objects to send interviews to. A new interview will be created for each user object. Creating a single interview returns a single interview, creating multiple returns an array of interviews.

If the plan has interview_sms_notifications enabled and you wish to also send an initial SMS invite along with the email, and an SMS reminder ~24 hours before the interview scheduled_at, you may optionally set phone and phone_parsed values on a user object. Both fields are required if either one is present. The phone value will be displayed in the Spark Hire user interface while phone_parsed is used for telephone link hrefs and is used when sending the actual SMS message. To ensure passing validation and maximum deliverability please ensure the phone_parsed value conforms to the E.164 international standard. There are many ways to parse this value. has_sms_consent must be true when using this functionality.
✓
email_message The text that will be sent along with the interview invitation email  
job_post The UUID of the job post this interview belongs to
✓
questions The format here is the same as in creating an interview question
✓
interview_question_set The uuid of a saved interview question set that you want to clone for this interview. If this is set, the questions array is ignored.
timezone The timezone is used to format a date if the user's current timezone is not known. For example, the invite email that is sent to the user will have a date formatted in this timezone. Can be any valid tz database timezone. Will default to UTC if not set.
has_sms_consent This is required when using phone and phone_parsed in assigned_to for SMS notifications. Please confirm you have permission to contact candidates by SMS text message. We require that some sort of user-initiated active confirmation (like a checkbox) is used to populate this value. It should not just be hard-coded to true. 
POST /interviews
Content-Type: application/json

{
  "type": "one_way",
  "scheduled_at": "2024-12-26T17:11:02+00:00",
  "assigned_to": [
    {
      "name": "Job Seeker",
      "email": "jobseeker@example.com"
    },
    {
      "name": "Another Jobseeker",
      "email": "another.job.seeker@example.com",
      "phone": "(312) 555-9494",
      "phone_parsed": "+13125559494"
    }
  ],
  "email_message": "Please complete this interview by this Friday.",
  "job_post": {
    "uuid": "35e44e40-fac8-11e2-ab8f-12313d03fec7"
  },
  "questions": [
    {
      "text": "Why do you want to work here?",
      "time_limit": 60,
      "takes": 0
    },
    {
      "text": "Describe your ideal job.",
      "time_limit": 120,
      "takes": 0
    }
  ],
  "interview_question_set": "e057657a-713b-4ba8-bb1c-8e50a5efc3d0",
  "timezone": "America/Chicago",
  "has_sms_consent": true
}
HTTP/1.1 201 OK
Content-Type: application/json

{
  "uuid": "bdc9403a-5021-498b-8d1b-d4cc0ef23a44",
  "rating": 0,
  "type": "one_way",
  "status": "completed",
  "created_at": "2024-12-21T17:11:02+00:00",
  "updated_at": "2024-12-21T17:11:02+00:00",
  "scheduled_at": "2025-01-15T17:11:02+00:00",
  "completed_at": "2025-01-01T17:11:02+00:00",
  "job_post": {
    "uuid": "7998f858-915b-4447-bf54-63e44463cc25",
    "title": "Sr. Account Executive",
    "created_at": "2024-12-21T17:11:02+00:00",
    "updated_at": "2024-12-21T17:11:02+00:00",
    "status_updated_at": "2025-01-15T17:11:02+00:00",
    "status": "active",
    "created_by": {
      "uuid": "29fc66c4-f3d1-11e2-ab8f-12313d03fec7",
      "name": "Calvin Shelton",
      "email": "calvin.shelton@example.com",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "location": {
      "uuid": "5320d1f4-f187-11e3-a0a0-080027880ca6",
      "formatted_address": "Shermer, IL, USA",
    }
  },
  "assigned_to": {
    "uuid": "ad1de611-e40e-4618-a603-ebf59a2c8092",
    "name": "Job Seeker",
    "email": "jobseeker@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "company": {
    "uuid": "b902fc6f-08ff-11e3-b8f7-22000aaa0152",
    "name": "Shermer Staffing",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "created_by": {
    "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
    "name": "Company User",
    "email": "example@company.com",
    "avatar": "https://cdn.example.com/avatar.png"
  }
  "questions": [
    {
      "uuid": "f8050292-554c-4e2c-8189-9330cfc80234",
      "text": "Why do you want to work here?",
      "completed": true,
      "time_limit": 60,
      "takes": {
        "completed": 0,
        "remaining": 0
    },
    {
      "uuid": "f8050292-554c-4e2c-8189-9330cfc80234",
      "text": "Describe your ideal job.",
      "completed": true,
      "time_limit": 120,
      "takes": {
        "completed": 0,
        "remaining": 0
    }
  ]
}

Update an interview

PUT /interviews/:uuid

Property Description Required
scheduled_at When the interview is due. They cannot complete the interview after this time. Must be within 1 year of the current date.
-
status A company can cancel an interview that has not yet been completed by the job seeker. A company can also complete live interviews.
-
 
POST /interviews
Content-Type: application/json

{
  "scheduled_at": "2024-12-26T17:11:02+00:00",
  "status": "canceled"
}

HTTP/1.1 201 OK
Content-Type: application/json

{
  "uuid": "bdc9403a-5021-498b-8d1b-d4cc0ef23a44",
  "rating": 0,
  "type": "one_way",
  "status": "completed",
  "created_at": "2024-12-21T17:11:02+00:00",
  "updated_at": "2024-12-21T17:11:02+00:00",
  "scheduled_at": "2025-01-15T17:11:02+00:00",
  "completed_at": "2025-01-01T17:11:02+00:00",
  "job_post": {
    "uuid": "7998f858-915b-4447-bf54-63e44463cc25",
    "title": "Sr. Account Executive",
    "created_at": "2024-12-21T17:11:02+00:00",
    "updated_at": "2024-12-21T17:11:02+00:00",
    "status_updated_at": "2025-01-15T17:11:02+00:00",
    "status": "active",
    "created_by": {
      "uuid": "29fc66c4-f3d1-11e2-ab8f-12313d03fec7",
      "name": "Calvin Shelton",
      "email": "calvin.shelton@example.com",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "location": {
      "uuid": "5320d1f4-f187-11e3-a0a0-080027880ca6",
      "formatted_address": "Shermer, IL, USA",
    }
  },
  "assigned_to": {
    "uuid": "ad1de611-e40e-4618-a603-ebf59a2c8092",
    "name": "Job Seeker",
    "email": "jobseeker@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "company": {
    "uuid": "b902fc6f-08ff-11e3-b8f7-22000aaa0152",
    "name": "Shermer Staffing",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "created_by": {
    "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
    "name": "Company User",
    "email": "example@company.com",
    "avatar": "https://cdn.example.com/avatar.png"
  }
  "questions": [
    {
      "uuid": "f8050292-554c-4e2c-8189-9330cfc80234",
      "text": "Why do you want to work here?",
      "completed": true,
      "time_limit": 60,
      "takes": {
        "completed": 0,
        "remaining": 0
    }
  ]
}

Delete an Interview

DELETE /interviews/:uuid 

DELETE /interviews/:uuid HTTP/1.1
HTTP/1.1 204 No Content

Interview Questions

All One-way interviews require questions.

Get a List of an Interviews Questions

GET /interviews/:uuid/questions 

GET /interviews/:uuid/questions HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "f8050292-554c-4e2c-8189-9330cfc80234",
    "text": "Why do you want to work here?",
    "completed": false,
    "skipped": false,
    "time_limit": 60,
    "takes": {
      "completed": -1,
      "remaining": -1,
      "limit": -1
    },
    "created_at": "2015-10-30T16:10:10+00:00",
    "updated_at": "2015-10-30T16:10:10+00:00",
    "started_at": null
  }
]

Get an Interview Question

GET /interviews/:uuid/questions/:uuid 

GET /interviews/:uuid/questions/:uuid HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "f8050292-554c-4e2c-8189-9330cfc80234",
  "text": "Why do you want to work here?",
  "completed": false,
  "skipped": false,
  "time_limit": 60,
  "takes": {
    "completed": -1,
    "remaining": -1,
    "limit": -1
  },
  "created_at": "2015-10-30T16:10:10+00:00",
  "updated_at": "2015-10-30T16:10:10+00:00",
  "started_at": null
}

Create an Interview Question

POST /interviews/:uuid/questions

To create an interview question post the question text formatted like this example.

Once an interview has been accepted, you cannot modify it.

Property Description Required
text The question text
✓
time_limit The question time limit in seconds. Must 30, 60, 90, 120, 160, or 180.
takes The number of times a job seeker can retake an interview question video. Cannot be more than 5. (-1 is unlimited and the default value). 
POST /interviews/:uuid/questions
Content-Type: application/json

{
  "text": "Why do you want to work with us?",
  "time_limit": 60,
  "takes": -1
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "f8050292-554c-4e2c-8189-9330cfc80234",
  "text": "Why do you want to work here?",
  "completed": false,
  "skipped": false,
  "time_limit": 60,
  "takes": {
    "completed": -1,
    "remaining": -1,
    "limit": -1
  },
  "created_at": "2015-10-30T16:10:10+00:00",
  "updated_at": "2015-10-30T16:10:10+00:00",
  "started_at": null
}

Update an Interview Question

PUT /interviews/:uuid/questions/:uuid

Once an interview has been accepted, you cannot modify it.

Property Description Required
text The question text
-
 
PUT /interviews/:uuid/questions/:uuid HTTP/1.1
Content-Type: application/json

{
  "text": "Why would you like to work with us?"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "f8050292-554c-4e2c-8189-9330cfc80234",
  "text": "Why would you like to work with us?",
  "completed": false,
  "skipped": false,
  "time_limit": 60,
  "takes": {
    "completed": -1,
    "remaining": -1,
    "limit": -1
  },
  "created_at": "2015-10-30T16:10:10+00:00",
  "updated_at": "2015-10-30T16:10:10+00:00",
  "started_at": null
}

Delete an Interview Question

DELETE /interviews/:uuid/questions/:uuid

Once an interview has been accepted, you cannot delete questions. 

DELETE /interviews/:uuid/questions/:uuid HTTP/1.1
HTTP/1.1 204 No Content

Question Sets

Save question templates to use when creating interviews. It's important to note that questions and their settings are copied to an interview. They are not directly linked to an interview, and thus updating a question set will not effect already created interviews.

Get a List of Question Sets

GET /question_sets 

GET /interview_question_sets HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "8a26c89b-3183-54be-ba60-e6ca608009ee",
    "created_at": "2024-12-21T17:11:02+00:00",
    "updated_at": "2024-12-21T17:11:02+00:00",
    "name": "A Basic Question Set Edit",
    "questions": [
      {
        "uuid": "372c6e93-a14c-4af2-b68a-c79aac574d9b",
        "time_limit": 60,
        "takes": 3,
        "think_time": "-1",
        "text": "What do you know about our company?"
      },
      {
        "uuid": "e76790ab-2072-45a0-b987-68b63ac201be",
        "time_limit": 120,
        "takes": 2,
        "think_time": "-1",
        "text": "Why are you interested in this particular career?"
      }
    ]
  }
]

Get a Question Set

GET /question_sets/:uuid 

GET /interview_question_sets/:uuid HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "8a26c89b-3183-54be-ba60-e6ca608009ee",
  "created_at": "2024-12-21T17:11:02+00:00",
  "updated_at": "2024-12-21T17:11:02+00:00",
  "name": "A Basic Question Set Edit",
  "questions": [
    {
      "uuid": "372c6e93-a14c-4af2-b68a-c79aac574d9b",
      "time_limit": 60,
      "takes": 3,
      "think_time": "-1",
      "text": "What do you know about our company?"
    },
    {
      "uuid": "e76790ab-2072-45a0-b987-68b63ac201be",
      "time_limit": 120,
      "takes": 2,
      "think_time": "-1",
      "text": "Why are you interested in this particular career?"
    }
  ]
}

Create a Question Set

POST /question_sets

To create an interview question set, post an array of question objects along with a name for the set.

Once an interview has been accepted, you cannot modify it. 

POST /interview_question_sets
Content-Type: application/json

{
  "name": "A Basic Question Set",
  "questions": [
    {
      "time_limit": 60,
      "takes": 3,,
      "think_time": "-1",
      "text": "What do you know about our company?"
    },
    {
      "time_limit": 120,
      "takes": 2,
      "think_time": "-1",
      "text": "Why are you interested in this particular career?"
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "8a26c89b-3183-54be-ba60-e6ca608009ee",
  "created_at": "2024-12-21T17:11:02+00:00",
  "updated_at": "2024-12-21T17:11:02+00:00",
  "name": "A Basic Question Set",
  "questions": [
    {
      "uuid": "372c6e93-a14c-4af2-b68a-c79aac574d9b",
      "time_limit": 60,
      "takes": 3,
      "think_time": "-1",
      "text": "What do you know about our company?"
    },
    {
      "uuid": "e76790ab-2072-45a0-b987-68b63ac201be",
      "time_limit": 120,
      "takes": 2,
      "think_time": "-1",
      "text": "Why are you interested in this particular career?"
    }
  ]
}

Update a Question Set

PUT /question_sets/:uuid

You can rename a question set, as well as update the time limit, takes, or text of any question within the set. 

PUT /interview_question_sets/:uuid HTTP/1.1
Content-Type: application/json

{
  "name": "A Basic Question Set",
  "questions": [
    {
      "uuid": "372c6e93-a14c-4af2-b47a-c79aac574d9b",
      "time_limit": 60,
      "takes": 3,
      "think_time": "-1",
      "text": "What do you know about our company?"
    },
    {
      "uuid": "e76790ab-2072-45a0-b707-68b63ac201be",
      "time_limit": 120,
      "takes": 2,
      "think_time": "-1",
      "text": "Why are you interested in this particular career?"
    },
    {
      "time_limit": 60,
      "takes": 3,
      "think_time": "-1",
      "text": "Why do you want to work for our company?"
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "8a26c89b-3183-54be-ba60-e6ca608009ee",
  "created_at": "2024-12-20T17:11:02+00:00",
  "updated_at": "2024-12-21T17:11:02+00:00",
  "name": "A Basic Question Set",
  "questions": [
    {
      "uuid": "372c6e93-a14c-4af2-b68a-c79aac574d9b",
      "time_limit": 60,
      "takes": 3,
      "think_time": "-1",
      "text": "What do you know about our company?"
    },
    {
      "uuid": "e76790ab-2072-45a0-b987-68b63ac201be",
      "time_limit": 120,
      "takes": 2,
      "think_time": "-1",
      "text": "Why are you interested in this particular career?"
    },
    {
      "uuid": "bbb17a5f-20d7-4bc4-b88b-bfd8a46e4b2f",
      "time_limit": 60,
      "takes": 3,
      "think_time": "-1",
      "text": "Why do you want to work for our company?"
    }
  ]
}

Delete a Question Set

DELETE /question_sets/:uuid

Once an interview has been accepted, you cannot delete questions. 

DELETE /interview_question_sets/:uuid HTTP/1.1
HTTP/1.1 204 No Content

Basic Share Links

Any completed interview can have a basic share link created for it. Update it to be active and your ready to send the viewable interview to anybody you'd like.

Basic links are referenced from an interview's api route. Posting with no data to this route creates the share link.

Create a basic share link

POST /interviews/:uuid/share_link 

POST /interviews/:uuid/share_link
Content-Type: application/json


HTTP/1.1 201 OK
Content-Type: application/json

{
  "uuid": "e66aa8fa-9250-4936-8924-c472b28e913b",
  "url": "http://hire.li/1qnBtNk",
  "created_at": "2024-12-21T17:11:02+00:00",
  "updated_at": "2024-12-21T17:11:02+00:00",
  "status": "active",
  "updated_by": {
    "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
    "name": "Staffing Recruiter",
    "email": "recruiter@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  }
}

Get a basic share link

GET /interviews/:uuid/share_link

GET /interviews/:uuid/share_link/:link_uuid

Interviews only have one basic link. Both routes will return the interview's basic share link.

shared

Name Description
uuid The shared link UUID
url The shared link public url
type The type of shared link (collaborative/open)
status The shared link viewing status. 'active' links are viewable, 'inactive' links are not.
updated_by The company user who last updated this share link. 
GET /interviews/:uuid/share_link HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "e66aa8fa-9250-4936-8924-c472b28e913b",
  "url": "http://hire.li/1qnBtNk",
  "created_at": "2024-12-21T17:11:02+00:00",
  "updated_at": "2024-12-21T17:11:02+00:00",
  "status": "active",
  "updated_by": {
    "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
    "name": "Staffing Recruiter",
    "email": "recruiter@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  }
}

Update a basic share link

PUT /interviews/:uuid/share_link/:link_uuid

Property Description Required
status active or inactive.
-
 
PUT /interviews/:uuid/share_link/:link_uuid
Content-Type: application/json

{
  "status": "inactive"
}

HTTP/1.1 201 OK
Content-Type: application/json

{
  "uuid": "e66aa8fa-9250-4936-8924-c472b28e913b",
  "url": "http://hire.li/1qnBtNk",
  "created_at": "2024-12-21T17:11:02+00:00",
  "updated_at": "2024-12-21T17:11:02+00:00",
  "status": "active",
  "updated_by": {
    "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
    "name": "Staffing Recruiter",
    "email": "recruiter@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  }
}

Advanced Share Links

Advanced links are a showcase for multiple candidate interviews. Attaching multiple interviews to a share link lets you easily share multiple candidates on one page.

This is an example of what an advanced share link page with multiple candidates would look like for the people you share with.

And this is an example of a share page for an individual candidate's interview with a submitted review.

Get a list of advanced share links

GET /share_links

A list of advanced share links that have been created. 

GET /share_links HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "e66aa8fa-9250-4936-8924-c472b28e913b",
    "url": "http://hire.li/1xEu9nJ",
    "created_at": "2014-11-10T22:35:12+00:00",
    "updated_at": "2014-11-10T22:35:12+00:00",
    "status": "active",
    "reviewer": {
      "name": "Hiring Authority",
      "email": "hiring.authority@example.com"
    },
    "created_by": {
      "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
      "name": "Staffing Recruiter",
      "email": "recruiter@example.com",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "updated_by": {
      "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
      "name": "Staffing Recruiter",
      "email": "recruiter@example.com",
      "avatar": "https://cdn.example.com/avatar.png"
    }
  }
]

Get an advanced share link

GET /share_links/:uuid

Get a single shared link object by its uuid.

shared

Name Description
uuid The shared link UUID
url The shared link public url
status The shared link viewing status. 'active' links are viewable, 'inactive' links are not.
reviewer Name and email of the person this was shared with
company The company who created the shared link
created_by The company user who created the shared link
interviews The array of shared interviews attached to this share link 
GET /share_links/:uuid HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "e66aa8fa-9250-4936-8924-c472b28e913b",
  "url": "http://hire.li/1xEu9nJ",
  "created_at": "2014-11-10T22:35:12+00:00",
  "updated_at": "2014-11-10T22:35:12+00:00",
  "status": "active",
  "reviewer": {
    "name": "Hiring Authority",
    "email": "hiring.authority@example.com"
  },
  "created_by": {
    "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
    "name": "Staffing Recruiter",
    "email": "recruiter@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "updated_by": {
    "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
    "name": "Staffing Recruiter",
    "email": "recruiter@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "interviews": [
    {
      "uuid": "521bc8e2-5833-4d8c-8034-746236ef8839",
      "interview_uuid": "fe4fd256-4869-4c12-b44f-6ee400ddb0c9"
      "scheduled_at": "2025-01-15T17:11:02+00:00",
      "completed_at": "2025-01-01T17:11:02+00:00",
      "type": "one_way",
      "job": {
        "uuid": "7998f858-915b-4447-bf54-63e44463cc25",
        "title": "Sr. Account Executive",
      }
    }
  ]
}

Create an advanced share link

POST /share_links

Returns an array of share links for each reviewer sent in the reviewers array

Property Description Required
status active or inactive.
✓
send_email Pass true. Not passing this will not send the email.
✓
reviewers Array of reviewer objects with "name" and "email". An advanced link will be created for each reviewer sent.
✓
interviews Array of interview objects. Each object must contain the interview's uuid.
✓
 
POST /share_links
Content-Type: application/json

{
  "status": "active",
  "send_email": true,
  "reviewers": [{
    "name": "Hiring Authority",
    "email": "hiring.authority@example.com"
  }],
  "interviews": [
    {
      "uuid": "d4695ffd-453a-4c46-8b51-dc15e4013e1b"
    },
    {
      "uuid": "d4667ffd-453a-4c46-8b51-dc15e4013e1b"
    }
  ]
}
HTTP/1.1 201 OK
Content-Type: application/json

[
 {
    "uuid": "e66aa8fa-9250-4936-8924-c472b28e913b",
    "url": "http://hire.li/1xEu9nJ",
    "created_at": "2014-11-10T22:35:12+00:00",
    "updated_at": "2014-11-10T22:35:12+00:00",
    "status": "active",
    "reviewer": {
      "name": "Hiring Authority",
      "email": "hiring.authority@example.com"
    },
    "created_by": {
      "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
      "name": "Staffing Recruiter",
      "email": "recruiter@example.com",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "updated_by": {
      "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
      "name": "Staffing Recruiter",
      "email": "recruiter@example.com",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "job": {
      "uuid": "7998f858-915b-4447-bf54-63e44463cc25",
      "title": "Sr. Account Executive",
    }
  }
]

Update an advanced share link

PUT /share_links/:uuid

Property Description Required
status active or inactive.
-
 
PUT /share_links/:uuid
Content-Type: application/json

{
  "status": "inactive"
}

HTTP/1.1 201 OK
Content-Type: application/json

{
  "uuid": "e66aa8fa-9250-4936-8924-c472b28e913b",
  "url": "http://hire.li/1xEu9nJ",
  "created_at": "2014-11-10T22:35:12+00:00",
  "updated_at": "2014-11-10T22:35:12+00:00",
  "status": "active",
  "reviewer": {
    "name": "Hiring Authority",
    "email": "hiring.authority@example.com"
  },
  "created_by": {
    "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
    "name": "Staffing Recruiter",
    "email": "recruiter@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "updated_by": {
    "uuid": "72e0e979-9dac-4d7f-8668-6e640a8105b9",
    "name": "Staffing Recruiter",
    "email": "recruiter@example.com",
    "avatar": "https://cdn.example.com/avatar.png"
  },
  "interviews": [
    {
      "uuid": "521bc8e2-5833-4d8c-8034-746236ef8839",
      "interview_uuid": "fe4fd256-4869-4c12-b44f-6ee400ddb0c9"
      "scheduled_at": "2025-01-15T17:11:02+00:00",
      "completed_at": "2025-01-01T17:11:02+00:00",
      "type": "one_way"
    }
  ]
}

Delete an advanced share link

DELETE /share_links/:uuid 

DELETE /share_links/:uuid HTTP/1.1
HTTP/1.1 204 No Content