API Reference

Partners API Concepts

Authentication

Partners API

Personal API Token (https://app.rc.recruitee.dev/#/settings/api_tokens) gives you access to our API on RC for integration development. You cannot use this token on production.

Use it to create POST /partner, update PATCH /partner, or retrieve GET /partner information.

Once the Partner is promoted to production, the only way to update it is to make changes on RC and re-request promotion.

Partner secret

partner.secret is generated for each Partner. It only gives you access to the Partners API endpoints for direct integration purposes, i.e. Reports-related actions.

Core API

If you need access to the broader Recruitee API outside of Partners API accessible with Partner secret, you must ask each customer for their Recruitee Personal API Token.

Partner

Entity you create with the POST /partner endpoint. It contains information about your service (kind, name, description, logo), and about the integration behaviour (URLs, options).

Integration

Integration is the relationship between Partner, and the customer's Recruitee Company (company_id). Customer integrates by providing the API Token to the Partner's service.

Kinds

Set partner.kind to the type of service you provide. This can determine integration features and labels the customer sees.

assessment, background_check, and reference_check integrations all support sending candidates, and saving and updating reports in Recruitee. The difference is in the labels the user sees in the Recruitee interface, e.g. "Send test" vs "Request background check" vs "Request reference check".

URLs

We will send requests, or link, to the URLs you set in partner.urls. All the API requests will contain Authorization: Bearer {token} header with the token provided by the customer. You should make it easy for the customer to copy their token from your service in order to paste it to Recruitee. You should use the token to authenticate and authorize the user.

Expected response statuses:

  • 2xx - success,
  • 401 or 403 - invalid token,
  • 4xx - error, you can show your own error message as described in Error handling.

validate_token

The customer must provide a valid token in order to enable the integration. 

GET {partner.urls.validate_token} HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

This example URL can be used in the initial development phase: https://c9d2c92dc329471696e8a6b670ea7c2b.m.pipedream.net

tests

Read: Sending candidates: Tests.

This example URL can be used in the initial development phase: https://1da22d5d35232651e170c77e943d5a68.m.pipedream.net

send_candidate

Read: Sending candidates: Payload.

This example URL can be used in the initial development phase: https://44c576c0fcabcf04b41673900b795b1b.m.pipedream.net

help_article

Non-API URL that's visible to the customer and will be opened in the browser. The help article is required before the integration can be promoted to all customers. It should include information:

  • where to find API Token,
  • how to integrate using the token,
  • how to use the integration.

Promoted: false

When a Partner is created, their partner.promoted attribute is set to false

This Partner is visible only to your company. Once the development on RC is done, Partner information will be copied to production and promoted to all customers.