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.
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.
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"
}
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 |
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"
}
All dates are returned in the RFC3339 format.
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"
}
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
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 POST
ing 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:
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.
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
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 |
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. |
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
}
]
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
}
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
This route allows you to grab basic information on your current user. It is useful for debugging unauthorized responses from the API.
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-06T20:31:00+00:00",
"renews_at": "2025-01-05T20:31:00+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"
}
}
}
}
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 /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-06T20:31:00+00:00",
"renews_at": "2025-01-05T20:31:00+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
}
}
}
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 /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-11-21T20:31:00+00:00",
"updated_at": "2024-11-21T20:31:00+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 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.
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-11-21T20:31:00+00:00",
"updated_at": "2024-11-27T20:31:00+00:00",
"company": {
"uuid": "0d2de946-fe53-11e2-ab8f-12313d03fec7",
"name": "Shermer Staffing",
"avatar": "https://cdn.example.com/avatar.png"
}
}
]
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-11-21T20:31:00+00:00",
"updated_at": "2024-11-27T20:31:00+00:00",
"company": {
"uuid": "0d2de946-fe53-11e2-ab8f-12313d03fec7",
"name": "Shermer Staffing",
"avatar": "https://cdn.example.com/avatar.png"
}
}
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-11-21T20:31:00+00:00",
"updated_at": "2024-11-27T20:31:00+00:00"
}
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-11-21T20:31:00+00:00",
"updated_at": "2024-11-27T20:31:00+00:00",
"company": {
"uuid": "0d2de946-fe53-11e2-ab8f-12313d03fec7",
"name": "Shermer Staffing",
"avatar": "https://cdn.example.com/avatar.png"
}
}
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
This endpoint allows administrators to view, create, delete, and modify company user API keys for custom Integrations.
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-04T20:31:00+00:00",
"created_at": "2024-11-21T20:31:00+00:00",
"updated_at": "2024-11-27T20:31:00+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 /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-04T20:31:00+00:00",
"created_at": "2024-11-21T20:31:00+00:00",
"updated_at": "2024-11-27T20:31:00+00:00",
"user": {
"uuid": "81e92110-d935-11e2-bdd9-080027733f26",
"email": "calvin.shelton@example.com",
"name": "Calvin Shelton",
"avatar": "https://cdn.example.com/avatar.png",
}
}
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-04T20:31:00+00:00",
"created_at": "2024-11-21T20:31:00+00:00",
"updated_at": "2024-11-27T20:31:00+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 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
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 /jobs
This resource returns an array of job objects.
See getting a job for an explanation of the data returned for each user.
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
|
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-11-21T20:31:00+00:00",
"updated_at": "2024-11-26T20:31:00+00:00",
"status_updated_at": "2024-11-26T20:31:00+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-05T20:31:00+00:00",
"status": "active"
}
}
]
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-11-21T20:31:00+00:00",
"updated_at": "2024-11-26T20:31:00+00:00",
"status_updated_at": "2024-11-26T20:31:00+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-05T20:31:00+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."
}
]
}
}
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' |
|
Example |
---|
|
Example |
---|
|
Example |
---|
|
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-11-21T20:31:00+00:00",
"updated_at": "2024-11-26T20:31:00+00:00",
"status_updated_at": "2024-11-26T20:31:00+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",
}
}
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-11-21T20:31:00+00:00",
"updated_at": "2024-11-26T20:31:00+00:00",
"status_updated_at": "2024-11-26T20:31:00+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-05T20:31:00+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 /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
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 /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.
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
|
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-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+00:00",
"scheduled_at": "2024-12-31T20:31:00+00:00",
"completed_at": "2024-12-17T20:31:00+00:00",
"job_post": {
"uuid": "7998f858-915b-4447-bf54-63e44463cc25",
"title": "Sr. Account Executive",
"created_at": "2024-12-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+00:00",
"status_updated_at": "2024-12-31T20:31:00+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 /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.
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. |
This is the same thing that is returned by hitting GET /interview/:uuid/questions.
This is the same thing that is returned by hitting GET /job/:uuid.
This is the user data for the job seeker who the interview is assigned to.
This is the company data for the company that the interview belongs to.
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-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+00:00",
"scheduled_at": "2024-12-31T20:31:00+00:00",
"completed_at": "2024-12-17T20:31:00+00:00",
"job_post": {
"uuid": "7998f858-915b-4447-bf54-63e44463cc25",
"title": "Sr. Account Executive",
"created_at": "2024-12-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+00:00",
"status_updated_at": "2024-12-31T20:31:00+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
}
]
}
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-11T20:31:00+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-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+00:00",
"scheduled_at": "2024-12-31T20:31:00+00:00",
"completed_at": "2024-12-17T20:31:00+00:00",
"job_post": {
"uuid": "7998f858-915b-4447-bf54-63e44463cc25",
"title": "Sr. Account Executive",
"created_at": "2024-12-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+00:00",
"status_updated_at": "2024-12-31T20:31:00+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
}
]
}
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-11T20:31:00+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-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+00:00",
"scheduled_at": "2024-12-31T20:31:00+00:00",
"completed_at": "2024-12-17T20:31:00+00:00",
"job_post": {
"uuid": "7998f858-915b-4447-bf54-63e44463cc25",
"title": "Sr. Account Executive",
"created_at": "2024-12-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+00:00",
"status_updated_at": "2024-12-31T20:31:00+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 /interviews/:uuid
DELETE /interviews/:uuid HTTP/1.1
HTTP/1.1 204 No Content
All One-way interviews require 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 /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
}
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
}
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 /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
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 /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-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+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 /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-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+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?"
}
]
}
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-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+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?"
}
]
}
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-05T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+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 /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
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.
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-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+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 /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.
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-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+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"
}
}
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-06T20:31:00+00:00",
"updated_at": "2024-12-06T20:31:00+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 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 /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 /share_links/:uuid
Get a single shared link object by its uuid.
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": "2024-12-31T20:31:00+00:00",
"completed_at": "2024-12-17T20:31:00+00:00",
"type": "one_way",
"job": {
"uuid": "7998f858-915b-4447-bf54-63e44463cc25",
"title": "Sr. Account Executive",
}
}
]
}
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",
}
}
]
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": "2024-12-31T20:31:00+00:00",
"completed_at": "2024-12-17T20:31:00+00:00",
"type": "one_way"
}
]
}
DELETE /share_links/:uuid
DELETE /share_links/:uuid HTTP/1.1
HTTP/1.1 204 No Content