Comeet for Developers

Develop apps and integrations to offer your service to Comeet users or streamline your own recruiting processes by building on Comeet.

26818
Suggest Edits

Careers API

 
 
 
Suggest Edits

Introduction

 

The Careers API is one of the integration options to sync a company's careers website with its Comeet account. Whether you need to create new career pages or connect existing pages, this integration option provides the most design flexibility.

To see more integration options, visit this page.

If at any time you have questions about using our Careers API, email us at api-support@comeet.co.

 
Suggest Edits

Prerequisites

 

Before starting, do the following:

  1. Set at least one position’s visibility to Published or Published (Restricted) so your web developer will have data to work with.
  2. Copy the company’s UID and Token from your Careers Website settings to send to your web developer.

Note: These steps can only be done by users with HR Admin or IT Admin roles.

 
Suggest Edits

Getting Started

 

To get started, you need your company’s details, including the company’s UID and the company’s Token. These details are included in every request to the server:

  • Company’s UID – used as part of the restful url.
  • Company’s Token – added as a query parameter called token to every request.

Endpoint

The current endpoint is as follows, it supports only https requests.

https://www.comeet.co/careers-api/2.0

Sample Request

GET https://www.comeet.co/careers-api/2.0/company/COMPANY-UID/positions?token=YOUR-TOKEN
 
Suggest Edits

Position Model

 
Field
Type
Description

uid

string

Position UID

name

string

department

string

email

string

Position’s email – candidates can send resume to this email address to apply for this position.

url_comeet_hosted_page

string

URL of the position’s page on the Comee-hosted website. It is possible to refer applicants to this web page.

url_active_page

string

URL of the current position’s page according to the position’s settings. Could be either on the company’s website or on the Comeet-hosted website. It is possible to refer applicants to this web page.

employment_type

string

experience_level

string

internal_use_custom_id

string

The position’s id as defined by the company (not to be confused with the UID of the position).

picture_url

string

Url of the public position image for display and sharing on social media

time_updated

timestamp

company_name

string

location

object

location.name

string

location.country

string

location.city

string

location.state

string

location.postal_code

string

location.street_name

string

location.arrival_instructions

string

location.street_number

string

location.timezone

string

categories

array

Custom categories.

categories[].name

string

categories[].value

string

categories[].order

int

details

array

Free-form text details.

details[].name

string

details[].value

string

HTML

details[].order

int

{  
  "uid":"87.405",
  "name":"Account Executive, Austin",
  "department":"Sales",
  "email":"companyname.87.405@applynow.io",
  "url_comeet_hosted_page":"https://www.comeet.co/jobs/companyname/30.005/account-executive-austin/87.405",
  "url_active_page":"https://www.comeet.co/jobs/companyname/30.005/account-executive-austin/87.405",
  "employment_type":"Full-time",
  "experience_level":"Intermediate",
  "internal_use_custom_id":null,
  "picture_url":"https://comeet-euw-app.s3.amazonaws.com/53/b5ac4af700dfe6d749a862f7ba267f288f6cb575",
  "time_updated":"2017-05-26T14:22:46Z",
  "company_name":"Company Name",
  "position_url":"https://www.comeet.co/careers-api/2.0/company/30.005/positions/87.405?token=359F1DD13E1DD1DD1A813E6A6A",
  "location":{  
    "name":"Austin, TX",
    "country":"US",
    "city":"Austin",
    "state":"TX",
    "postal_code":"",
    "street_name":"",
    "arrival_instructions":null,
    "street_number":"",
    "timezone":"America/Iqaluit"
  },
  "categories":[  
    {  
      "name":"Territory",
      "value":"USA",
      "order":1
    }
    //...
  ],
  "details":[  
    {  
      "name":"Description",
      "value":"We are looking for ...",
      "order":1
    },
    {  
      "name":"Requirements",
      "value":"Candidates should have ...",
      "order":2
    }
    //,,,
  ]
}
Suggest Edits

/{company_uid}/positions

The list of published positions of the company. Make sure there are a few published positions otherwise the returned data set will be empty.

Returns a list of Positions.

 
gethttps://www.comeet.co/careers-api/2.0/company/company_uid/positions

Path Params

{company_uid}
string
required

Query Params

token
string
required

Company's token

details
boolean

When true all position information is included in the response including the description, requirements and custom fields

To receive the position's description fields, such as job description and requirements, set the details parameter to True. By default, these fields are not included in the response.

When making a request to get the list of positions, set the timeout limit to 60 seconds. This will ensure that the request doesn't fail in case it takes a few seconds to retrieve a large number of positions.

No code samples available
A binary file was returned

You couldn't be authenticated

No response examples available
[
   {
   "uid": "87.405",
   "name": "Account Executive, Austin",
   "department": "Sales",
   "email": "companyname.87.405@applynow.io",
   "location": {
      "name": "Austin, TX",
      "country": "US",
      "city": "Austin",
      "state": "TX",
      "postal_code": "",
      "street_name": "",
      "arrival_instructions": null,
      "street_number": "",
      "timezone": "America/Iqaluit"
   },
   "url_comeet_hosted_page": "https://www.comeet.co/jobs/companyname/30.005/account-executive-austin/87.405",
   "url_active_page": "https://www.comeet.co/jobs/companyname/30.005/account-executive-austin/87.405",
   "employment_type": "Full-time",
   "experience_level": "Intermediate",
   "internal_use_custom_id": null,
   "picture_url": "https://comeet-euw-app.s3.amazonaws.com/53/b5ac4af700dfe6d749a862f7ba267f288f6cb575",
   "time_updated": "2017-05-26T14:22:46Z",
   "company_name": "Company Name",
   "position_url": "https://www.comeet.co/careers-api/2.0/company/30.005/positions/87.405?token=359F1DD13E1DD1DD1A813E6A6A",
   "categories": [{
      "name": "Territory",
      "value": "USA",
      "order": 1
   }]
   },
   ...
]
Suggest Edits

/{company_uid}/positions/{position_uid}

Returns a Position.

 
gethttps://www.comeet.co/careers-api/2.0/company/company_uid/positions/position_uid

Path Params

{company_uid}
string
required

Query Params

token
string
required

Company's token

details
boolean

When true all position information is included in the response including the description, requirements and custom fields

To receive the position's description fields, such as job description and requirements, set the details parameter to True. By default, these fields are not included in the response.

No code samples available
A binary file was returned

You couldn't be authenticated

No response examples available
{
   "uid": "87.405",
   "name": "Account Executive, Austin",
   "department": "Sales",
   "email": "companyname.87.405@applynow.io",
   "url_comeet_hosted_page": "https://www.comeet.co/jobs/companyname/30.005/account-executive-austin/87.405",
   "url_active_page": "https://www.comeet.co/jobs/companyname/30.005/account-executive-austin/87.405",
   "employment_type": "Full-time",
   "experience_level": "Intermediate",
   "internal_use_custom_id": null,
   "picture_url": "https://comeet-euw-app.s3.amazonaws.com/53/b5ac4af700dfe6d749a862f7ba267f288f6cb575",
   "time_updated": "2017-05-26T14:22:46Z",
   "company_name": "Company Name",
   "position_url": "https://www.comeet.co/careers-api/2.0/company/30.005/positions/87.405?token=359F1DD13E1DD1DD1A813E6A6A",
   "location": {
      "name": "Austin, TX",
      "country": "US",
      "city": "Austin",
      "state": "TX",
      "postal_code": "",
      "street_name": "",
      "arrival_instructions": null,
      "street_number": "",
      "timezone": "America/Iqaluit"
   },
   "categories": [{
      "name": "Territory",
      "value": "USA",
      "order": 1
   }
   //... more category fields
   ],
   "details": [{
      "name": "Description",
      "value": "We are looking for ...",
      "order": 1
   },{
      "name": "Requirements",
      "value": "Candidates should have ...",
      "order": 2
   }
   //... more detail fields
   ]
 }
Suggest Edits

Sharing Best Practices

 

Render your careers pages on the server side to support proper sharing on social networks and include the social meta tags.

The careers website is an opportunity to allow users and employees to share the company’s positions on social networks such as Facebook and LinkedIn. To maximize sharing, include meta tags in your html that include the position name, description and other information that should be available in the post. To enable social networks to read tags properly, the pages should be rendered on the server side—not on the client side.

See the list of meta tags suggested by Facebook – Facebook’s Content Sharing Best Practices.

 
Suggest Edits

Closed Positions

 

When building your careers website, keep in mind that applicants may click a link to a position that has been closed. This not-uncommon situation requires proper handling of URLs of unknown positions (closed positions will no longer appear in the positions list), usually by redirecting the visitors to the positions list.

 
Suggest Edits

Embedding Widgets

 

Comeet allows you to embed several types of widgets:

  • Application Form – applicants can use Comeet’s rich functionality to apply for positions on your website.
  • Social – leverage employee referral programs by easily enabling company employees to share positions on social media and automatically track their referrals.
  • Careers Website – quickly embed the complete careers website functionality into your website.

To support any of these widgets, start by adding the following code to your page in the <head> section. Place your configuration parameters in the configuration object. You can add parameters to your configuration as required. See full list of parameters below.

To enable Comeet to track candidate sources properly (the website from which the applicant arrived at your website), add this code to every pages on your website.

<script>
   window.comeetInit = function() {
      COMEET.init({
         "token":       "-- your token --",
         "company-uid": "-- your company uid ---",
         "company-name":"-- your company name ---",
         "color":       "278fe6", //optional
         "font-size":   "13px" //optional
         //add more parameters here
      });
   };
 
   (function(d, s, id) {var js, fjs = d.getElementsByTagName(s)[0]; if (d.getElementById(id)) {return; } js = d.createElement(s); js.id = id;
   js.src = "//www.comeet.co/careers-api/api.js"; fjs.parentNode.insertBefore(js, fjs); }(document, 'script', 'comeet-jsapi'));
</script>

The following parameters can be added to the configuration. NOTE: parameters added directly to widgets can override those in the <head> section of your page.

Context:

Name
Description
Required

token

Company token

required

company-uid

Company UID

required

position-uid

Position UID

required

thankyou-url

After applying, the applicants will be redirected to the specified url. This setting can only be set up during initialization

optional

Style:

Name
Description
Required

css-url

URL to custom CSS file for customizing the widgets

optional

css-cache

When developing your CSS, you may want to set this value to false to prevent the widget from using the cached CSS. Default is true

optional

color

Leading color for buttons and links. Default is 278fe6

optional

background-color

Background color for the form. Default is white

optional

button-color

Color for the button. Defaults to the value of color above

optional

font-size

Font-size used. Default is 13px

optional

button-font-size

Font size of buttons if you want it different from the text. Defaults to the value of font-size above

optional

Colors

Button and link colors should be dark enough to permit readability. If you choose a light color you may see it rendered as a darker color than the given one.

 
Suggest Edits

Application Form Widget

 

To provide candidates with access to Comeet’s rich functionality when applying for positions on your website, you can embed our form directly into the page. Please follow these steps:

  1. Make sure you have Comeet’s API embedded in the <HEAD> of your page. If you haven’t done so already, get it here .

  2. To inject the application form, add this code where you want the form to appear. Place your configuration parameters as shown with the “data-” prefix.

<script type="comeet-applyform" data-position-uid="position_uid"></script>

NOTE: The application form widget must be embedded on the main page and not within an iframe.

Configuration Parameters

The following parameters are available in both the <head> section and in the form injection code. Note: The parameters in the injection code can override those in the <head> section.

Colors

Button and link colors should be dark enough to permit readability. If you choose a light color you may see it rendered as a darker color than the given one.

Context:

Name
Description
Required

token

Company token

required

company-uid

Company UID

required

position-uid

Position UID

required

thankyou-url

After applying, the applicants will be redirected to the specified URL. This setting can only be set up during initialization

optional

apply-as-employee

When enabled, employees are given the option to “Apply as an employee.” Source will be noted as “Employees” and source type as “Internal Mobility.” Defaults to true

optional

Fields:

Name
Description
Required

field-email-required

Require email address? Defaults to true for candidates and false for referrals,

optional

field-phone-required

Require phone? Defaults to true for candidates and false for referrals.

optional

field-resume

Show the option to attach resume? Defaults to true.

optional

field-linkedin

Enable LinkedIn? Defaults to true.

optional

require-profile

Which profile is required? Defaults to "resume”, also accepts “linkedin”, “resume-linkedin” (require both), “any” (either resume or LinkedIn), “none” (both are optional).

optional

field-website

Show website field? Defaults to false.

optional

field-website-required

Require website? Defaults to false.

optional

field-coverletter

Show cover letter field? Defaults to true.

optional

field-coverletter-required

Require cover letter? Defaults to false.

optional

field-portfolio

Show portfolio field? Defaults to true.

optional

field-portfolio-required

Require portfolio? Defaults to false.

optional

field-personalnote

Show personal note field? Defaults to true.

optional

field-personalnote-required

Require personal note? Defaults to false.

optional

Style:

Name
Description
Required

css-url

URL to a custom CSS file for customizing the widget.

optional

css-cache

When developing your CSS, you may want to set this value to false to prevent the widget from using the cached CSS. Default is true.

optional

color

Leading color for buttons and links. Default is 278fe6.

optional

background-color

Background color for the form. Default is white.

optional

button-color

Color for the button.

optional

button-text

Text to display on the submit button. Default is “Submit Application”.

optional

font-size

Font-size to use. Default is 13px.

optional

button-font-size

Font-size for buttons if you wish to set it to a different size than the text. Default is font-size value above.

optional

labels-position

Where to place the labels? Defaults to “responsive”, also accepts “left”, ”top”.

optional

Alternative Options

There are other alternatives you can provide to candidates so they can apply for jobs.

Position email address

Each position has a dedicated email address. Candidates can send resumes to this email to apply for that position.

A simple link example:

<a href="mailto:email_name?subject=Apply to job">Apply</a>

Position page

Each position has it’s own web page on the company’s careers website. The page displays information about the position and includes an application form. Using the form, candidates can apply with their LinkedIn profile or upload a resume and cover letter..

The url for the position page is noted as careers_page_url in the position details.

Known limitation of the Facebook app for iPhone/iPad

Due to this app's limited functionality, it is not possible to attach a resume and other files. Applicants visiting the position page using this app will have the option of using a LinkedIn profile to apply, submitting their resume by email or visiting the position page in a web browser.

 
Suggest Edits

Social Widget

 

Goal

The Social Widget API is a part of Comeet’s Employee Referrals program. The widget helps you cast a wider net by leveraging your employees’ connections and friends to find better candidates. Depending on your company's policies and what you specify in the position settings, employees may be rewarded with bonuses offered for successful referrals.

When an employee shares the careers website or an open position, a unique trackable link is included. Should someone apply using it, the employee will be automatically recognized as the referrer and attributed as that candidate's source. Employees can also submit referrals online by simply providing their contact details.

Just getting started with referrals? Learn more in the guide to Comeet’s Employee Referrals.

Prerequisites

  1. The API should be enabled for your company. Refer to Company Settings in Comeet for instructions.
  2. You should have your company’s uid and token, also found in Company Settings in Comeet.
  3. Comeet’s API should be embedded in the <HEAD> of your web page. For more information, read here.

Track referrals from LinkedIn posts

Comeet tracks referrals made by employees in the company by using a trackable link. This link includes the coref parameter which identifies the employee who posted the position on social media.
When sharing the trackable link on LinkedIn, LinkedIn reads the page and looks for the canonical link and the OG:URL element in the <head> of the page. If these elements are included in the page but the specified URL does not include the coref parameter then referral tracking will not work. To overcome this behavior, you can either omit the canonical link and OG:URL elements from your page, or render the canonical link and OG:URL element on the server side and include the coref parameter that was specified in the request. For example:
<link rel="canonical" href="https://company.com/careers/product-manager?coref=xxx.xx.xx" />
<meta property="og:url" content="https://company.com/careers/product-manager?coref=xxx.xx.xx"/>

If you use the Comeet WordPress plugin then this logic is already handled by the plugin (starting from version 2.0.6.1).

Usage

Embed the social widget by adding this code where you want the widget to appear. Place your configuration parameters as shown with the “data-” prefix.

This widget can work with or without the position’s uid.

<script type="comeet-social" data-position-uid="POSITION UID GOES HERE"></script>

Configuration Parameters

The following parameters are available in both the <head> section and in the form injection code. NOTE: The parameters in the injection code can override those in the <head> section.

Colors

Button and link colors should be dark enough to permit readability. If you choose a light color you may see it rendered as a darker color than the given one.

Context:

Name
Description
Required

token

Company token

required

company-uid

Company UID

required

position-uid

Position UID

required

Customize:

Name
Description
Required

social-pinterest

Show the Pinterest button? Defaults to true.

optional

social-whatsapp

Show the WhatsApp button? Defaults to false.

optional

social-employees

Enable support for employees? Defaults to true.

optional

social-show-title

Show a title? Defaults to true.

optional

social-share-url

Override the URL to share. Defaults to the page URL.

optional

Style:

Name
Description
Required

css-url

URL to a custom CSS file for customizing the widget.

optional

css-cache

When developing your CSS, you may want to set this value to false to prevent the widget from using the cached CSS. Default is true.

optional

social-color

Which colors to use?
“white” (default) – White background, native social network color on hover
“native” – Native social network color.

optional

color

Leading color for buttons and links. Default is 278fe6.

optional

background-color

Background color for the form. Default is white.

optional

button-color

Color for the button.

optional

font-size

Font-size to use. Default is 13px.

optional

What it looks like

“color”: “ca2027”

“color”: “ca2027”

“social-show-title”: “false”

“social-show-title”: “false”

“social-color”: “native”

“social-color”: “native”

“social-show-title”: “false”
“social-employees”: “false”
“social-color”: “native”

“social-show-title”: “false”
“social-employees”: “false”
“social-color”: “native”

“social-color”: “native”
“social-networks”: “basic”

“social-color”: “native”
“social-networks”: “basic”

 
Suggest Edits

Careers Website Widget

 

Goal

Quickly embed the complete careers website functionality in your website without any customization.

If you want to customize your careers website, please refer to the Careers API to retrieve position data and render pages on your server.

Prerequisites

  1. The API should be enabled for your company. Refer to Company Settings in Comeet for instructions.
  2. You should have your company’s uid and token, also found in Company Settings in Comeet.
  3. Comeet’s API should be embedded in the <HEAD> of your web page. For more information, read here.

Usage

Embed the careers website widget by adding this code where you want the widget to appear.

<script>
      window.comeetInit = function() {
         COMEET.init({
            "token":       "your.company.token",
            "company-uid": "your.company.UID",
            "company-name":"your.company.name"
            //add more parameters here
         });
      };
 
      (function(d, s, id) {var js, fjs = d.getElementsByTagName(s)[0]; if (d.getElementById(id)) {return; } js = d.createElement(s); js.id = id;
      js.src = "//www.comeet.co/careers-api/api.js"; fjs.parentNode.insertBefore(js, fjs); }(document, 'script', 'comeet-jsapi'));
</script>
<script type="comeet-careers"></script>
 
Suggest Edits

Using Custom CSS

 

You can customize the widgets' look and feel by using the parameters listed for each one. If you want to customize the design beyond the supported options, you may use your own custom CSS. This is done by providing the following params:

  • css-url – Absolute URL to CSS file. This file must be publicly accessible as it needs to be read by Comeet's system.
  • css-cache – When developing your CSS, you may want to set this value to false to prevent the widget from using a cached version of the CSS file.

IMPORTANT: Write stable CSS

As Comeet's widgets may change from time to time, it is important that your custom styles not break the layout of your widgets. Follow these guidelines when writing your CSS:

  • Do not use CSS selectors that rely on the order of elements or on any attribute other than ID or Class
  • CSS selectors may use IDs of elements, such as: #copyLink or #inputFirstName
  • CSS selectors may use the following element classes: .control-label, .form-group, .field-* (any class of a field), .submit-button, .shareTitle, .shareButton
 
Suggest Edits

Employee Portal (BETA)

 

Comeet's widgets can be embedded in an internal portal for employees. Use these parameters to provide a great experience to employees browsing the open positions on your portal. When used, Comeet will have their details and they won’t have to input their information.

Name
Description
Required

is-employee

true or false. When true, the visitor is required to be identified as an employee.
If the employee-fullname and employee-email are not provided, a pop-up window will request their name and work email. Default is false

optional

employee-fullname

Provide this parameter along with the employee-email so employees don’t have to input their information

optional

employee-email

Provide this parameter along with the employee-fullname so employees don’t have to input their information

optional

 
Suggest Edits

Wix Website Integration

 

Goal

Integrate your Wix website with Comeet and enjoy the following key benefits:

  1. Everything remains in sync
    Your careers website will remain in sync with the positions’ status and details in Comeet.

  2. Streamlined application process
    Candidates can easily apply from desktop or mobile with their resume or LinkedIn profile.

  3. Automated source attribution
    Candidate sources are tracked automatically.

  4. Powerful employee referral program
    Comprehensive referral program functionality has everything you need to tap into your employees’ networks.

  5. Fast and efficient screening
    Questionnaires will help you screen candidates faster while completely eliminating poor matches at top of funnel.

Prerequisites

Before you get started, ensure that you have:

  1. At least one position's visibility set to Published or Published (Restricted).
  2. The company's UID and Token. You can retrieve them from the Careers Website settings page.

Managing company settings is available for users with a role of HR Admin or IT Admin.

Usage

You can use our embedded careers website by creating a Wix box with the following HTML code:

<!DOCTYPE html>
<html>
<head>
<title></title>
</head>
<body>
    <script>
      window.comeetInit = function() {
         COMEET.init({
            "token":       "your.company.token",
            "company-uid": "your.company.UID",
            "company-name":"your.company.name"
            //add more parameters here
         });
      };
 
      (function(d, s, id) {var js, fjs = d.getElementsByTagName(s)[0]; if (d.getElementById(id)) {return; } js = d.createElement(s); js.id = id;
      js.src = "//www.comeet.co/careers-api/api.js"; fjs.parentNode.insertBefore(js, fjs); }(document, 'script', 'comeet-jsapi'));
    </script>
    <script type="comeet-careers"></script>
</body>
</html>

Due to restrictions on executing scripts on the main page, the employee referral program and “Apply as an employee” features are not supported on a Wix based website.
We offer other integration options that enable this functionality. Learn more here.

 
Suggest Edits

Wordpress Plugin

 

This plug-in is available to anyone who uses the Comeet recruiting platform and wants to showcase their career opportunities on a WordPress site.

Plugin on GitHub

This plugin is provided as-is. We do not provide support for its installation on individual websites. We invite you to post feature requests and report problems on the plug-in’s page on GitHub.

 

I get an error: “Company public API is not enabled”

The API is disabled by default. The company’s admin in Comeet (usually the head of recruitment) can visit the settings at Company Settings > Careers Website and check Enable API.

I don’t see any positions, or only a few

The API only returns positions that are set to Published. The company’s recruiters have permission to set positions from Not published to Published.

I make changes to a position but they are not reflected in the results from the API

It may take a couple of minutes for the changes you make to appear in the data returned by the API.

Where do I find the company identifiers – UID and token?

You can find these details in Comeet under Company Settings > Careers Website. These settings are available to the company’s admin (usually the head of recruitment). While you’re there, make sure the Enable API option is checked.

Have more questions? Contact us at support@comeet.co.


 
Suggest Edits

Hires API

 
 
 
Suggest Edits

API Overview

 

This API enables you to be notified when a candidate is hired on Comeet. This is useful for HRIS and talent management systems that manage employee data.

To begin the integration process, contact us at partners@comeet.co and we’ll provide you with details for a sandbox account.

 
Suggest Edits

Webhook for Hire Event

 

The integration uses the form of a webhook. Defining the webhook requires two values:

  • Endpoint URL – Each time a hire is made in Comeet, the new employee’s data is sent via a POST request to this specified endpoint URL over HTTPS. If you plan to support multiple companies using Comeet, make sure to provide a URL that includes a unique identifier of the user or company.
  • Secret Key – When defined, the key is used to generate a digital signature using the SHA256 algorithm on the sent data. The signature is included in the HTTP header signature allowing you to verify Comeet as the sender.
    To configure this integration in Comeet, a user with Admin privileges specifies these values in the Integrations page.
 
Suggest Edits

Webhook Request

 

The POST request contains a candidate's data under the following structure:

Request

Field
Type
Description

comeet_id

string

Unique candidate ID

first_name

string

middle_name

string

last_name

string

email

string

time_created

timestamp

YYYY-MM-DDTHH:mm:ssZ

phone

string

mobile_phone

string

id_number

string

linkedin_url

string

source

object

Data about the candidate's source, NULL if the candidate doesn't have a source

source.name

string

source.type

string

source.comeet_id

string

Unique source ID

resume

object

resume.name

string

resume.url

string

A public URL for the candidate resume. The link will expire three minutes after being delivered.

picture

object

picture.url

string

A public URL for the candidate profile picture. The link will expire 200 seconds after being delivered.

links

array

links[].url

string

files[]

array

files[].name

string

files[].url

string

files[].type

string

Only files of type "offer_letter" are supported

opening.description

opening.reason

position

object

position.comeet_id

string

Unique positions ID

position.name

string

position.department

string

position.position_id

string

The position id that was set by the costumer. may also be null or empty string. Not to be confused with position.comeet_id

position.location

string

position.employment

string

position.seniority

string

position.hiring_manager

object

position.hiring_manager.first_name

string

position.hiring_manager.last_name

string

position.hiring_manager.email

string

position.custom_fields

object

Key-value pairs of public custom position category fields. Note that default fields (department, location, etc) are part of the position object

custom_fields

object

Key-value pairs of custom candidate fields

Response

Expecting HTTP 200. In case of an error, make sure to include a clear and actionable description of the problem in the response shown to the user.

{  
  "comeet_id":"19E.98",
  "first_name":"Bobby",
  "middle_name":"Robert",
  "last_name":"Chauck",
  "email":"bobby.c@example.com",
  "time_created":"2016-08-10T13:30:02Z",
  "phone":"07-4442321",
  "mobile_phone":"052-8644246",
  "id_number":"5454-2233-1",
  "linkedin_url":"https://www.linkedin.com/in/bobby-hauck-06b0735",
  "hired_date":"2016-10-16",
  "start_date":"2016-10-23",
  "source":{  
    "name":"JobmeHR",
    "type":"Agency",
    "comeet_id":"101E.27"
  },
  "resume":{  
    "name":"bobby_cv.docx",
    "url":"https://comeet-euw-qa.s3-eu-west-1.amazonaws.com/65c0a9ff2166g"
  },
  "picture":{  
    "url":"https://comeet-euw-qa.s3-eu-west-1.amazonaws.com/e43123cff1231g0"
  },
  "links":[  
    {  
      "url":"http://www.personalportfolio.com"
    }
  ],
  "files": [
    {
      "name": "Offer letter.pdf",
      "url": "https://comeet-euw-qa.s3-eu-west-1.amazonaws.com/e4376598f1231g0",
      "type": "offer_letter"
    }
  ],
  "opening": {
       "description": "For team A",
       "reason": "new",
  },
  "position":{  
    "comeet_id":"34D.98",
    "name":"Automation QA",
    "department":"R&D",
    "position_id": "AQA_011",
    "location": "New York",
    "employment": "Full-time",
    "seniority": "Senior",
    "hiring_manager":{  
      "first_name":"David",
      "last_name":"Black",
      "email":"david.black@example.com"
    },
    "custom_fields":{  
      "custom field":"value",
      "custom field 2":"value 2",
      ...
    }
  },
  "custom_fields":{  
    "custom field":"value",
    "custom field 2":"value 2",
    ...
  }
}
Suggest Edits

Test Request

 

The endpoint for the webhook should support a request to test the connection. This request is executed when the user adds the webhook information to confirm that both the URL and Secret Key were entered correctly.

Request

POST request for the same endpoint with the following variation:

  • The payload is an empty object: {}
  • Query string parameter test_connection=true is added to the URL

Response

Expecting HTTP 200. In case of an error, include a clear and actionable description of the problem in the response shown to the user.

 
Suggest Edits

Handling Errors

 

The creation of a new employee in the talent management system is synchronous. In case of an error, the user will see an error message in Comeet and will not be able to change the candidate's status to Hired until the problem's resolution. Your application is expected to handle errors using the following guidelines:

  • When an error is returned, the new employee must not be created in your application

  • Use HTTP code of 4XX for bad requests, such as conflicts, missing data or a authorization problem

  • Show the users a clear message explaining the cause of the error and suggestions for resolving it. Include the message to the user in the display_message property as part of the response payload.

  • The response payload should include any additional information that would help a technical person investigate the problem. These details will be available to the user by clicking on "Technical details" in the error window in Comeet.

Have more questions? Contact us at support@comeet.co.

{
  //Message to the user
  "display_message": "Explain the problem and ways to resolve"

  //Additional details for a technical person go here
}
Suggest Edits

Sourcing API

 
 
 
Suggest Edits

API Overview

 

The Sourcing API allows an external tool to retrieve a list of positions, add candidates to these positions and retrieve the recruiting status of the added candidates.

The available endpoints are:

1. Candidates

2. Positions

We are looking forward to seeing what you will build using the Comeet Sourcing API!

 
Suggest Edits

Intended Audience

 

1. Providers of recruiting tools

Providers of recruiting tools that help companies find matching candidates can offer their service to Comeet users through this API. If you are interested in becoming a partner please contact us by following the instructions below.

2. Comeet customers

Comeet users who wish to use this API's capabilities can create a custom Sourcing App. To do so, please contact your Dedicated Customer Success Manager (available to customers with the Enterprise plan).

 
Suggest Edits

Getting Access - Become a Partner

 
  1. Submit the Become a Partner Form. You will be requested to submit the following information:

    • Your contact details - name, email, role and company name
    • Your app - name, description, logo and website URL
    • Promotion - You may want to offer a promotion to Comeet customers to grab their attention as a new app to the Comeet platform. If you do, we'll make it visible to recruiters using Comeet. Explain the offering and, optionally, add a URL for a page that allows users to take advantage of the promotion.
    • Activation page - You can make activation easier for Comeet users by creating an activation page for them. Instead of asking users to copy and paste the API Key, users will click on an "Activate" button in Comeet to open the URL of your page. This URL will include the API Key. Please visit the API's reference for more details.
    • API Terms of Use - By using this API, you agree to the Comeet API Terms of Use.
  2. Once the submission is approved, we will send you your secret and invite you to your Sandbox account. Sign up to your Sandbox account and retrieve the API Key for that account from the Job Boards & Apps setting page.

  3. Develop the integration. When ready, send us a short video that demonstrates the integration including all the steps described in the Example Scenario below.

  4. We'll review the submitted video. Once approved, we'll provide you the secret to the production environment to be used with https://api.comeet.co.

 
Suggest Edits

Example Scenario

 
  1. Set up the integration - this is a one-time step:

    1. A Comeet user with an Admin role will find your service on our Sourcing Apps page and click Integrate.
    2. The user selects the positions that will be shared through the API.
    3. If you provided activation url then the user clicks the Activate button which opens the url you provided. The request will include the api-key of the Comeet account and the Signature that allows you to verify that the request was made by Comeet. Alternatively, if you don't provide the activation url the user will click on Copy Key and will manually input the API Key in your app (ie. by pasting in the product or sending to a support rep).

The provided access is at the level of the account (the company) in Comeet. It is not possible to provide access on the user's level.

  1. Request to retrieve the list of positions.

  2. Add candidate to a position.

  3. Retrieve candidate status.

This request can be executed periodically to update the candidate's status as long as the candidate is still under consideration.

 
Suggest Edits

Authorization

 

All API calls must use HTTPS and be authorized. Here are the required steps:

  1. To authorize a request you need these values:

    • secret - received when approved as a Comeet partner. See Getting Access - Become a Partner)
    • api-key - received from a Comeet customer when the integration is activated.
  2. Generate a token by encoding the account's api-key with your secret using JWT. You can use one of the many JWT libraries available, see on the right an example using pyjwt.

  3. Include the Authorization header with all of your HTTP requests using the syntax:
    Authorization: Bearer <token>

import jwt
import time

expiration_time = time.time() + 600 # 10 minutes
token = jwt.encode({'iss': 'API_KEY', 'exp': expiration_time},
                   'API_SECRET',
                   algorithm='HS256')
Suggest Edits

Timestamp Format

 

Comeet works with timestamps as strings using the format: YYYY-MM-DDTHH:mm:ssZ.

 
Suggest Edits

Error Responses

 

If you make an invalid request, you will receive a detailed error response with one of the following error codes.

Error
Status code
Message

required_field

400

You must include this required field: "[field name]"

string_size_limit

400

The provided value for "[property name]" exceeds the limit of [X] characters: "[value]"

invalid_email

400

The provided email address is invalid: "[email]"

invalid_linkedin_url

400

The provided LinkedIn URL is invalid: "[linkedin_url]"

invalid_url

400

The provided URL is invalid: "[url]"

source_contact_conflict

400

The provided email address of the source contact already exists and belongs to another source: "[source contact email address]"

incorrect_country_code

400

The provided country code does not conform to ISO 3166: "[country code]"

invalid_custom_candidate_field

400

The provided custom candidate field "[custom candidate field name]" does not exist

invalid_datetime

400

The provided time format is invalid: "[provided datetime string]"

file_size_limit

403

The provided file exceeds size limit of [X]MB: "[file name]"

malicious_file

403

The provided file cannot be accepted due to the company's security policy: "[file name]"

no_permission

403

You do not have permission to perform this action

position_not_found

404

The provided position id was not found at the specified account

not_found

404

The provided ID could not be found

candidate_post_conflict

409

You are trying to create a candidate with partner_candidate_id that already exists in the same position with status In progress

too_many_requests

429

You have reached your allowed limit of [X] requests per 60 seconds

{  
  "status": 409,
  "error": "candidate_post_conflict",
  "message": "Candidate with provided partner_candidate_id already exists in position with status in progress",
  "candidate_uid": 5555
}
Suggest Edits

Candidate Model

 
Field
Type
Description

uid

string

Candidate UID

deleted

boolean

Indicates whether the candidate has been deleted. When true the candidate object will only include the uid

position_uid

string

Position UID

source_contact

object

source_contact.full_name

string

source_contact.email

string

source_contact.phone

string

time_created

string

Format: YYYY-MM-DDTHH:mm:ssZ

time_last_status_changed

string

Format: YYYY-MM-DDTHH:mm:ssZ

current_steps[]

array

If the candidate is In progress then this is the array of the current steps that the candidate is waiting for. If the candidate is in any other status then the array is empty.

current_steps[].name

string

current_steps[].type

string

One of the following:

  • Go/No-go
  • Phone Interview
  • Video Interview
  • In person Interview
  • Assessment
  • Administrative
  • Offer

current_steps[].time_scheduled

string

Time of scheduled interview. Format: YYYY-MM-DDTHH:mm:ssZ

completed_steps[]

array

completed_steps[].name

string

completed_steps[].type

string

One of the following:

  • Go/No-go
  • Phone Interview
  • Video Interview
  • In person Interview
  • Administrative
  • Assessment
  • Offer

completed_steps.time_scheduled

string

Format: YYYY-MM-DDTHH:mm:ssZ

completed_steps[].time_completed

string

Format: YYYY-MM-DDTHH:mm:ssZ

status

string

One of the following:

  • In progress
  • On hold
  • Awaiting Decision
  • Rejected
  • Withdrawn
  • Hired

time_last_status_change

string

Format: YYYY-MM-DDTHH:mm:ssZ

resume

object

The resume object is only included when a dedicated permission is granted

resume.name

string

resume.url

string

Note that the URL to the resume file has a time limit of about an hour. If it expires, read the candidate object again to refresh the URL

address

object

address.country

string

address.state

string

address.zip

string

address.street_address

string

address.city

string

{  
  "uid": "00.AAA",
  "deleted": false,
  "position_uid": "11.11",
  "source_contact": {  
    "full_name": "Michael Rosen",
    "email": "michael.rosen@source.com",
    "phone": "555 555 1234"
  },
  "time_created": "2018-01-01T12:50:50Z",
  "time_last_status_change": "2018-01-01T12:50:50Z",
  "current_steps": [  
    {  
      "name": "Technical interview",
      "type": "In person Interview",
      "time_scheduled": "2018-01-01T12:50:50Z"
    }
    //...
  ],
  "completed_steps": [  
    {  
      "name": "CV Screen",
      "type": "Go/No-go",
      "time_scheduled": "2018-01-01T12:50:50Z",
      "time_completed": "2018-03-03T12:50:50Z"
    }
    //...
  ],
  "status": "In progress",
  "resume": {  
    "name":"michael_rosen_cv.docx",
    "url":"https://comeet-xxx.amazonaws.com/65c0a9ff2166g"
  },
  "address":{
    "country": "US",
    "state": "NY",
    "zip": "11249",
    "street_address": "109 S 5th St",
    "city": "Brooklyn"
  }    
}
Suggest Edits

Position Model

 
Field
Type
Description

uid

string

Position UID

name

string

status

string

One of the following:

  • "open"
  • "on-hold"
  • "closed"

internal_name

string

department

string

email

string

Position’s email – candidates can send resume to this email address to apply for this position.

url_comeet_hosted_page

string

URL of the position’s page on the Comeet-hosted website. It is possible to refer applicants to this web page.

url_active_page

string

URL of the current position’s page according to the position’s settings. Could be either on the company’s website or on the Comeet-hosted website. It is possible to refer applicants to this web page.

experience_level

string

internal_use_custom_id

string

The position’s id as defined by the company (not to be confused with the UID of the position).

picture_url

string

URL for the public position image for display and share on social media

time_updated

timestamp

company_name

string

position_url

string

URL for receiving the position object through the API

location

object

location.name

string

location.country

string

location.city

string

location.state

string

location.postal_code

string

location.street_name

string

location.arrival_instructions

string

location.street_number

string

location.timezone

string

location.uid

string

categories

array

Custom categories.

categories[].name

string

categories[].value

string

categories[].order

int

details

array

Free-form text details.

details[].name

string

details[].value

string

HTML

details[].order

int

{  
  "uid":"87.405",
  "name":"Account Executive, Austin",
  "status": "open",
  "department":"Sales",
  "email":"companyname.87.405@applynow.io",
  "url_comeet_hosted_page":"https://www.comeet.co/jobs/companyname/30.005/account-executive-austin/87.405",
  "url_active_page":"https://www.comeet.co/jobs/companyname/30.005/account-executive-austin/87.405",
  "employment_type":"Full-time",
  "experience_level":"Intermediate",
  "internal_use_custom_id":null,
  "picture_url":"https://comeet-euw-app.s3.amazonaws.com/53/b5ac4af700dfe6d749a862f7ba267f288f6cb575",
  "time_updated":"2017-05-26T14:22:46Z",
  "company_name":"Company Name",
  "position_url":"https://www.comeet.co/careers-api/2.0/company/30.005/positions/87.405?token=359F1DD13E1DD1DD1A813E6A6A",
  "location":{  
    "name":"Austin, TX",
    "country":"US",
    "city":"Austin",
    "state":"TX",
    "postal_code":"",
    "street_name":"",
    "arrival_instructions":null,
    "street_number":"",
    "timezone":"America/Iqaluit",
    "uid": "D00.000"
  },
  "categories":[  
    {  
      "name":"Territory",
      "value":"USA",
      "order":1
    }
    //...
  ],
  "details":[  
    {  
      "name":"Description",
      "value":"We are looking for ...",
      "order":1
    },
    {  
      "name":"Requirements",
      "value":"Candidates should have ...",
      "order":2
    }
    //,,,
  ]
}
Suggest Edits

/candidates

Creates new candidate for a specified position. Returns the Candidate.

 
posthttps://api.comeet.co/sourcing/candidates

Body Params

position_uid
string
required

The UID of the position to which the candidate should be added

partner_candidate_id
string
required

Unique ID of the candidate on the partner's system

first_name
string
required
middle_name
string
last_name
string
required
email
string
phone
string
mobile_phone
string
national_id
string
linkedin_url
string
salary_expectations
string

Access to this field is restricted in Comeet (BETA)

resume
object
resume.name
string
resume.file
string

Base64 representation of the resume in one of the following formats: PDF, DOC, DOCX

picture
object

Profile photo

picture.name
string
picture.file
string

Base64 representation of the file contents

links
array of objects
files
array of objects
source_contact
object

Include the source contact if your app aggregates multiple sources. For example, use this object to include the details headhunter who submitted the candidate

source_contact.full_name
string
source_contact.email
string
source_contact.phone
string
address
object
address.country
string
address.city
string
address.state
string
address.zip
string
address.street
string
custom_fields
object

Key-value pairs of custom candidate fields

note
string

Plain text, no formatting.

Keeping track of candidate fields

NOTE: Not all fields submitted in the body of the POST request can be retrieved later through GET. Make sure you keep track of everything you need in your service.

No code samples available
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
{
    "position_uid": "11.11",
    "partner_candidate_id": "1111A",
    "first_name": "Bobby",
    "middle_name": "Robert",
    "last_name": "Chauck",
    "email": "bobby.c@example.com",
    "phone": "07-4442321",
    "mobile_phone": "052-8644246",
    "national_id": "5454-2233-1",
    "linkedin_url": "https://www.linkedin.com/in/bobby-hauck-06b0735",
    "salary_expectations": "80k / Annual",
    "resume":
    {
        "name": "bobby_cv.docx",
        "file": "BASE64"
    },
    "picture":
    {
        "file": "BASE64",
        "name": "image.png"
    },
    "links": [
    {
        "url": "https://www.github.com/bobbyc"
    }
    //...
    ],
    "files": [
    {
        "name": "Coding Challenge",
        "file": "BASE64"
    },
    //...
    ],
    "source":
    {
        "name": "JobmeHR",
        "type": "Agency"
    },
    "source_contact":
    {
        "full_name": "Michael Rosen",
        "email": "michael.rosen@source.com",
        "phone": "555 555 1234"
    },
    "address":
    {
        "country": "US",
        "city": "New York",
        "state": "NY",
        "zip": "11249",
        "street": "109 S 5th st. #302"
    },
    "custom_fields":
    {
        "field1": "value1",
        //...
    },
    "note": "The candidate expressed his interest in this position"
}
{  
  "uid": "00.AAA",
  "position_uid": "11.11",
  "source_contact": {  
    "full_name": "Michael Rosen",
    "email": "michael.rosen@source.com",
    "phone": "555 555 1234"
  },
  "time_created": "2018-01-01T12:50:50Z",
  "time_last_status_changed": "2018-01-01T12:50:50Z",
  "current_steps": [  
    {  
      "name": "Technical interview",
      "type": "In person Interview",
      "time_scheduled": "2018-01-01T12:50:50Z"
    }
  ],
  "completed_steps": [  
    {  
      "name": "CV Screen",
      "type": "Go/No-go",
      "time_scheduled": "2018-01-01T12:50:50Z",
      "time_completed": "2018-03-03T12:50:50Z"
    }
  ],
  "status": "In progress"
}
{  
  "status":409,
  "error":"candidate_post_conflict",
  "message":"Candidate with provided partner_candidate_id already exists in position with status in progress",
  "candidate_uid":5555
}
Suggest Edits

/candidates

Read a list of Candidates.

 
gethttps://api.comeet.co/sourcing/candidates

Query Params

include
array of strings

Which optional fields to include in the response. See the Candidate schema for details.

filter
string
limit
int32

Maximum value: 1000

next
string

Pagination cursor (will be returned in "next_page")

Supported filters:

  • status - comma separated list of statuses. Return candidates who match any of the provided values.
    status=In%20progress,Rejected

  • time_created:before - Return candidates for which the time_created is BEFORE the provided time.
    time_created:before=2018-01-01T12:50:50Z

  • time_created:after - Return candidates for which the time_created is AFTER the provided time.
    time_created:after=2018-01-01T12:50:50Z

  • time_last_status_change:before - Return candidates for which the time_last_status_change is BEFORE the provided time.
    time_last_status_change:before=2018-01-01T12:50:50Z

  • time_last_status_change:after - Return candidates for which the time_last_status_change is AFTER the provided time.
    time_last_status_change:after=2018-01-01T12:50:50Z

  • time_hiring_process_updated - Return candidates that had any activity AFTER the provided time.
    time_hiring_process_updated=2018-01-01T12:50:50Z

No code samples available
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
{  
  "candidates":[  
    {  
      "uid":"00.AAA",
      "deleted": false,
      "position_uid":"11.11",
      "source_contact":{  
        "full_name":"Michael Rosen",
        "email":"michael.rosen@source.com",
        "phone":"555 555 1234"
      },
      "time_created":"2018-01-01T12:50:50Z",
      "time_last_status_changed":"2018-01-01T12:50:50Z",
      "current_steps":[  
        {  
          "name":"Technical interview",
          "type":"In person Interview",
          "time_scheduled":"2018-01-01T12:50:50Z"
        }        //...
      ],
      "completed_steps":[  
        {  
          "name":"CV Screen",
          "type":"Go/No-go",
          "time_scheduled":"2018-01-01T12:50:50Z",
          "time_completed":"2018-03-03T12:50:50Z"
        }        //...
      ],
      "address":{
        "country": "US",
        "state": "NY",
        "zip": "11249",
        "street_address": "109 S 5th St",
        "city": "Brooklyn"
      },
      "status":"In progress"
    }    //...
  ],
  // URL or null if no more candidates available
  "next_page": "https://api.comeet.co/..." 
}
Suggest Edits

/candidates/{uid}

Read a specific Candidate.

 
gethttps://api.comeet.co/sourcing/candidates/uid

Path Params

uid
string
required

Query Params

include
array of strings

Which optional fields to include in the response. See the Candidate schema for details.

 
No code samples available
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
{  
  "uid": "00.AAA",
  "position_uid": "11.11",
  "source_contact": {  
    "full_name": "Michael Rosen",
    "email": "michael.rosen@source.com",
    "phone": "555 555 1234"
  },
  "time_created": "2018-01-01T12:50:50Z",
  "time_last_status_changed": "2018-01-01T12:50:50Z",
  "current_steps": [  
    {  
      "name": "Technical interview",
      "type": "In person Interview",
      "time_scheduled": "2018-01-01T12:50:50Z"
    }
    //...
  ],
  "completed_steps": [  
    {  
      "name": "CV Screen",
      "type": "Go/No-go",
      "time_scheduled": "2018-01-01T12:50:50Z",
      "time_completed": "2018-03-03T12:50:50Z"
    }
    //...
  ],
  "status": "In progress"
}
Suggest Edits

/positions

Read a list of Positions.

 
gethttps://api.comeet.co/sourcing/positions

Query Params

include
array of strings

Which optional fields to include in the response. Supported values: details

filter
string
limit
int32

Maximum value: 1000

next
string

Pagination cursor (will be returned in "next_page")

Supported filters:

  • status - comma separated list of statuses. Return positions that match any of the provided values.
    status=open,closed

  • is_published - true or false. Return positions that match the provided value.
    is_published=true

  • time_last_updated:before - Return candidates for which the time_last_status_change is BEFORE the provided time.
    time_last_updated:before=2018-01-01T12:50:50Z

  • time_last_updated:after - Return positions for which the time_last_updated is AFTER the provided time.
    time_last_status_change:after=2018-01-01T12:50:50Z

No code samples available
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
{  
  "positions":[  
    {  
      "uid":"87.405",
      "name":"Account Executive, Austin",
      "status": "open",
      "department":"Sales",
      "email":"companyname.87.405@applynow.io",
      "url_comeet_hosted_page":"https://www.comeet.co/jobs/companyname/30.005/account-executive-austin/87.405",
      "url_active_page":"https://www.comeet.co/jobs/companyname/30.005/account-executive-austin/87.405",
      "employment_type":"Full-time",
      "experience_level":"Intermediate",
      "internal_use_custom_id":null,
      "picture_url":"https://comeet-euw-app.s3.amazonaws.com/53/b5ac4af700dfe6d749a862f7ba267f288f6cb575",
      "time_updated":"2017-05-26T14:22:46Z",
      "company_name":"Company Name",
      "position_url":"https://www.comeet.co/careers-api/2.0/company/30.005/positions/87.405?token=359F1DD13E1DD1DD1A813E6A6A",
      "location":{  
        "name":"Austin, TX",
        "country":"US",
        "city":"Austin",
        "state":"TX",
        "postal_code":"",
        "street_name":"",
        "arrival_instructions":null,
        "street_number":"",
        "timezone":"America/Iqaluit",
        "uid": "D00.000"        
      },
      "categories":[  
        {  
          "name":"Territory",
          "value":"USA",
          "order":1
        }        //...
      ],
      "details":[  
        {  
          "name":"Description",
          "value":"We are looking for ...",
          "order":1
        },
        {  
          "name":"Requirements",
          "value":"Candidates should have ...",
          "order":2
        }        //...
      ]
    }    //...
  ],
  // URL or null if no more candidates available 
  "next_page":"https://api.comeet.co/..."
}
Suggest Edits

/positions/{uid}

Read a specific Position.

 
gethttps://api.comeet.co/sourcing/positions/uid

Path Params

uid
string
required

Query Params

include
array of strings

Which optional fields to include in the response. Supported values: details

 
No code samples available
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
{  
  "uid":"87.405",
  "name":"Account Executive, Austin",
  "status": "open",
  "department":"Sales",
  "email":"companyname.87.405@applynow.io",
  "url_comeet_hosted_page":"https://www.comeet.co/jobs/companyname/30.005/account-executive-austin/87.405",
  "url_active_page":"https://www.comeet.co/jobs/companyname/30.005/account-executive-austin/87.405",
  "employment_type":"Full-time",
  "experience_level":"Intermediate",
  "internal_use_custom_id":null,
  "picture_url":"https://comeet-euw-app.s3.amazonaws.com/53/b5ac4af700dfe6d749a862f7ba267f288f6cb575",
  "time_updated":"2017-05-26T14:22:46Z",
  "company_name":"Company Name",
  "position_url":"https://www.comeet.co/careers-api/2.0/company/30.005/positions/87.405?token=359F1DD13E1DD1DD1A813E6A6A",
  "location":{  
    "name":"Austin, TX",
    "country":"US",
    "city":"Austin",
    "state":"TX",
    "postal_code":"",
    "street_name":"",
    "arrival_instructions":null,
    "street_number":"",
    "timezone":"America/Iqaluit",
    "uid": "D00.000"
  },
  "categories":[  
    {  
      "name":"Territory",
      "value":"USA",
      "order":1
    }
    //...
  ],
  "details":[  
    {  
      "name":"Description",
      "value":"We are looking for ...",
      "order":1
    },
    {  
      "name":"Requirements",
      "value":"Candidates should have ...",
      "order":2
    }
    //...
  ]
}
Suggest Edits

/positions/{uid}/candidates

Read a list of Candidates.

 
gethttps://api.comeet.co/sourcing/positions/uid/candidates

Query Params

include
array of strings

Which optional fields to include in the response. See the Candidate schema for details.

filter
string
limit
int32

Maximum value: 1000

next
string

Pagination cursor (will be returned in "next_page")

This request is similar to /candidates, it only returns candidates in the specified position.

No code samples available
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available
 
Suggest Edits

Job Board API

 
 
 
Suggest Edits

API Overview

 

This API is for Job Boards that wish to offer their sourcing platform to Comeet users. If you are interested please contact us at support@comeet.co.

Comeet allows recruiters to automate their postings to job boards. For each job board, recruiters can choose whether to post all of their positions automatically or post positions selectively.

 
Suggest Edits

Becoming a Comeet Job Board Partner

 

If you are interested in partnering with Comeet, please contact us at support@comeet.co and tell us about your job board.

The integration process is as follows:

  1. Send us your logo and written summary describing your sourcing platform or channel:
    • Summary – Write this for recruiters. Mention the geographies in which you operate. Highlight any noteworthy or unique characteristics of the job board. Please limit your summary to 120 characters.
    • Logo – Please submit two versions of your logo:
      High-rez - Preferred format is .eps or a 300 DPI jpg. at approx. 400 X 400 px. with a transparent background.
      Medium-rez - Approx. 150 X 150 px. at 144 DPI .jpg.
  1. We will set up your job board on Comeet. As a Comeet Job Board partner, you will be provided with a URL to a dedicated feed for your Job Board, listing all of the positions to be published. We expect your system to read this feed and update the list of jobs periodically in intervals of up to 24 hours. Updating the feed means adding positions, updating positions information and removing positions that are no longer in the feed.

  2. When we see that positions are being published, updated and properly removed from the job board, we will set the integration live for all customers.

 
Suggest Edits

Positions Feed

 

The feed is a list of jobs provided in XML format. Each job includes the following properties:

Field
Description

guid

Unique ID of the position

title

Position title

description

Position description (HTML)

requirements

Position requirements (HTML)

url

The URL of the position’s page – refer candidates to this page. The URL includes a tracking parameter that allows Comeet to associate applicants with the job board that referred them

employer

Name of the company

employer-uid

Unique ID of the company

city

Position location - city

state

Position location - state

country

Position location - two-character country code according to ISO 3166-1 Alpha-2

zipcode

Position location - zip code

position-email

Unique email address of the position, accepting emails that include a resume file as an attachment. The email includes a tracking parameter that allows Comeet to associate applicants with the job board that sent them

post-date

The date of the post as: YYYY-DD-MM

Jobs feed for development

An example of a jobs feed for development purposes is available at:
http://support.comeet.co/downloads/jobboard-sample-feed.xml

<?xml version="1.0" encoding="UTF-8"?>
<jobs>
   <job>
      <guid><![CDATA[NV8xMzc4MF8xMTM4NV8yOTc0]]></guid>
      <title><![CDATA[Senior Java/J2EE Engineer]]></title>
      <description><![CDATA[<p><b>Description:</b> </p><p>We are looking for talented, experienced Java/J2EE Developers to join our Core Java team. </p><p><b>Responsibilities:</b></p><p><b></b></p><ul><li>As a Java/J2EE developer, you'll be facing challenges that are at the "edge" of the cutting edge of technology, and therefore, it is a position in which you will be constantly thinking out-of-the-box to find a creative solution or the shortest path to victory, depending on the call of the hour. </li><li>If you truly love technology, this won't feel like work, more like a thrilling adventure. The ability to work as a team member is crucial here as we all depend on each other's success. </li><li>Independent work is also very important, and of course, at the end of the day, delivering code that works on time. </li><li>Some of the skills required: debugging, sprint planning, and system design &amp; task estimation. Strong knowledge in Java and EJB's - a must, with a big plus if you are a Groovy/Grails Warrior.</li></ul>]]></description>
      <requirements><![CDATA[<ul><li><span>At least 6 years of Java/J2EE, EJB Development Experience</span><br></li><li>At least one year experience working with EJB’s in an Application Server environment</li><li>Groovy &amp; Grails a big plus</li><li>At least 2 years of Java/J2EE Development in Online Environments</li><li>Experience in multi-threaded environments</li><li>Proven track record of driving projects to completion</li><li>Advantage working in a startup environment</li><li>Team player with good interpersonal skills</li><li>Sense of humor a must, but not required. On-job training provided.</li></ul><p><br></p><p><b><i>Think you fit the bill? We want to hear from you! </i></b></p>]]></requirements>
      <url><![CDATA[https://www.companyname.com/jobs/7C.209/senior-javaj2ee-engineer/?coref=1.11.p9B_00E]]></url>
      <employer><![CDATA[Company name]]></employer>
      <employer-uid><![CDATA[11.111AA]]></employer-uid>
      <city><![CDATA[New York]]></city>
      <state><![CDATA[NY]]></state>
      <country><![CDATA[US]]></country>
      <zipcode>10003</zipcode>
      <position-email><![CDATA[companyname.7C.209@applynow.io]]></position-email>
      <post-date>2016-05-10</post_date>
   </job>
   ...
</jobs>
Suggest Edits

Evaluation API

 
 
 
Suggest Edits

Introduction

 

Comeet enables recruiters to automate their recruiting processes by creating workflows comprised of recruiting steps or tasks. These steps are either handled in-house or by external recruiters or integrated recruiting tools. This article is intended for providers of recruiting tools that assess or evaluate candidates.

 
Suggest Edits

API Overview

 

The API works in the form of webhooks where Comeet performs HTTP requests to the evaluation provider's service. Implementing the API requires the creation of these endpoints:

  1. Get list of tests
  2. Submit candidate for evaluation
  3. Get evaluation
 
Suggest Edits

Getting Access - Become a Partner

 
  1. Submit the Become a Partner Form. You will be requested to submit the following information:

    • Your contact details - name, email, role and company name
    • Your app - name, description, website URL, logo (270 x 80 px) and avatar (80 x 80 px)
    • Service type – One of the following: Candidate assessment, Video interviews, Background checks, Reference checks, Other.
    • Endpoints – For the 3 webhooks.
    • Activation page - Instead of asking users to copy and paste the API Key, you can make activation easier for users by creating an activation page. See details below.
    • API Terms of Use - By using this API, you agree to the Comeet API Terms of Use.
  2. Once the submission is approved, we will send you your secret and invite you to your Sandbox account. Sign up to your Sandbox account and retrieve the API Key for that account from the integrations setting page.

  3. Develop the integration. When ready, send us a short video that demonstrates the integration including all the steps described in the Example Scenario below.

  4. We'll review the submitted video. Once approved, we'll provide you the secret to the production environment to be used with https://api.comeet.co.

Activation Page - Make activation easier for Comeet users

If you provided an activation url then the user will click on the Activate button in Comeet which will open the url you provided. The request will include the api-key of the Comeet account and the Signature that allows you to verify that the request was made by Comeet. Alternatively, if you don't provide the activation url the user will click on Copy Key and will manually input the API Key in your app (ie. by pasting in the product or sending to a support rep).

 
Suggest Edits

Authorization

 

All API calls use HTTPS and should be verified by your system:

  1. To verify a request you need these values:

    • secret - received when approved as a Comeet partner. See Getting Access - Become a Partner.
    • api-key - received from a Comeet customer when the integration is activated.
  2. Comeet will add the Authorization header to all HTTP requests using the following syntax:
    Authorization: Bearer <token>

  3. Verify the request by decoding the token with your secret using JWT. The result must be identical to the api-key. You can use one of the many JWT libraries available online.

 
Suggest Edits

Example Scenario

 
  1. Set up the integration

    • A Comeet user with an Admin role will find your service on Comeet's Integrations page and click Integrate.
    • If you provided an activation url then the user clicks the Activate button which opens the url you provided. The request will include the api-key of the Comeet account and the Signature that allows you to verify that the request was made by Comeet. Alternatively, if you don't provide the activation url the user will click on Copy Key and will manually input the API Key in your app (ie. by pasting it in your app or sending it to a support rep).
  2. Set up the test step on the position workflow
    The recruiter will add a step to the workflow and define it as a step that uses your app. Then the user will select one or more of the tests that your app provides. The user can also create the step’s policy; whether it will run automatically or require confirmation.

  3. Send test
    When a candidate reaches the test step, Comeet will initiate the request to submit the test for evaluation. If necessary, Comeet will send the candidate an email requesting completion of an evaluation test using a link provided by the evaluation partner.

  4. Test is completed
    Comeet periodically checks on test status until it is completed. After completion, the evaluation is added to the candidate profile. Depending on the outcome and policies defined by the recruiter or hiring manager, the candidate will progress in the workflow.

 
Suggest Edits

Get List of Tests

 
gethttps://www.evaluation-partner.com/api/tests

The list of tests is shown to the user who sets up the evaluation step as part of the position’s workflow. Each test may include a description.

In case of an error retrieving the list, the last list that was successfully retrieved will be used until the next successful response.

Request

HTTP Headers

Name
Value

Content-Type

application/json

Authorization

Bearer XXXXXXXXXXXXXXXXX

Response

Response is an array of tests.

Name
Type
Optional
Description

test_id

string

required

Test ID

test_name

string

required

Test name

test_description

string

optional

Test description (HTML); inline styling is not allowed; limited to 5000 characters

test_group

string

optional

Use this property to group tests together, eg. "Basic", "Advanced". Limited to 50 characters

No code samples available
A binary file was returned

You couldn't be authenticated

No response examples available
GET https://www.evaluation-partner.com/api/tests
[
    {
        "test_id": "75489534211",
        "test_name": "Java Developer / Threads",
        "test_description": "Write code in multi-threaded environment",
        "test_group": "Basic"
    },
    {
        "test_id": "765653432",
        "test_name": "Java Developer / Collection",
        "test_description": "Write efficient Java code using collections",
        "test_group": "Basic"      
    }
]
Suggest Edits

Submit Candidate for Evaluation

 
posthttps://www.evaluation-partner.com/api/tests/submit

Submit a candidate for one or more tests. It is up to the evaluation provider to specify whether Comeet should send a message to the candidate to complete the test at a specified link.

Contact us to specify any customization preferences.

  • The evaluation partner can specify whether the request should allow multiple tests or only one test at a time.
  • The Optional/Required fields in the request can be customized per the evaluation partner's needs. For example, if the candidate’s email is required by the service, it can be defined as required, preventing the user from submitting any candidates lacking defined email addresses.

In case of an error submitting a candidate for evaluation, the recruiter will be notified and requested to review the error message.

Request

Payload:

Name
Type
Optional
Description

test_ids

array[string]

required

Array of evaluation partner test_id

candidate

object

required

Candidate details

candidate.uid

string

required

candidate.first_name

string

required

candidate.middle_name

string

optional

candidate.last_name

string

optional

candidate.phone

string

optional

candidate.email

string

optional

candidate.resume

object

optional

candidate.resume.name

string

optional

File name of the resume

candidate.resume.url

string

optional

URL to the resume. The link expires 3 minutes after it was submitted

position

object

required

The position for which the candidate is being considered

position.uid

string

required

position.name

string

required

assignees

array

required

The users who are responsible for this step in the hiring process

assignees[].first_name

string

required

assignees[].middle_name

string

optional

assignees[].last_name

string

optional

assignees[].email

string

required

HTTP Headers

Name
Value

Content-Type

application/json

Authorization

Bearer XXXXXXXXXXXXXXXXXXXXX

Response

Name
Type
Optional
Description

candidate_evaluation_id

string

required

Unique ID of the candidate submission for requested tests

test_url_for_candidate

string

optional

When provided Comeet will send an email message to the candidate requesting to complete the test at the specified URL

instructions_for_candidate

string

optional

Plain text, limited to 2000 characters. Only applicable when test_url_for_candidate is provided. When provided, these instructions will be included as part of the message to the candidate

No code samples available
A binary file was returned

You couldn't be authenticated

No response examples available
POST https://www.evaluation-partner.com/api/tests/submit
{
    "test_ids": ["5354343", "4324343"],
    "candidate":
    {
        "uid": "AAA.00",        
        "first_name": "Harry",
        "middle_name": "James",
        "last_name": "Potter",
        "phone": "123-456-7890",
        "email": "hpotter@hogwarts.edu",
        "resume": {
              "name": "harry_cv.pdf",
              "url": "https://comeet-euw-qa.s3-eu-west-1.amazonaws.com/65c0a9ff2166g"
        }
    },
    "position":
    {      
        "uid":"87.405",
        "name":"Account Executive"
    },
    "assignees": [
      {
        "first_name": "Cory",
        "middle_name": "",
        "last_name": "James",
        "email": "cory@company.com"       
      },
      {
        "first_name": "Collin",
        "middle_name": "Charles",
        "last_name": "Cha",
        "email": "collin@company.com"      
      }      
    ]
}
{
    "candidate_evaluation_id": "98765"
}
{
    "candidate_evaluation_id": "98765",
    "test_url_for_candidate": "https://www.evaluation-partner.com/tests/98765",
    "instructions_for_candidate": "The test should take one hour to complete."
}
Suggest Edits

Get Evaluation

 
gethttps://www.evaluation-partner.com/api/get_evaluation?candidate_evaluation_id=000

This endpoint is used periodically to check the status of candidate tests. The provided status is shown to users in Comeet. After the test is reported as completed, Comeet will stop checking the test’s status.

Request

Query string params:

Name
Type
Optional
Description

candidate_evaluation_id

string

required

candidate_evaluation_id that was previously created

HTTP Headers:

Name
Value

Content-Type

application/json

Authorization

Bearer XXXXXXXXXXXXXXXXXX

Response

Name
Type
Optional
Description

status

string

required

40 characters limit. The status of the test will be shown in Comeet. When the test is completed, the status should be "completed"

outcome

string

required

One of the following:
"passed" - the candidate will continue to the next step in the hiring process
"review" - Comeet will create a task to review the results of the test
"failed" - the candidate will be rejected

score

number

optional

Overall score; A real number between 1 to 5, eg. "3.5"

summary

string

optional

Plain text; 2000 characters limit

criteria

array

optional

Array of the criteria that were evaluated

criteria[].title

string

required

Title of the criterion

criteria[].notes

string

optional

Plain text; 500 characters limit

criteria[].score

number

optional

Score for criterion; A real number between 1 to 5, eg. "3.5"

criteria[].group

string

optional

Use this property to group criteria together, eg. "Exercise 1", "Exercise 2", "Overview". Limited to 200 characters

url_for_users

string

optional

URL that registered users can go to to see the completed test page in your app. It is recommended to provide both url_for_users and url_for_non_users

url_for_non_users

string

optional

URL that non-registered users can go to to see the completed test page in your app. It is recommended to provide both url_for_users and url_for_non_users

Handling edge cases

Comeet expects the response to indicate how the hiring process should continue and clearly explain to the recruiter what happened. For example, if the candidate or the test were deleted from your system, the response should be:
{
"status": "completed",
"outcome": "review",
"summary": "-- an explanation to the recruiter about what happened --"
}

No code samples available
A binary file was returned

You couldn't be authenticated

No response examples available
GET https://www.evaluation-partner.com/api/get_evaluation?candidate_evaluation_id=000
{
    "status": "completed",
    "outcome": "passed",
    "score": 4.5,
    "summary": "Performed well.",      
    "criteria": [
        {
            "title": "Riding a Nimbus 2000",
            "notes": "Quidditch World Cup potential.",
            "score": 5
        },
        {
            "title": "Riding a Firebolt",
            "notes": "Impressive maneuvers.",
            "score": 4
        }      
    ],
    "url_for_users": "https://www.evaluation-partner.com/evaluation/1111",
    "url_for_non_users": "https://www.evaluation-partner.com/evaluation/1111?token=hgsadkf3kas56jdgfsdsakjpgdhqfjakansmgdhfrkj56as8h0gdu"      
}

In case of an error requiring the user’s attention, the response should provide a message that describes the problem. Include the display_message property in the response to provide the message that is going to be displayed to users in Comeet. Make sure to include all the information that the user would need to understand the problem and address it.

Have more questions? Contact us at support@comeet.co.

{
    "display_message": "Subscription has expired"
    ...
}