Overview

This page contains documentation for how to interact with the Agave API. API access is included for all company accounts, and is available to use for Account Owners only.

Introduction

All API requests are accessed using the Agave API web service at https://api.agave.com/v1.

All requests are sent and received in the JSON data format.

Since the API is new and in a state of development, the API is subject to changes without version bumps. For that reason, we recommend you have developer resources available to make the necessary updates as our API changes.

Use Cases

The Agave API allows you to build different applications and scripts to perform actions like create candidates, integrate into other platforms (HRIS, HRMS, etc) and show data outside of our app suite.

Using our candidate endpoints, you can create:

  • A custom jobs page
  • A custom referral/agency portal
  • A university-specific jobs portal
  • Sync to other apps to update candidate information in Agave

The Agave API allows you to integrate with third-party tools in order to:

  • Add candidates into Agave with custom sources, tags, and stages
  • Update the candidate status in Agave based on what happens in third-party apps

Here are a few practical examples of what you can do:

  • Export candidate data to onboarding software
  • Export rich data downloads to third-party tools for reporting and analysis
  • Custom dashboards to show visual representations of candidate data

Authentication

All requests are authenticated using API keys generated by one of your company's Account Owners. You must include the API key as a value in each request with the api_key parameter. You can manage these keys from your https://hire.agave.com/settings/api-keys page. You can use multiple API keys at a time. It's important to keep your API keys secret because they allow others to access and update your company's data.

We use basic auth to handle requests (leave your password blank). All requests must be made over HTTPS.

Rate Limits

We enforce rate limiting to prevent abuse and keep our service responsive. Currently we limit requests to a steady stage of 5 requests per second per API key. When available, we support burst requests up to 10 requests per second. We do not offer a guarantee on these rates. For your implementation, we recommend an exponential backoff.

Please contact us if you're looking for increased rates.

We also enforce a maximum number of requests each month with "credits". You can view your remaining balance on the billing page and make changes. Each authenticated request consumes one credit, and the credits are refreshed at the start of each billing cycle.

Currently we deduct your consumed credits from the available pool at the top of each hour, as a result it is sometimes possible to accrue a small negative balance. If there is a deficit then we will use the new credits the following month to first cover that balance. For example, if you end up with -10 credits and would normally have 1000 credits added at the start of the billing cycle, you would now start with 990 credits.

Responses And Errors

When calls to the API fail, we return an HTTP status code to indicate what happened. The response body is in the JSON format with additional context.

HTTP Status Description
200 OK If data was requested, it's available in the data field at the top level of the response body.
201 Created Resource successfully created and the data is available in the data field at the top level of teh response body.
400 Invalid An error occured, typically because of bad or missing parameters. Double check the syntax of your request and try again.
401 Unauthorized A valid API key was not found in the request. You must authenticate all of your requests. Read more about how authentication works.
403 Forbidden You attempted to access a resource that is not authorized to your account. Ask an Account Owner to grant you a new API Key with the correct access.
404 Not Found The resource requested is missing, or the path you supplied is invalid.
429 Too Many Requests You are trying to access the API too frequently and are being limited, or have exceeded your maximum number of credits. Read more about how our rate limiting works.
500 Server Error It's not you, it's us. Something went wrong on our side.

Pagination

We support pagination of results. You can pass the parameters below in your request to limit the result count, or move the index with an offset.


Parameters
limit 5
Number
Number of results to limit to
offset 25
Number
Index of results

We enforce a default limit of 100 results per API call. For increased limits, please reach out to us.

We start our offset counting at 1, not 0. So if you wanted 200 results, you would make two requests. The second request would set an offset of 100 to start on the 100th record. The first request would return results 1-100, and the second request would return results 101-200.

Lists

We do not currently support lists, but the next API update will include this feature.

Webhooks

Our webhooks allow an HTTP POST request to be sent to a URL when any of the following events occur:

  • A candidate is hired
  • The candidate stage changes
  • The candidate archive reason changes (e.g. they were archived for a reason, or unarchived)

Using webhooks will allow you to notify third parties (such as HRIS applications) when important changes happen to your candidates.

An Owner account is required to setup webhooks. They can accessed from the Settings -> Webhooks page.

We only send webhook requests to valid HTTPS URLs.

Testing webhooks

You can test out a webhook on your own custom URL by clicking the "Test" button next to the URL (HTTPS required). Here is an example of what the request body looks like:

POST /custom-webhook-url HTTP/2

User-Agent: "Agave-Webhooks"
Content-Type: "application/json"
Content-Length: 153
{
  "sent_at": "11122333444",
  "event": "candidate_hired",
  "data": {},
  "signature": "7be4b3ca01b838d60a5a65f114ecfcffa9eb1bc47b44393779d64774ce206677",
  "token": "60a8c8ff7ed692d7f8f51ad2fd04b8ea"
}

Security considerations

In order to secure webhook requests:

  • We only allow an Account Owner to configure webhooks.
  • We only allow webhook requests to HTTPS URLs.
  • We generate tokens using a randomized string of length 32.
  • We generate a signature using SHA256 where the input is the concatenation of the token followed by the sent_at field.
  • We use a sent_at field to indicate when the request was sent. You should check this field to make sure it's a recent time.

Receiving a request

Our webhooks are sent as HTTPS POST requests, which is similar to any other type of HTTP request you'd receive. We use JSON as the data format in the request body.

Attributes
event offer_made
String
Type of event. Possible values are: hired, stage_change, or archive_reason_change.
sent_at 1555590983159
String
When webhook was created and sent for the first time (retries will occur on failure)
data Object
Payload for webhook event. See event payload for more details.
token 60a8c8ff7ed692d7f8f51ad2fd04b8ea
String
A randomized string of length 32. Can be regenerated by an Owner.
signature 7be4b3ca01b838d60a5a65f114ecfcffa9eb1bc47b44393779d64774ce206677
String
Hashed value (SHA256) of the token and sent_at fields.

We should receive back a 2xx response in order for the request to be considered successful. Anything other than 2xx will be considered a failure, and we will retry several times for up to 5 minutes.

You can track the history of requests on the webhooks page under the History section. We only record successful and failed attempts, we don't record retries. If a request initially fails, we will update the status to Success if it eventually succeeds, otherwise it remains in the Fail state.

Event payloads

If a candidate is hired, the event will be hired. The data will include the candidate_id.

{
  "event": "hired",
  "data": {
    "candidate_id": "1f00a7a6-ff9e-49d0-885a-3b1a955ef0c3"
  }
}



If a candidate stage changes, the event will be stage_change. The data will include the candidate_id, from_stage_id, and to_stage_id.

{
  "event": "stage_change",
  "data": {
    "candidate_id": "1f00a7a6-ff9e-49d0-885a-3b1a955ef0c3",
    "from_stage_id": "5cb41ba7-58a9-4e3c-ae7f-937373c51054",
    "to_stage_id": "4b89e585-c1d6-4649-91f5-92a4c01962df"
  }
}



If a candidate archive reason changes, the event will be archive_reason_change. The data will include the candidate_id, from_archive_reason (stage UID), to_archive_reason (stage UID), archived_at (timestamp of when candidate stage changed), and unarchived_at (timestamp if the candidate was unarchived, null otherwise).

{
  "event": "archive_reason_change",
  "data": {
    "candidate_id": "1f00a7a6-ff9e-49d0-885a-3b1a955ef0c3",
    "from_archive_reason": "494231fb-8ed9-4348-bdea-4bad1abd41bd",
    "to_archive_reason": "a1320c64-292c-4323-98f5-745e24259a3e",
    "archived_at": "1035106221173",
    "unarchived_at": null
  }
}

Hosted Jobs API

Job Postings

These hosted job postings are accessible to anyone with a valid company_name, without the need for authentication. For the purpose of public access, we will only expose jobs in the published state through this API.

List all job postings

GET /postings/company/:company_name HTTP/2

Example

curl https://api.agave.com/v1/postings/company/agave
Parameters
format html
String
JSON, HTML, or XML (Indeed)
limit 5
Number
Number of results to limit to
offset 25
Number
Index of results
location Palo Alto
String
Filter by location. Case-sensitive, supports multiple*
work_type Contact
String
Filter by work type. Case-sensitive, supports multiple*
team Engineering
String
Filter by team. Case-sensitive, supports multiple*
department Back-end
String
Filter by department. Case-sensitive, supports multiple*

* supports multiple values (i.e. location[]=Palo%20Alto&location[]=San%20Francisco), use ORs on multiple values.

Retrieve a job posting

GET /postings/company/:company_name/:posting_id HTTP/2

Example

curl https://api.agave.com/v1/postings/company/agave/9480f261-ef45-4ef3-ae66-223838c01968
Parameters
posting_id 9480f261-ef45-4ef3-ae66-223838c01968
String
Job Posting UID

Returns a JSON response of the job posting.

Hosted Job Responses

HTML

<div class="agave">
  <ul>
    <li>
      <a href="https://jobs.agave.com/agave/aaa-bbb-ccc-ddd" target="_top"
        >Customer Support Rep</a
      >
    </li>
    <li>
      <a href="https://jobs.agave.com/agave/aaa-bbb-ccc-eee" target="_top"
        >Site Reliability Engineer</a
      >
    </li>
  </ul>
</div>

JSON

{
  "id": "675cacc8-f32a-46e3-bafb-039f09c0df60",
  "type": "job",
  "data": {
    "id": "675cacc8-f32a-46e3-bafb-039f09c0df60",
    "title": "Software Engineer - React",
    "description": "<p>Experience with React, Redux and Saga.</p>",
    "job_site_url": "https://jobs.agave.com/agave/675cacc8-f32a-46e3-bafb-039f09c0df60",
    "apply_url": "https://jobs.agave.com/agave/675cacc8-f32a-46e3-bafb-039f09c0df60/apply",
    "opening_message": "Welcome to Agave.",
    "closing_message": "Thank you.",
    "details": {
      "work_type": "Full Time",
      "location": "Remote",
      "team": "Frontend",
      "department": "Engineering"
    }
  }
}

XML

<?xml version="1.0" encoding="utf-8"?>
<source>
    <publisher>Agave</publisher>
    <publisherurl>https://www.agave.com</publisherurl>
    <job>
        <title>
            <![CDATA[Software Engineer - React]]>
        </title>
        <date>
            <![CDATA[2019-05-21 04:23:03 UTC]]>
        </date>
        <referencenumber>
            <![CDATA[675cacc8-f32a-46e3-bafb-039f09c0df60]]>
        </referencenumber>
        <url>
            <![CDATA[https://jobs.agave.com/agave/675cacc8-f32a-46e3-bafb-039f09c0df60?source=Indeed]]>
        </url>
        <company>
            <![CDATA[Pied Piper]]>
        </company>
        <sourcename>
            <![CDATA[Agave]]>
        </sourcename>
        <city>
            <![CDATA[Palo Alto]]>
        </city>
        <state>
            <![CDATA[n/a]]>
        </state>
        <country>
            <![CDATA[US]]>
        </country>
        <email>
            <![CDATA[richard@pied-piper.com]]>
        </email>
        <description>
            <![CDATA[<p>Experience with Ruby on Rails.</p>]]>
        </description>
        <jobtype>
            <![CDATA[Full Time]]>
        </jobtype>
        <metadata>
            <![CDATA[Fulltime, Backend]]>
        </metadata>
    </job>
</source>
Attributes
id c80a3bff-d941-4ffb-8ed5-6dba3e78613c
String
Job Posting UID
title Software Engineer
String
Job posting title
description <p>Experience with React, Redux and Saga.</p>
HTML or String
Description of job posting
job_site_url https://jobs.agave.com/agave/675cacc8-f32a-46e3-bafb-039f09c0df60
String
The URL of the root URL of the hosted jobs page
apply_url https://jobs.agave.com/agave/675cacc8-f32a-46e3-bafb-039f09c0df60/apply
String
The URL to apply to the specific job
opening_message <p>Welcome to Agave.</p>
HTML or String
Opening message of job posting
closing_message <p>Thank you.</p>
HTML or String
Closing message of job posting
details
Object
Details regarding location, work type, team, department

Applications

Candidates can apply directly to these job posting through this API. You can also setup integrations. Note that only published job postings are accessible.

Apply to a job posting

POST /postings/company/:company_name HTTP/2

Example

curl -d '{"posting_id": "c5bf80e8-9b8e-422e-a9a7-608c51efa61f", "name": "Tony", "email": "tony@agave.com"}' -H "Content-Type: application/json" -X POST https://api.agave.com/v1/postings/company/agave/e1e7bbfc-c6f2-457f-95b0-fc5be07df349
Fields
posting_id c80a3bff-d941-4ffb-8ed5-6dba3e78613c
String
Job Posting UID*
name Tony
String
Application name*
email tony@agave.com
String
Application email*
resume
Multipart/form-data file
Optional resume attachment
phone 123-456-7890
String
Applicant phone number
company Agave
String
Current applicant company
links [ "http://linkedin.com/in/tony" ]
Array of links
List of relevant links
send_confirmation
Boolean
Whether candidate should receive confirmation email
source LinkedIn
String
Source tag
ip 0.0.0.0
String
IP address (for compliance reasons)
consent
Boolean
Whether candidate is open to future opportunities, if they're protected by GDPR

* required fields

API Reference

This documentation contains all resources available through the Agave Developer API. Find details on how to interact with each endpoint and the expected data returned.

Candidates

Candidates are added to your Agave account through the following ways:

  • applying through your job site
  • being manually added
  • being referred by someone else such as another team member or an agency
  • being sourced using the Chrome extension.

Candidates contain personal details, notes, feedback, interview schedules, and additional forms. Once a candidate is archived, they exit your hiring pipeline. A candidate is archived when they are either rejected or hired.

Note: We currently only support the read and list endpoints.

Retrieve a candidate

GET /candidates/:candidate HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/745d7143-543a-46d7-80fe-8bc0512f7bc8
{
  "data": {
    "id": "745d7143-543a-46d7-80fe-8bc0512f7bc8",
    "name": "Bob Loblaw",
    "owner": "8cd0f70d-7ce3-40aa-b552-784f65bd8fb3",
    "headline": "Acme Inc, E Corp, Mega Coffee Corp",
    "location": "Champaign-Urbana, IL",
    "emails": ["bob@loblaw.com"],
    "phones": [
      {
        "kind": "mobile",
        "number": "555-111-2233"
      }
    ],
    "links": ["http://linkedin.com/in/bobloblaw"],
    "created_at": "1045106226179",
    "last_interaction_at": "1035106221173",
    "snooze_ends_at": "1165101251183",
    "archived_at": "1035191254783",
    "stage": {
      "id": "7daba49e-bd8d-4b30-a882-ec4110fadef7",
      "text": "New Lead"
    },
    "stage_changes": [
      {
        "id": "14b2b6c5-fd87-41a5-9ffe-af5469509b35",
        "from_stage": null,
        "to_stage": "7daba49e-bd8d-4b30-a882-ec4110fadef7",
        "user": "8cd0f70d-7ce3-40aa-b552-784f65bd8fb3",
        "updated_at": "1555459724275"
      }
    ],
    "tags": ["Stack Overflow", "Software Engineer", "Referral", "Palo Alto"],
    "sources": ["Extension", "LinkedIn"],
    "origin": "sourced",
    "applications": ["a9aeb707-7c3c-4d97-96b4-7ad3e93b34a2"],
    "followers": ["b7a6788d-265c-45f3-a0b7-701cdcb5b34d"],
    "urls": {
      "show": "https://hire.agave.com/candidates/745d7143-543a-46d7-80fe-8bc0512f7bc8",
      "list": "https://hire.agave.com/candidates"
    },
    "data_protection": {
      "lawful_basis": "Candidate consent",
      "consent_period": "Six months",
      "consent_expires_at": null,
      "is_anonymized": false
    }
  }
}

List all candidates

GET /candidates HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates
{
  "data": [
    {
      "id": "745d7143-543a-46d7-80fe-8bc0512f7bc8",
      "name": "Bob Loblaw",
      "owner": "8cd0f70d-7ce3-40aa-b552-784f65bd8fb3",
      "headline": "Acme Inc, E Corp, Mega Coffee Corp",
      "location": "Champaign-Urbana, IL",
      "emails": ["bob@loblaw.com"],
      "job_ids": [
        "476831d1-9753-4dea-ac8a-57f8b3af07c6",
        "87abcb82-bcd0-456a-b103-aa188abe9e62"
      ],
      "phones": [
        {
          "kind": "mobile",
          "number": "555-111-2233"
        }
      ],
      "links": ["http://linkedin.com/in/bobloblaw"],
      "created_at": "1045106226179",
      "last_interaction_at": "1035106221173",
      "snooze_ends_at": "1165101251183",
      "archived_at": "1035191254783",
      "stage": {
        "id": "7daba49e-bd8d-4b30-a882-ec4110fadef7",
        "text": "New Lead"
      },
      "stage_changes": [
        {
          "id": "14b2b6c5-fd87-41a5-9ffe-af5469509b35",
          "from_stage": null,
          "to_stage": "7daba49e-bd8d-4b30-a882-ec4110fadef7",
          "user": "8cd0f70d-7ce3-40aa-b552-784f65bd8fb3",
          "updated_at": "1555459724275"
        }
      ],
      "tags": ["Stack Overflow", "Software Engineer", "Referral", "Palo Alto"],
      "sources": ["Extension", "LinkedIn"],
      "origin": "sourced",
      "applications": ["a9aeb707-7c3c-4d97-96b4-7ad3e93b34a2"],
      "followers": ["b7a6788d-265c-45f3-a0b7-701cdcb5b34d"],
      "urls": {
        "show": "https://hire.agave.com/candidates/745d7143-543a-46d7-80fe-8bc0512f7bc8",
        "list": "https://hire.agave.com/candidates"
      },
      "data_protection": {
        "lawful_basis": "Candidate consent",
        "consent_period": "Six months",
        "consent_expires_at": null,
        "is_anonymized": false
      }
    },
    {
      "id": "ab41139a-7de8-4e4c-8c38-f8f770b5b7e1",
      "name": "Kevin Durant",
      "owner": "8cd0f70d-7ce3-40aa-b552-784f65bd8fb3",
      "headline": "Small forward for the GSW",
      "location": "Oakland, CA",
      "emails": ["kd@gs.com"],
      "job_ids": [
        "476831d1-9753-4dea-ac8a-57f8b3af07c6",
        "87abcb82-bcd0-456a-b103-aa188abe9e62"
      ],
      "phones": [
        {
          "kind": "mobile",
          "number": "123-456-7890"
        }
      ],
      "links": [],
      "created_at": "1235537336182",
      "last_interaction_at": null,
      "snooze_ends_at": null,
      "archived_at": "1555537343777",
      "stage": {
        "id": "e01d8dae-09ad-4954-84bd-79b148f7c8a1",
        "text": "Timing"
      },
      "stage_changes": [
        {
          "id": "9c3b0146-e9bf-4000-b1c0-10d1a008a4d7",
          "from_stage": "7daba49e-bd8d-4b30-a882-ec4110fadef7",
          "to_stage": "e01d8dae-09ad-4954-84bd-79b148f7c8a1",
          "user": "8cd0f70d-7ce3-40aa-b552-784f65bd8fb3",
          "updated_at": "1555537343771"
        },
        {
          "id": "a8379c07-102d-459d-ab47-eea024489b49",
          "from_stage": null,
          "to_stage": "7daba49e-bd8d-4b30-a882-ec4110fadef7",
          "user": "8cd0f70d-7ce3-40aa-b552-784f65bd8fb3",
          "updated_at": "1555537336230"
        }
      ],
      "tags": ["basketball"],
      "sources": ["Extension"],
      "origin": "referred",
      "applications": ["2458c4f6-1de6-43f7-84cd-55bed0f0f7b4"],
      "followers": [],
      "urls": {
        "show": "https://hire.agave.com/candidates/ab41139a-7de8-4e4c-8c38-f8f770b5b7e1",
        "list": "https://hire.agave.com/candidates"
      },
      "data_protection": {
        "lawful_basis": "Candidate consent",
        "consent_period": "Six months",
        "consent_expires_at": null,
        "is_anonymized": false
      }
    }
  ]
}
Parameters
link linkedin.com/kevin_durant
String
Candidate link
owned_by 47328b3c-b208-44bd-98d5-8eddc06eef01
String
Candidate owner UID
created_by 47328b3c-b208-44bd-98d5-8eddc06eef01
String
User UID who created the candidate
state archived
String
Candidate pipeline state. Possible values are active or archived.
email kevin.durant@nba.com
String
Candidate email
phone 555-424-4422
String
Candidate phone number
Attributes
id fa0845f8-44cc-4cc0-b30b-f0d175080429
String
Candidate UID
name Bob Loblaw
String
Candidate full name
owner 47328b3c-b208-44bd-98d5-8eddc06eef01
String
Candidate owner UID
headline Acme Inc, E Corp, Mega Coffee Corp
String
Candidate headline - usually this highlights their current company, a list of previous companies, or schools they've attended
location Champaign-Urbana, IL
String
Candidate current location
emails bob@loblaw.com
Array of strings
Candidate emails
job_ids Array of strings
The UID of jobs associated with the candidate.
phones [{"kind": "mobile", "number": "555-111-2233"}]
Array of objects
Candidate phone number(s)
links linkedin.com/in/bobloblaw
Array of strings
Candidate links
created_at 1045106226179
Timestamp
Datetime when candidate was created. If the candidate applied through your job site, this value is the moment they hit the "apply" button on their application.
last_interaction_at 1035106221173
Timestamp
Datetime when last interaction with candidate profile occurred.
snooze_ends_at 1165101251183
Timestamp
If candidate has been snoozed, this value indicates when snooze ends.
archived_at 1035191254783
Timestamp
When the candidate was archived (eg rejected or hired).
stage Object
The current candidate stage.
stage_changes Array of objects
The progression of the candidate's stages.
tags ["Stack Overflow", "Software Engineer", "Referral", "Palo Alto"]
Array of strings
A list of custom candidate tags.
sources ["Extension", "LinkedIn"]
Array of strings
A list of candidate sources.
origin "referred"
String
The candidate's origin.
applications ["a9aeb707-7c3c-4d97-96b4-7ad3e93b34a2"]
Array of strings
A list of the candidate's job application IDs (the job posting they are being considered for).
followers ["b7a6788d-265c-45f3-a0b7-701cdcb5b34d"]
Array of strings
A list of user IDs (strings) who are following the candidate.
urls Object
An object with the show and list URLs to view the candidate profile and all candidates respectively.
data_protection Object
An object with the lawful_basis, consent_period, consent_expires_at, and is_anonymized string properties to indicate GDPR status.

Create a candidate

POST /candidates HTTP/2

Example

curl -u API_KEY: -d '{"name":"Kevin Duraant", "owned_by_id": :user_id, "perform_as": :user_id}' -H "Content-Type: application/json" -X POST https://api.agave.com/v1/candidates

Update a candidate

PUT /candidates/:candidate HTTP/2

Example

curl -u API_KEY: -d '{"name":"Kevin Duraant", "owned_by_id": :user_id, "perform_as": :user_id}' -H "Content-Type: application/json" -X PUT https://api.agave.com/v1/candidates/e4ec5416-e685-4b40-9134-066eb49170d9
Params
name Bob Loblaw
String
Candidate full name
location Champaign-Urbana, IL
String
Candidate current location
origin "referred"
String
The candidate's origin.
snooze_ends_at 1165101251183
Timestamp
If candidate has been snoozed, this value indicates when snooze ends.
emails bob@loblaw.com
Array of strings
Candidate emails
phones [{"kind": "mobile", "number": "555-111-2233"}]
Array of objects
Candidate phone number(s)
links linkedin.com/in/bobloblaw
Array of strings
Candidate links
owned_by_id 47328b3c-b208-44bd-98d5-8eddc06eef01
String
Candidate owner UID
perform_as fe9f0364-66dc-4e70-baaf-7d464bc9c00b
String
Perform this create on behalf of a User.

Feedback

Feedback forms are added to a candidate's profile, usually after an interview is completed.

Retrieve a feedback form

GET /candidates/:candidate/feedbacks/:feedback HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/e4ec5416-e685-4b40-9134-066eb49170d9/feedbacks/b162178b-c1da-4c93-b499-473872d2d846
{
  "data": {
    "id": "b162178b-c1da-4c93-b499-473872d2d846",
    "type": "interview",
    "title": "Interview feedback",
    "instructions": "Please complete form following interview",
    "fields": {},
    "form": "a35957c2-2dc6-48e4-95b9-7497940daba3",
    "user": "8cd0f70d-7ce3-40aa-b552-784f65bd8fb3",
    "created_at": "1555983926707",
    "completed_at": "1555984790677",
    "state": "submitted"
  }
}

List all feedback

GET /candidates/:candidate/feedbacks HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/e4ec5416-e685-4b40-9134-066eb49170d9/feedbacks
{
  "data": [
    {
      "id": "b162178b-c1da-4c93-b499-473872d2d846",
      "type": "interview",
      "title": "Interview feedback",
      "instructions": "Please complete form following interview",
      "fields": {},
      "form": "a35957c2-2dc6-48e4-95b9-7497940daba3",
      "user": "8cd0f70d-7ce3-40aa-b552-784f65bd8fb3",
      "created_at": "1555983926707",
      "completed_at": "1555984790677",
      "state": "submitted"
    },
    {
      "id": "06b84b7a-24b3-428a-90d6-6ec4956bd576",
      "type": "interview",
      "title": "Testing form",
      "instructions": "This is a test feedback form",
      "fields": {},
      "form": "5d45d8e4-c0b0-4bc7-b4e2-5f7a68679bc5",
      "user": "a181bf83-98b9-48b1-952d-cb429ea7adcc",
      "created_at": "1555984953275",
      "completed_at": null,
      "state": "draft"
    }
  ]
}
Attributes
id c80a3bff-d941-4ffb-8ed5-6dba3e78613c
String
Form UID
type interview
String
Form type. Feedback forms are of type interview
title NBA Draft Report
String
Form title
instructions Observe players making free throws and form a recommendation.
String
Form instructions
fields
Object
Currently under construction. Collection of questions and answers.
form c80a3bff-d941-4ffb-8ed5-6dba3e78613c
String
Form template UID.
user 7595cbb2-2d82-4dcc-9f70-538f15282525
String
The user who completed and submitted the feedback.
created_at 1095106136159
Timestamp
Datetime when form was created.
completed_at 1095106137359
Timestamp
Datetime when form was completed.
state submitted
String
State of form. Can be either draft if in progress or submitted if completed.

Feedback Templates

List all feedback templates

GET /feedback-forms HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/feedback-forms
{
  "data": [
    {
      "id": "a45beb29-e6f0-4c23-862e-89b4710c3b84",
      "title": "Simple Interview Feedback",
      "group": {
        "id": "7b8cfd19-1daa-48a4-a9d9-ce14d5e0c0b7",
        "title": "Interview"
      },
      "description": "Feedback form post interview",
      "questions": [
        {
          "id": "fea0b8fd-bebd-4151-bcd6-6b1b2aef415c",
          "type": "feedback_form_question",
          "data": {
            "id": "fea0b8fd-bebd-4151-bcd6-6b1b2aef415c",
            "question": "Rating",
            "description": null,
            "placeholder": null,
            "input": "rating",
            "options": [],
            "required": true,
            "display_order": 0
          }
        }
      ],
      "created_at": "1555984950275",
      "updated_at": "1555984953275"
    },
    {
      "id": "9441b2d9-f21e-4c34-9779-71f1b1adbad7",
      "title": "Interview Feedback",
      "group": {
        "id": "7b8cfd19-1daa-48a4-a9d9-ce14d5e0c0b7",
        "title": "Interview"
      },
      "description": "Assessment form post interview",
      "questions": [
        {
          "id": "990d0405-9b7b-4790-9e6d-9181cfe82fc3",
          "type": "feedback_form_question",
          "data": {
            "id": "990d0405-9b7b-4790-9e6d-9181cfe82fc3",
            "question": "Rating",
            "description": null,
            "placeholder": null,
            "input": "rating",
            "options": [],
            "required": true,
            "display_order": 0
          }
        },
        {
          "id": "7e4c1814-b2b6-484c-89cf-679d251e7841",
          "type": "feedback_form_question",
          "data": {
            "id": "7e4c1814-b2b6-484c-89cf-679d251e7841",
            "question": "Culture Fit",
            "description": "Question to judge culture fit",
            "placeholder": null,
            "input": "scorecard",
            "options": [
              {
                "title": "Culture Fit"
              },
              {
                "title": "Motivation"
              }
            ],
            "required": false,
            "display_order": 1
          }
        }
      ],
      "created_at": "1555984950275",
      "updated_at": "1555984953275"
    }
  ]
}
Attributes
id c80a3bff-d941-4ffb-8ed5-6dba3e78613c
String
Template UID
title Interview Feedback
String
Template title
group Object
Returns the id and title of the group this template belongs to. Templates can be assigned to custom group names, or the field is empty if there is no grouping.
description Question to judge culture fit
String
The description of the feedback template.
questions Array of Objects
Returns the id and type, and relevant data of the questions in this template.
created_at 1095106136159
Timestamp
Datetime when form was created.
updated_at 1095106137359
Timestamp
Datetime when form was updated.

Files

Retrieve a file

GET /candidates/:candidate/files/:file HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/e4ec5416-e685-4b40-9134-066eb49170d9/files/667ad6fd-36d3-471a-beb3-804d3f1ef97c
{
  "data": {
    "id": "667ad6fd-36d3-471a-beb3-804d3f1ef97c",
    "url": "https://api.agave.com/rails/active_storage/blobs/eyJfcmFxbHM/Kevin%20Durant%20Resume%2019.pdf",
    "ext": ".pdf",
    "name": "Kevin Durant Resume 2019",
    "uploaded_at": "1095106136159"
  }
}

List all files

GET /candidates/:candidate/files HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/e4ec5416-e685-4b40-9134-066eb49170d9/files
{
  "data": [
    {
      "id": "667ad6fd-36d3-471a-beb3-804d3f1ef97c",
      "url": "https://api.agave.com/rails/active_storage/blobs/eyJfcmFxbHM/Kevin%20Durant%20Resume%2019.pdf",
      "ext": ".pdf",
      "name": "Kevin Durant Resume 2019",
      "uploaded_at": "1095106136159"
    },
    {
      "id": "e2663e8b-3d24-4bb1-b352-50c69caf8ea5",
      "url": "https://api.agave.com/rails/active_storage/blobs/FGrekLoJKbn/Parsed%20Resume.json",
      "ext": ".json",
      "name": "Parsed Resume",
      "uploaded_at": "15131341241259"
    }
  ]
}
Attributes
id 667ad6fd-36d3-471a-beb3-804d3f1ef97cc
String
File UID
url https://api.agave.com/rails/active_storage/blobs/eyJfcmFxbHM/Resume%2019.pdf
String
URL of file to download
ext .pdf
String
Returns the extension of the candidate file.
name Kevin Durant Resume 2019
String
File name.
uploaded_at 1095106136159
Timestamp
Datetime when the file was originally uploaded to the candidate profile.

Download file

GET /candidates/:candidate/files/:file/download HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/e4ec5416-e685-4b40-9134-066eb49170d9/files/667ad6fd-36d3-471a-beb3-804d3f1ef97c/download

Interviews

Retrieve an interview

GET /candidates/:candidate/interviews/:interview HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/e4ec5416-e685-4b40-9134-066eb49170d9/interviews/fe829871-cfeb-4649-a6e7-c14f56eeda07
{
  "data": {
    "id": "fe829871-cfeb-4649-a6e7-c14f56eeda07",
    "state": "scheduled",
    "description": "Please bring your laptop with you and check in at the front desk.",
    "feedback_reminder": "once",
    "time_zone": "America/Los_Angeles",
    "starts_at": "1015106236159",
    "ends_at": "1015106237110",
    "canceled_at": "1015106237120",
    "stage": "faf0d55e-d24f-4feb-886e-30f169eb386f",
    "posting": "e9ed8ee3-5999-4577-a401-03842a26eef9",
    "user": "fe9f0364-66dc-4e70-baaf-7d464bc9c00b",
    "created_at": "1015106236389",
    "updated_at": "1015106236394",
    "slots": [
      {
        "data": {
          "id": "323e1a9b-7076-42d2-b438-1a374158808e",
          "description": "Technical interview",
          "starts_at": "1015106236159",
          "ends_at": "1015106237110",
          "feedback_form": "01415ad3-7213-4037-b7be-5ee5128f6069",
          "location": "San Francisco",
          "interviewers": ["d5f6ef74-613e-4b19-96c4-54aee6d74e81"]
        }
      }
    ]
  }
}

List all interviews

GET /candidates/:candidate/interviews HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/e4ec5416-e685-4b40-9134-066eb49170d9/interviews
{
  "data": [
    {
      "id": "fe829871-cfeb-4649-a6e7-c14f56eeda07",
      "state": "scheduled",
      "description": "Please bring your laptop with you and check in at the front desk.",
      "feedback_reminder": "once",
      "time_zone": "America/Los_Angeles",
      "starts_at": "1015106236159",
      "ends_at": "1015106237110",
      "canceled_at": "1015106237120",
      "stage": "faf0d55e-d24f-4feb-886e-30f169eb386f",
      "posting": "e9ed8ee3-5999-4577-a401-03842a26eef9",
      "user": "fe9f0364-66dc-4e70-baaf-7d464bc9c00b",
      "created_at": "1015106236389",
      "updated_at": "1015106236394",
      "slots": [
        {
          "data": {
            "id": "323e1a9b-7076-42d2-b438-1a374158808e",
            "description": "Technical interview",
            "starts_at": "1015106236159",
            "ends_at": "1015106237110",
            "feedback_form": "01415ad3-7213-4037-b7be-5ee5128f6069",
            "location": "San Francisco",
            "interviewers": ["d5f6ef74-613e-4b19-96c4-54aee6d74e81"]
          }
        }
      ]
    },
    {
      "id": "cb6df100-98d9-49f2-9374-a2179d80fb12",
      "state": "draft",
      "description": "Please bring your laptop with you and check in at the front desk.",
      "feedback_reminder": "none",
      "time_zone": "America/Los_Angeles",
      "starts_at": "1215106236159",
      "ends_at": "1215106237110",
      "canceled_at": null,
      "stage": "d14fccce-69eb-4cd0-adbb-8f3eb90790f7",
      "posting": "dedb3de0-1ccb-4b73-8361-4a694a43c840",
      "user": "d062ff36-8d8f-41e1-afac-199e360fd69b",
      "created_at": "1215106236389",
      "updated_at": "1215106236394",
      "slots": [
        {
          "data": {
            "id": "a08d52e4-ae79-41dd-9d21-748b54a82ef4",
            "description": "First interview",
            "starts_at": "1215106236159",
            "ends_at": "1215106236610",
            "feedback_form": "1b9a3efb-54c2-44bc-bd34-c153434b917f",
            "location": "San Francisco",
            "interviewers": ["d5f6ef74-613e-4b19-96c4-54aee6d74e81"]
          }
        },
        {
          "data": {
            "id": "323e1a9b-7076-42d2-b438-1a374158808e",
            "description": "Second interview",
            "starts_at": "1215136236610",
            "ends_at": "1215136237110",
            "feedback_form": "1b9a3efb-54c2-44bc-bd34-c153434b917f",
            "location": "San Francisco",
            "interviewers": ["085131cc-93c3-4fcf-b356-74cfd20fcbec"]
          }
        }
      ]
    }
  ]
}
Attributes
id fe829871-cfeb-4649-a6e7-c14f56eeda07
String
Interview UID
state scheduled
String
State of interview. Can be either draft if in progress and unscheduled or scheduled if interview has been scheduled.
description Please bring your laptop with you and check in at the front desk.
String
The description of the interview. This is usually written in by the interviewer to provide instructions to the candidate.
feedback_reminder once.
String
How frequently to remind interviewers to leave feedback if it's missing. Possible values are none, once, daily, or every_6_hours.
time_zone America/Los_Angeles
String
Time zone of interview.
starts_at 1015106236159
Timestamp
Datetime of when interview starts.
ends_at 1015106237110
Timestamp
Datetime of when the interview ends.
canceled_at 1015106237120
Timestamp
Datetime when interview was canceled. Value is null if the interview is not canceled.
stage faf0d55e-d24f-4feb-886e-30f169eb386f
String
The Stage UID of the candidate at the time the interview is scheduled.
posting e9ed8ee3-5999-4577-a401-03842a26eef9
String
Job Posting UID of candidate for this interview.
user fe9f0364-66dc-4e70-baaf-7d464bc9c00b
String
User UID who created the interview.
created_at 1015106236389
Timestamp
Datetime of when the interview was created.
updated_at 1015106236394
Timestamp
Datetime of when the interview was last updated.
slots Object
A list of the interview slots. Each interview slot has id, description, starts_at, ends_at, feedback_form, location, and interviewers nested in a data object.

Create an interview

POST /candidates/:candidate/interviews HTTP/2

Example

curl -u API_KEY: -d '{"state":"draft", "time_zone":"America/Los_Angeles", "perform_as": :user_id}' -H "Content-Type: application/json" -X POST https://api.agave.com/v1/candidates/e4ec5416-e685-4b40-9134-066eb49170d9/interviews
Params
state scheduled
String
State of interview. Can be either draft if in progress and unscheduled or scheduled if interview has been scheduled.
description Please bring your laptop with you and check in at the front desk.
String
The description of the interview. This is usually written in by the interviewer to provide instructions to the candidate.
feedback_reminder once.
String
How frequently to remind interviewers to leave feedback if it's missing. Possible values are none, once, daily, or every_6_hours.
time_zone America/Los_Angeles
String
Time zone of interview.
starts_at 1015106236159
Timestamp
Datetime of when interview starts.
ends_at 1015106237110
Timestamp
Datetime of when the interview ends.
perform_as fe9f0364-66dc-4e70-baaf-7d464bc9c00b
String
Perform this create on behalf of a User.

Delete an interview

DELETE /candidates/:candidate/interviews/:interview HTTP/2

Example

curl -u API_KEY: -X DELETE https://api.agave.com/v1/candidates/e4ec5416-e685-4b40-9134-066eb49170d9/interviews/cb6df100-98d9-49f2-9374-a2179d80fb12

This endpoint should change interview state to cancelled

Notes

Retrieve an note

GET /candidates/:candidate/notes/:note HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/b77c41bd-3e1b-4b4c-ae66-c2768340e0fa/notes/e8137aaa-41dc-403d-a919-a14fabe905b3
{
  "data": {
    "id": "e8137aaa-41dc-403d-a919-a14fabe905b3",
    "text": "<p>Strong candidate, solid</p>",
    "rating": "strong_yes",
    "secret": true,
    "created_by_id": "8cd0f70d-7ce3-40aa-b552-784f65bd8fb3",
    "created_at": "1546923036000",
    "updated_at": "1546923036000",
    "candidate_id": "b77c41bd-3e1b-4b4c-ae66-c2768340e0fa"
  }
}

List all notes

GET /candidates/:candidate/notes HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/b77c41bd-3e1b-4b4c-ae66-c2768340e0fa/notes
{
  "data": [
    {
      "id": "e8137aaa-41dc-403d-a919-a14fabe905b3",
      "text": "<p>Strong candidate, solid</p>",
      "rating": "strong_yes",
      "secret": true,
      "created_by_id": "8cd0f70d-7ce3-40aa-b552-784f65bd8fb3",
      "created_at": "1546923036000",
      "updated_at": "1546923036000",
      "candidate_id": "b77c41bd-3e1b-4b4c-ae66-c2768340e0fa"
    },
    {
      "id": "57a1f139-0906-4b58-a5bb-7efd75dccad0",
      "text": "<p>Not quite what we are looking for</p>",
      "rating": "no",
      "secret": false,
      "created_by_id": "9bb9cf8d-a6e5-4869-94a3-1aa62cd04535",
      "created_at": "1546923036000",
      "updated_at": "1546923036000",
      "candidate_id": "b77c41bd-3e1b-4b4c-ae66-c2768340e0fa"
    }
  ]
}
Attributes
id fe829871-cfeb-4649-a6e7-c14f56eeda07
String
Note UID
created_by_id 9bb9cf8d-a6e5-4869-94a3-1aa62cd04535
String
User UID
candidate_id b77c41bd-3e1b-4b4c-ae66-c2768340e0fa
String
Candidate UID
text Good candidate!
String
Text content of the note
rating yes
String
One of no, yes, strong_no, strong_yes
secret false
Boolean
Return whether note is secret
created_at 1015106237120
Timestamp
Datetime when note was created.
updated_at 1015106237120
Timestamp
Datetime when note was updated.

Offers

List offers

GET /candidates/:candidate/offers HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/e4ec5416-e685-4b40-9134-066eb49170d9/offers
{
  "data": [
    {
      "id": "b946dd65-2c92-4337-9955-437f92c4027f",
      "created_at": "1015106237120",
      "submitted_at": "1015106237110",
      "status": "signed",
      "fields": [
        {
          "question": "Candidate name",
          "answer": "Bob Loblaw"
        },
        {
          "question": "Compensation currency",
          "answer": "USD - $"
        },
        {
          "question": "Job posting",
          "answer": "8dd88781-0fe9-4a87-aa1d-d2fc365a1fb6"
        },
        {
          "question": "Job title",
          "answer": "Software Engineer"
        },
        {
          "question": "Offered compensation amount",
          "answer": {
            "currency": "USD",
            "amount": 100000
          }
        },
        {
          "question": "Type of earnings",
          "answer": "Year (Salary)"
        }
      ]
    },
    {
      "id": "22292b47-5d15-492f-8a13-7c8c8835d0d3",
      "created_at": "1115106237120",
      "submitted_at": "1115106237110",
      "status": "sent",
      "fields": [
        {
          "question": "Candidate name",
          "answer": "Bob Loblaw"
        },
        {
          "question": "Compensation currency",
          "answer": "USD - $"
        },
        {
          "question": "Job posting",
          "answer": "8dd88781-0fe9-4a87-aa1d-d2fc365a1fb6"
        },
        {
          "question": "Job title",
          "answer": "Software Engineer"
        },
        {
          "question": "Offered compensation amount",
          "answer": {
            "currency": "USD",
            "amount": 120000
          }
        },
        {
          "question": "Type of earnings",
          "answer": "Year (Salary)"
        }
      ]
    }
  ]
}
Attributes
id fe829871-cfeb-4649-a6e7-c14f56eeda07
String
Offer UID
created_at 1015106237120
Timestamp
Datetime when offer was created.
submitted_at 1015106237110
Timestamp
Datetime of when the offer was submitted (sent to the candidate for consideration).
user fe9f0364-66dc-4e70-baaf-7d464bc9c00b
String
User UID who created the offer.
status sent
String
State of offer letter. Can be draft if in progress, sent if emailed to candidate, signed if candidate signed, and declined if candidate rejected the offer.
fields Array of Objects
A list of questions and answers attached to the offer letter. These are form objects, similar to those used in feedbacks.

Jobs

Retrieve a job

GET /jobs/:job HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/jobs/e9ed8ee3-5999-4577-a401-03842a26eef9
{
  "data": {
    "id": "fe829871-cfeb-4649-a6e7-c14f56eeda07",
    "title": "Director of Sales",
    "created_at": "1015106236389",
    "updated_at": "1015106236394",
    "user": "14ff7873-4b27-4794-9c53-6ba5785daba5",
    "owner": "14ff7873-4b27-4794-9c53-6ba5785daba5",
    "hiring_manager": "14ff7873-4b27-4794-9c53-6ba5785daba5",
    "categories": {
      "team": "93d57b86-760d-49e6-a1e9-c341b3453506",
      "department": "fbf62992-2167-4256-b413-93a84b6b142a",
      "location": "San Francisco",
      "commitment": "1 Year"
    },
    "content": {
      "description": "Looking for a master of sales",
      "lists": [],
      "opening": "",
      "closing": "",
      "custom_questions": ["What's a project that you are proud of?"]
    },
    "tags": "sales, director",
    "state": "published",
    "urls": {
      "list": "jobs.agave.com/company/director_sales",
      "show": "jobs.agave.com/company/director_sales",
      "apply": "jobs.agave.com/company/director_sales"
    }
  }
}

List all jobs

GET /jobs HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/jobs
{
  "data": [
    {
      "id": "fe829871-cfeb-4649-a6e7-c14f56eeda07",
      "title": "Director of Sales",
      "created_at": "1015106236389",
      "updated_at": "1015106236394",
      "user": "14ff7873-4b27-4794-9c53-6ba5785daba5",
      "owner": "14ff7873-4b27-4794-9c53-6ba5785daba5",
      "hiring_manager": "14ff7873-4b27-4794-9c53-6ba5785daba5",
      "categories": {
        "team": "93d57b86-760d-49e6-a1e9-c341b3453506",
        "department": "fbf62992-2167-4256-b413-93a84b6b142a",
        "location": "San Francisco",
        "commitment": "1 Year"
      },
      "content": {
        "description": "Looking for a master of sales",
        "lists": [],
        "opening": "",
        "closing": "",
        "custom_questions": ["What's a project that you are proud of?"]
      },
      "tags": "sales, director",
      "state": "published",
      "urls": {
        "list": "jobs.agave.com/company/director_sales",
        "show": "jobs.agave.com/company/director_sales",
        "apply": "jobs.agave.com/company/director_sales"
      }
    },
    {
      "id": "5d91f313-3878-4d6d-a83a-a1e9a8ab6ffa",
      "title": "Software Engineer",
      "created_at": "1215106236389",
      "updated_at": "1215106236394",
      "user": "728ef96b-5144-45e1-9e47-b6fdb2ec050c",
      "owner": "2a8acfe8-ffce-4426-8e87-dbf04e8946cc",
      "hiring_manager": "ebfb7ff5-7078-431e-a870-76ee6193a272",
      "categories": {
        "team": "e2fe4665-2826-4fab-87d1-ca56d28d0b6a",
        "department": "26ed7cba-7e0b-49b2-8beb-aa5b1f74dd47",
        "location": "New York",
        "commitment": "6 Month"
      },
      "content": {
        "description": "Looking for a software engineer",
        "lists": [],
        "opening": "",
        "closing": "",
        "custom_questions": []
      },
      "tags": "software, engineer",
      "state": "close",
      "urls": {
        "list": "jobs.agave.com/company/software_engineer",
        "show": "jobs.agave.com/company/software_engineer",
        "apply": "jobs.agave.com/company/software_engineer"
      }
    }
  ]
}
Attributes
id fe829871-cfeb-4649-a6e7-c14f56eeda07
String
Posting UID
title Director of Sales
String
Title of the job posting.
created_at 1015106236389
Timestamp
Datetime of when the job posting was created.
updated_at 1015106236394
Timestamp
Datetime of when the job posting was last updated.
user 14ff7873-4b27-4794-9c53-6ba5785daba5
String
User UID who created the job posting.
owner 14ff7873-4b27-4794-9c53-6ba5785daba5
String
User UID who owns the job posting.
hiring_manager 14ff7873-4b27-4794-9c53-6ba5785daba5
String
User UID who is the hiring manager for job posting.
categories Object
Contains the team, department, location, and commitment of the job posting.
content Object
Contains the description, lists, opening, closing and custom_questions of the job posting.
tags sales, director
String
A string of custom tags set on this job posting. All candidates added to the posting will also automatically be assigned these tags.
state published
String
The state of the job posting. Possible values are draft, internal (may only manually add candidates or referrals), published (anyone can apply), or closed.
urls Object
Contains the list (company job site URL), show (job posting URL), and apply URLs for this job posting.

Create a job

POST /jobs HTTP/2

Example

curl -u API_KEY: -d '{"title":"Software Engineer", "state":"published", "owned_by_id": :user_id, "perform_as": :user_id}' -H "Content-Type: application/json" -X POST https://api.agave.com/v1/jobs

Update a job

PUT /jobs/:job HTTP/2
curl -u API_KEY: -d '{"title":"Software Engineer", "state":"published", "owned_by_id": :user_id, "perform_as": :user_id}' -H "Content-Type: application/json" -X PUT https://api.agave.com/v1/jobs/fe829871-cfeb-4649-a6e7-c14f56eeda07
Params
title Director of Sales
String
Title of the job posting.
state published
String
The state of the job posting. Possible values are draft, internal (may only manually add candidates or referrals), published (anyone can apply), or closed.
owned_by_id 14ff7873-4b27-4794-9c53-6ba5785daba5
String
User UID who owns the job posting.
perform_as fe9f0364-66dc-4e70-baaf-7d464bc9c00b
String
Perform this create on behalf of a User.

Referrals

Retrieve a referral

GET /candidates/:candidate/referrals/:referral HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/e9ed8ee3-5999-4577-a401-03842a26eef9/referrals/b5b3b784-ffb7-49bf-a336-e59505fd7974
{
  "data": {
    "id": "b5b3b784-ffb7-49bf-a336-e59505fd7974",
    "type": "referral",
    "title": "Referral",
    "instructions": "Please fill out this referral form for the candidate you are referring",
    "fields": [
      {
        "id": "287e3ba1-a0fd-4e43-8131-581292880478",
        "type": "form_submission_answer",
        "data": {
          "id": "287e3ba1-a0fd-4e43-8131-581292880478",
          "question": "Notes / Comments",
          "placeholder": null,
          "input": "textarea",
          "options": [],
          "required": false,
          "display_order": 2,
          "answer": null
        }
      },
      {
        "id": "ca729b63-8346-4b84-a87d-30404bddb706",
        "type": "form_submission_answer",
        "data": {
          "id": "ca729b63-8346-4b84-a87d-30404bddb706",
          "question": "Relationship",
          "placeholder": "Select one",
          "input": "dropdown",
          "options": [
            "Former colleague",
            "Friend",
            "Reputation",
            "Other",
            "Don't know this person"
          ],
          "required": false,
          "display_order": 1,
          "answer": null
        }
      },
      {
        "id": "2c5e408b-49e4-434d-a5ce-313054fd4e89",
        "type": "form_submission_answer",
        "data": {
          "id": "2c5e408b-49e4-434d-a5ce-313054fd4e89",
          "question": "Name of referrer",
          "placeholder": null,
          "input": "text",
          "options": [],
          "required": false,
          "display_order": 0,
          "answer": null
        }
      }
    ],
    "form": "cca6cfa0-0609-4a69-8c0c-f39ff48f0988",
    "referrer": "fcd64f86-9f26-4b48-a57e-3b6b0fb58b11",
    "user": "fcd64f86-9f26-4b48-a57e-3b6b0fb58b11",
    "created_at": "1035106236389"
  }
}

List all referrals

GET /candidates/:candidate/referrals HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/e9ed8ee3-5999-4577-a401-03842a26eef9/referrals
{
    "data": [
        {
            "id": "6c2a7aa1-ff6f-4196-aae9-819723d9e422",
            "type": "referral",
            "title": "Referral",
            "instructions": "Please fill out this referral form for the candidate you are referring",
            "fields": [
                {
                    "id": "287e3ba1-a0fd-4e43-8131-581292880478",
                    "type": "form_submission_answer",
                    "data": {
                        "id": "287e3ba1-a0fd-4e43-8131-581292880478",
                        "question": "Notes / Comments",
                        "placeholder": null,
                        "input": "textarea",
                        "options": [],
                        "required": false,
                        "display_order": 2,
                        "answer": "This candidate is excellent"
                    }
                },
                {
                    "id": "ca729b63-8346-4b84-a87d-30404bddb706",
                    "type": "form_submission_answer",
                    "data": {
                        "id": "ca729b63-8346-4b84-a87d-30404bddb706",
                        "question": "Relationship",
                        "placeholder": "Select one",
                        "input": "dropdown",
                        "options": [
                            "Former colleague",
                            "Friend",
                            "Reputation",
                            "Other",
                            "Don't know this person"
                        ],
                        "required": false,
                        "display_order": 1,
                        "answer": "Former colleague"
                    }
                },
                {
                    "id": "2c5e408b-49e4-434d-a5ce-313054fd4e89",
                    "type": "form_submission_answer",
                    "data": {
                        "id": "2c5e408b-49e4-434d-a5ce-313054fd4e89",
                        "question": "Name of referrer",
                        "placeholder": null,
                        "input": "text",
                        "options": [],
                        "required": false,
                        "display_order": 0,
                        "answer": "Kevin Durant"
                    }
                }
            ]
            "form": "cca6cfa0-0609-4a69-8c0c-f39ff48f0988",
            "referrer": "fcd64f86-9f26-4b48-a57e-3b6b0fb58b11",
            "user": "fcd64f86-9f26-4b48-a57e-3b6b0fb58b11",
            "created_at": "1015106236389"
        },
        {
            "id": "7d11ebec-319f-4e2c-8315-3779dedcc1df",
            "type": "referral",
            "title": "Referral",
            "instructions": "Please fill out this referral form for the candidate you are referring",
            "fields": [
                {
                    "id": "287e3ba1-a0fd-4e43-8131-581292880478",
                    "type": "form_submission_answer",
                    "data": {
                        "id": "287e3ba1-a0fd-4e43-8131-581292880478",
                        "question": "Notes / Comments",
                        "placeholder": null,
                        "input": "textarea",
                        "options": [],
                        "required": false,
                        "display_order": 2,
                        "answer": "This candidate is excellent"
                    }
                },
                {
                    "id": "ca729b63-8346-4b84-a87d-30404bddb706",
                    "type": "form_submission_answer",
                    "data": {
                        "id": "ca729b63-8346-4b84-a87d-30404bddb706",
                        "question": "Relationship",
                        "placeholder": "Select one",
                        "input": "dropdown",
                        "options": [
                            "Former colleague",
                            "Friend",
                            "Reputation",
                            "Other",
                            "Don't know this person"
                        ],
                        "required": false,
                        "display_order": 1,
                        "answer": "Friend"
                    }
                },
                {
                    "id": "2c5e408b-49e4-434d-a5ce-313054fd4e89",
                    "type": "form_submission_answer",
                    "data": {
                        "id": "2c5e408b-49e4-434d-a5ce-313054fd4e89",
                        "question": "Name of referrer",
                        "placeholder": null,
                        "input": "text",
                        "options": [],
                        "required": false,
                        "display_order": 0,
                        "answer": "Kevin Durant"
                    }
                }
            ]
            "form": "cca6cfa0-0609-4a69-8c0c-f39ff48f0988",
            "referrer": "a9d71e56-954a-4be3-b1ac-7e13202dd427",
            "user": "ae041e1b-c57b-41d3-b8a7-91622b2738ad",
            "created_at": "1115106236389"
        }
    ]
}
Attributes
id b5b3b784-ffb7-49bf-a336-e59505fd7974
String
Referral form UID
type referral
String
Type of form. This is always referral for this endpoint.
title Referral
String
Title of the referral form. This is set by default to Referral and can be customized.
instructions Fill out this form to the best of your knowledge.
String
Instructions for filling out the referral form. This is optional and can be set by the company.
fields Object
Contains the collection of question and answer form responses. Note: this response is not included in the current version of the API but will be supported in the future.
form 3e117fe6-ec04-4f68-9c0e-96ced99a3b32
String
Form UID of the referral form.
referrer 47328b3c-b208-44bd-98d5-8eddc06eef01
String
User UID of the referrer.
user fe9f0364-66dc-4e70-baaf-7d464bc9c00b
String
User UID of the referral creator. This is not always the referrer, but the Agave user that created the referral, even though they are usually the same person.
created_at 1015106236389
Timestamp
Datetime of when the referral was created.

Resumes

Retrieve a resume

GET /candidates/:candidate/parsed_resumes/:parsed_resume HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/0a32bc10-96b7-490a-9c5c-64125e5af045/parsed_resumes/8241116d-aae0-4c8e-8ea7-8ded52425904
{
  "data": {
    "id": "8241116d-aae0-4c8e-8ea7-8ded52425904",
    "work_history": {
      "EmployerOrg": [
        {
          "UserArea": {
            "sov:EmployerOrgUserArea": {
              "sov:NormalizedEmployerOrgName": "Splunk"
            }
          },
          "EmployerOrgName": "Splunk",
          "PositionHistory": [
            {
              "Title": "Professional Services Consultant",
              "EndDate": {
                "StringDate": "current"
              },
              "OrgInfo": [
                {
                  "PositionLocation": {
                    "CountryCode": "CA",
                    "Municipality": "Calgary"
                  }
                }
              ],
              "OrgName": {
                "OrganizationName": "Splunk"
              },
              "UserArea": {
                "sov:PositionHistoryUserArea": {
                  "sov:Id": "POS-1",
                  "sov:IsSelfEmployed": "true",
                  "sov:NormalizedTitle": "Professional Services Consultant",
                  "sov:SelfEmploymentPhrase": "Consultant",
                  "sov:NormalizedOrganizationName": "Splunk",
                  "sov:CompanyNameProbabilityInterpretation": {
                    "#text": "Confident",
                    "@internalUseOnly": "BS"
                  },
                  "sov:PositionTitleProbabilityInterpretation": {
                    "#text": "Confident",
                    "@internalUseOnly": "SM"
                  }
                }
              },
              "StartDate": {
                "YearMonth": "2018-06"
              },
              "Description": "Splunk is the leading platform for Operational Intelligence.",
              "JobCategory": [
                {
                  "Comments": "Information Technology describes 100% of this job",
                  "CategoryCode": "Information Technology → Privacy and Data Security",
                  "TaxonomyName": "Skills taxonomy"
                },
                {
                  "CategoryCode": "Senior (more than 5 years experience)",
                  "TaxonomyName": "Job Level"
                }
              ],
              "@positionType": "contract",
              "@currentEmployer": "true"
            }
          ]
        },
        {
          "UserArea": {
            "sov:EmployerOrgUserArea": {
              "sov:NormalizedEmployerOrgName": "Best Buy"
            }
          },
          "EmployerOrgName": "Best Buy",
          "PositionHistory": [
            {
              "Title": "Mobile Specialist",
              "EndDate": {
                "YearMonth": "2013-02"
              },
              "OrgName": {
                "OrganizationName": "Best Buy"
              },
              "UserArea": {
                "sov:PositionHistoryUserArea": {
                  "sov:Id": "POS-13",
                  "sov:NormalizedTitle": "Mobile Specialist",
                  "sov:NormalizedOrganizationName": "Best Buy",
                  "sov:CompanyNameProbabilityInterpretation": {
                    "#text": "Confident",
                    "@internalUseOnly": "SK"
                  },
                  "sov:PositionTitleProbabilityInterpretation": {
                    "#text": "Confident",
                    "@internalUseOnly": "ST"
                  }
                }
              },
              "StartDate": {
                "YearMonth": "2012-09"
              },
              "Description": "Activated new cell phone lines and hardware upgrades for all of the major\r\ncarriers.",
              "JobCategory": [
                {
                  "CategoryCode": "Entry Level",
                  "TaxonomyName": "Job Level"
                }
              ],
              "@positionType": "directHire"
            }
          ]
        }
      ]
    },
    "education_history": {
      "SchoolOrInstitution": [
        {
          "Degree": [
            {
              "Comments": "University of Calgary\r\nComputer Programming, Data Analysis\r\n\r\n• (2012 - 2016)",
              "UserArea": {
                "sov:DegreeUserArea": {
                  "sov:Id": "DEG-2"
                }
              },
              "DegreeDate": {
                "Year": "2016"
              },
              "DegreeMajor": [
                {
                  "Name": ["Computer Programming"]
                }
              ],
              "DatesOfAttendance": [
                {
                  "EndDate": {
                    "Year": "2016"
                  },
                  "StartDate": {
                    "Year": "2012"
                  }
                }
              ]
            }
          ],
          "School": [
            {
              "SchoolName": "University of Calgary"
            }
          ],
          "UserArea": {
            "sov:SchoolOrInstitutionTypeUserArea": {
              "sov:NormalizedSchoolName": "University of Calgary"
            }
          },
          "@schoolType": "university"
        }
      ]
    },
    "candidate_id": "0a32bc10-96b7-490a-9c5c-64125e5af045",
    "company_id": "36e4ef3f-7af2-423a-ae65-2d1dc7c19bb4",
    "created_by_id": "b204b74f-ddbc-43ef-a705-0766952d8bbe",
    "created_at": "1546922200",
    "updated_at": "1546922200"
  }
}

List all resumes

GET /candidates/:candidate/parsed_resumes HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/candidates/0a32bc10-96b7-490a-9c5c-64125e5af045/parsed_resumes
{
  "data": [
    {
      "id": "8241116d-aae0-4c8e-8ea7-8ded52425904",
      "work_history": {
        "EmployerOrg": [
          {
            "UserArea": {
              "sov:EmployerOrgUserArea": {
                "sov:NormalizedEmployerOrgName": "Splunk"
              }
            },
            "EmployerOrgName": "Splunk",
            "PositionHistory": [
              {
                "Title": "Professional Services Consultant",
                "EndDate": {
                  "StringDate": "current"
                },
                "OrgInfo": [
                  {
                    "PositionLocation": {
                      "CountryCode": "CA",
                      "Municipality": "Calgary"
                    }
                  }
                ],
                "OrgName": {
                  "OrganizationName": "Splunk"
                },
                "UserArea": {
                  "sov:PositionHistoryUserArea": {
                    "sov:Id": "POS-1",
                    "sov:IsSelfEmployed": "true",
                    "sov:NormalizedTitle": "Professional Services Consultant",
                    "sov:SelfEmploymentPhrase": "Consultant",
                    "sov:NormalizedOrganizationName": "Splunk",
                    "sov:CompanyNameProbabilityInterpretation": {
                      "#text": "Confident",
                      "@internalUseOnly": "BS"
                    },
                    "sov:PositionTitleProbabilityInterpretation": {
                      "#text": "Confident",
                      "@internalUseOnly": "SM"
                    }
                  }
                },
                "StartDate": {
                  "YearMonth": "2018-06"
                },
                "Description": "Canada Area\r\nSplunk is the leading platform for Operational Intelligence. Where you see\r\nservers and devices, apps and logs, traffic and clouds; we see data\r\neverywhere.\r\nSplunk enables the curious to look closely at what others ignore: machine\r\ndata, and find what others may never see: insights that can make your\r\ncompany more productive, profitable, secure and competitive.\r\nWhat can Splunk do for you? Just Ask.",
                "JobCategory": [
                  {
                    "Comments": "Information Technology describes 100% of this job",
                    "CategoryCode": "Information Technology → Privacy and Data Security",
                    "TaxonomyName": "Skills taxonomy"
                  },
                  {
                    "CategoryCode": "Senior (more than 5 years experience)",
                    "TaxonomyName": "Job Level"
                  }
                ],
                "@positionType": "contract",
                "@currentEmployer": "true"
              }
            ]
          },
          {
            "UserArea": {
              "sov:EmployerOrgUserArea": {
                "sov:NormalizedEmployerOrgName": "Best Buy"
              }
            },
            "EmployerOrgName": "Best Buy",
            "PositionHistory": [
              {
                "Title": "Mobile Specialist",
                "EndDate": {
                  "YearMonth": "2013-02"
                },
                "OrgName": {
                  "OrganizationName": "Best Buy"
                },
                "UserArea": {
                  "sov:PositionHistoryUserArea": {
                    "sov:Id": "POS-13",
                    "sov:NormalizedTitle": "Mobile Specialist",
                    "sov:NormalizedOrganizationName": "Best Buy",
                    "sov:CompanyNameProbabilityInterpretation": {
                      "#text": "Confident",
                      "@internalUseOnly": "SK"
                    },
                    "sov:PositionTitleProbabilityInterpretation": {
                      "#text": "Confident",
                      "@internalUseOnly": "ST"
                    }
                  }
                },
                "StartDate": {
                  "YearMonth": "2012-09"
                },
                "Description": "Burnaby\r\n• Activated new cell phone lines and hardware upgrades for all of the major\r\ncarriers in Canada.\r\n• Rapidly synthesized data and information to provide tailored\r\nrecommendations; built strong customer relationship to ensure brand loyalty.\r\n• Provided sale skills development and leadership to ensure that department\r\nsale goals were achieved\r\n• Interacted with ~100 customers/shift; used strong analytical skills to accurately assess and resolve customer issue\r\n• Routinely update reports to ensure efficient communication with manager",
                "JobCategory": [
                  {
                    "CategoryCode": "Entry Level",
                    "TaxonomyName": "Job Level"
                  }
                ],
                "@positionType": "directHire"
              }
            ]
          }
        ]
      },
      "education_history": {
        "SchoolOrInstitution": [
          {
            "Degree": [
              {
                "Comments": "University of Calgary\r\nComputer Programming, Data Analysis\r\n\r\n• (2012 - 2016)",
                "UserArea": {
                  "sov:DegreeUserArea": {
                    "sov:Id": "DEG-2"
                  }
                },
                "DegreeDate": {
                  "Year": "2016"
                },
                "DegreeMajor": [
                  {
                    "Name": ["Computer Programming"]
                  }
                ],
                "DatesOfAttendance": [
                  {
                    "EndDate": {
                      "Year": "2016"
                    },
                    "StartDate": {
                      "Year": "2012"
                    }
                  }
                ]
              }
            ],
            "School": [
              {
                "SchoolName": "University of Calgary"
              }
            ],
            "UserArea": {
              "sov:SchoolOrInstitutionTypeUserArea": {
                "sov:NormalizedSchoolName": "University of Calgary"
              }
            },
            "@schoolType": "university"
          }
        ]
      },
      "candidate_id": "0a32bc10-96b7-490a-9c5c-64125e5af045",
      "company_id": "36e4ef3f-7af2-423a-ae65-2d1dc7c19bb4",
      "created_by_id": "b204b74f-ddbc-43ef-a705-0766952d8bbe",
      "created_at": "1546923036000",
      "updated_at": "1546923036000"
    }
  ]
}
Attributes
id fe829871-cfeb-4649-a6e7-c14f56eeda07
String
Resume UID
candidate_id 0a32bc10-96b7-490a-9c5c-64125e5af045
String
Candidate UID
company_id 36e4ef3f-7af2-423a-ae65-2d1dc7c19bb4
String
Company UID
created_by_id b204b74f-ddbc-43ef-a705-0766952d8bbe
String
User UID
created_at 1546923036000
Timestamp
Datetime when resume was created.
updated_at 1546923036000
Timestamp
Datetime when resume was updated.
work_history Object
Data regarding candidate work history.
education_history Object
Data regarding candidate education history.

Sources

List all sources

GET /sources HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/sources
{
  "data": [
    {
      "text": "Manually added",
      "count": 2
    },
    {
      "text": "Job site",
      "count": 2
    },
    {
      "text": "Extension",
      "count": 9
    },
    {
      "text": "LinkedIn",
      "count": 4
    }
  ]
}
Attributes
text LinkedIn
String
Text of the source.
count Object
Number of times this source shows up on candidate profiles.

Stages

Retrieve a stage

GET /stages/:stage HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/stages/45d418c9-0d90-4488-a8cb-2ba641473153
{
  "data": {
    "id": "45d418c9-0d90-4488-a8cb-2ba641473153",
    "text": "Hired"
  }
}

List all stages

GET /stages HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/stages
{
  "data": [
    {
      "id": "7daba49e-bd8d-4b30-a882-ec4110fadef7",
      "text": "New Lead"
    },
    {
      "id": "2382b161-da75-4d53-871b-6f6b1db087dd",
      "text": "Reached Out"
    },
    {
      "id": "b822764b-dabd-493d-889f-590245345b6c",
      "text": "Responded"
    },
    {
      "id": "c81b148a-6b49-48eb-8f4f-cb3290ac7846",
      "text": "New Applicant"
    },
    {
      "id": "49aac907-e88b-4a03-9354-bc85da4ee5e1",
      "text": "Contacted"
    },
    {
      "id": "2287aa76-a17d-48c2-8b11-edb14924f3ed",
      "text": "Phone Interview"
    },
    {
      "id": "1394874a-5eda-4ad9-9e8e-6e088b50204f",
      "text": "On-site Interview"
    },
    {
      "id": "37a6727d-15ec-4854-a359-975946b8fe94",
      "text": "Reference Checks"
    },
    {
      "id": "d2eeb439-b987-4b35-b2f0-d2744ad2636b",
      "text": "Offer"
    },
    {
      "id": "36a7fbe6-5a3c-4861-8ed0-01545ce1e018",
      "text": "Underqualified"
    },
    {
      "id": "0febe3a8-7400-4a10-a043-f99a56bafafa",
      "text": "Unresponsive"
    },
    {
      "id": "e01d8dae-09ad-4954-84bd-79b148f7c8a1",
      "text": "Timing"
    },
    {
      "id": "b87cd52b-e43f-4915-8333-315e61383c95",
      "text": "Withdrew"
    },
    {
      "id": "9a25ad2a-7812-458a-b3e8-8c6866e31bc9",
      "text": "Offer declined"
    },
    {
      "id": "e29518f8-da86-4d27-9ff5-662adc11fce0",
      "text": "Position closed"
    },
    {
      "id": "45d418c9-0d90-4488-a8cb-2ba641473153",
      "text": "Hired"
    }
  ]
}
Attributes
id 88417217-3fd2-4850-a630-acea3e7f7ede
String
Stage UID
text Contacted
String
Title of the stage.

Tags

List all tags

GET /tags HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/tags
{
  "data": [
    {
      "text": "Contract",
      "count": 2
    },
    {
      "text": "Full Time",
      "count": 2
    },
    {
      "text": "Part Time",
      "count": 9
    },
    {
      "text": "Remote",
      "count": 4
    }
  ]
}
Attributes
text Contract
String
Text of the tag.
count Object
Number of times this tag shows up on candidate profiles.

Users

Retrieve a user

GET /users/:user HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/users/fe9f0364-66dc-4e70-baaf-7d464bc9c00b
{
  "data": {
    "id": "fe9f0364-66dc-4e70-baaf-7d464bc9c00b",
    "name": "Steve Kerr",
    "email": "steve.kerr@nba.com",
    "role": "owner",
    "photo": "https://api.agave.com/rails/active_storage/blobs/vyJpcmMxbHM/kerr.png",
    "created_at": "1015106236319",
    "deactivated_at": "1015106238324",
    "candidate_id": "f61c9f4b-6a8c-402b-80ae-5680d563052b"
  }
}

List all users

GET /users HTTP/2

Example

curl -u API_KEY: https://api.agave.com/v1/users
{
  "data": [
    {
      "id": "26903e84-d899-401d-9c5c-8c70b4ebf666",
      "name": "Alexander the Great",
      "email": "alex@greece.com",
      "role": "team_member",
      "photo": "https://api.agave.com/rails/active_storage/blobs/xMhuPMajkJD/alex.png",
      "created_at": "1555461512021",
      "deactivated_at": null,
      "candidate_id": null
    },
    {
      "id": "fe9f0364-66dc-4e70-baaf-7d464bc9c00b",
      "name": "Steve Kerr",
      "email": "steve.kerr@nba.com",
      "role": "owner",
      "photo": "https://api.agave.com/rails/active_storage/blobs/vyJpcmMxbHM/kerr.png",
      "created_at": "1015106236319",
      "deactivated_at": "1015106238324",
      "candidate_id": "f61c9f4b-6a8c-402b-80ae-5680d563052b"
    }
  ]
}
Attributes
id fe9f0364-66dc-4e70-baaf-7d464bc9c00b
String
User UID
name Steve Kerr
String
Full name of user.
email steve.kerr@nba.com
String
Email address of user.
role owner
String
Role of user. Possible values are owner, admin, member, hiring_manager, interviewer, and deactivated.
photo https://api.agave.com/rails/active_storage/blobs/vyJpcmMxbHM/kerr.png
String
URL of user photo. Value is null if user has not uploaded a photo.
created_at 1015106236319
Timestamp
Datetime of when the user was created.
deactivated_at 1015106238324
Timestamp
Datetime of when the user was deactivated.
candidate_id f61c9f4b-6a8c-402b-80ae-5680d563052b
String
Candidate UID if the user also has a candidate record.