Introduction

The Candidate Ingestion API enables sourcing partners with whom Greenhouse shares mutual customers to submit prospects and candidates.

The API allows partners to:

1. Send candidates from the partner application to Greenhouse.
2. Retrieve the current stage and status of candidates.
3. Retrieve jobs on which the Greenhouse user is allowed to operate.

Note: The organization must be able to create prospects in order to create prospects using the Candidate Ingestion API.

Authentication

This API offers two methods of authentication: OAuth 2.0 and Basic Auth.

Authentication via OAuth 2.0

If the mutual customer’s users have accounts in both Greenhouse and the partner’s system, the preferred authentication method is OAuth 2.0. In this case, the partner would place an integration option on their website which would allow the user to authenticate in to Greenhouse via the partner’s application. This is similar to allowing people to register for a website using Facebook credentials. For a partner to configure this, they must supply Greenhouse with the following information:

1. Application Name: The name of the application as it would appear in Greenhouse.
2. Application URL: The URL to the primary application.
3. Callback URL: This is the URL to which Greenhouse will send authenticated users.
4. Logo Image: This is a 128x128 image that will be included in the permissions modal.

When Greenhouse receives this information, we will supply the partner with a consumer key, a consumer secret, a token URL, and an authorize URL. For example:

The partner should use this information to initiate an OAuth 2.0 flow in their application. Note the customer user can rescind this at any time.

When the user attempts to connect with Greenhouse, they will see a prompt asking them to confirm the connection. This prompt will then associate the user’s account in the partner system with their Greenhouse account.

Once the OAuth process is complete and the user grants the partner permission to access their data on Greenhouse, the partner will receive an access token. This access token must be included in the Authorization header:

Authorization: Bearer <access_token>

Authentication via Basic Auth

If your users only have an account in Greenhouse and you will be submitting candidates as a partner (and not sourced by a user), you will likely want to authenticate via HTTP Basic Authentication. Users do not have to take any action to authorize your application to modify Greenhouse data. When using basic auth, you are required to set the On-Behalf-Of header for every request. The value should be the e-mail address of the user on behalf of whom you are taking action. For example:

On-Behalf-Of: john.smith@example.com

Normally, this will be a service user created specifically for this purpose. If this header is missing, or Greenhouse doesn't recognize the address, the API will issue a 401 Unauthorized response. The application must also supply the API key. Via basic auth, you will include the API key as the basic auth username and nothing as the password. Since only a username needs to be provided in our case, you’ll need to append a : (colon) to the API token and then Base64 encode the resulting string. This may be included via URL:

https://<base64_encoded_api_key>:@api.greenhouse.io/v1/partners/candidates

or as an authorized header:

Authorization: Basic base64_encoded_api_key:

In all cases, the customer will have supplied the partner with a Partner API Key and a service user. Both items are required to submit candidates.

Note: Capabilities with the Ingestion API will be limited to the permissions of the On-Behalf-Of user

There are four user types, Site Admin, Job Admin, Interviewer, and Basic.

Site Admins have access to all jobs by default, whereas Job Admins/Interviewers are assigned to specific jobs. Job Admins/Interviewers will only be able to retrieve jobs via the API that they are assigned access to, or that are live on the company's job board. However they can add Candidates to jobs they have access to, as well as jobless Prospects to Greenhouse.

Because all user permissions are job-based, in order to retrieve jobless Prospects from the API, Site Admins, Job Admins, and Interviewers need the additional Greenhouse permission to manage jobless Prospects. Otherwise, they can only add Prospects, and not retrieve them. This is true of the UI as well.

Basic users have the most restrictions, since their abilities in the UI are also very limited:

Basic users can:

• Retrieve jobs
• Retrieve information about the current user
• Create prospects on no jobs
• Create candidates on jobs

They can't:

• Retrieve prospects
• Retrieve candidates
• Create a tracking link

OAuth Scopes

If you use OAuth for authentication, there are 3 permission scopes to be aware of. Some endpoints will require a specific permission scope while others require none.

• candidates.create: Create new candidates or prospects
• candidates.view: View candidates imported via this partner
• jobs.view: View my jobs.

General considerations

Unless otherwise specified, API methods generally conform to the following:

• Properties without a value will use null instead of being undefined
• "Snake Case" is used for attribute names (e.g. first_name)
• We reserve the right to add more properties to objects, but will never change or remove them

Ingestion API Change Log

The timestamps below are Eastern Time.

Candidates

Retrieve Candidates

curl 'https://api.greenhouse.io/v1/partner/candidates'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

{
    "candidate_ids": 17681532
}

API Response

{
    "id": 17681532,
    "name": "Harry Potter",
    "external_id": "24680",
    "applications": [
        {
            "id": 59724,
            "job": "Auror",
            "status": "Active",
            "stage": "Application Review",
            "profile_url": "https://app.greenhouse.io/people/17681532?application_id=26234709"
        }
    ]
}

Retrieve a candidate's data. Note that this call will only return candidates that the current user has permission to view.

GET https://api.greenhouse.io/v1/partner/candidates

scope: candidates.view

Request Parameters

The request should contain a single query parameter that specifies a comma-delimited list of candidate IDs or a single candidate ID. If you provide any candidate ids that don't exist or to which you do not have access, this endpoint will ignore them and only return the candidates that exist to this API key or Bearer token, or will return an empty response if you have only supplied one candidate ID.

An empty array will be returned for "Retrieve Candidates" requests with a single candidate ID for the following use-cases:

1. Permissions changes made on a Greenhouse user account associated to the email address used to authenticate the request (e.g. User has been disabled or deprovisioned).
2. The candidate is on a job that the user account/email address doesn't have access to. Note that the user account must be at least a job admin on the job associated to the candidate ID. If added as a prospect, the user must have the permission to manage unattached prospects.
3. The candidate profile was manually deleted by the organization.
4. The source on the candidate profile was manually changed to a new source different from the original partner source.
5. The candidate has been merged with another profile generating a new candidate ID.

If you would like more information about why you are not able to access a specific candidate ID, please contact the customer for more details, as Greenhouse Support will not share candidate details without the permission of the organization that owns the candidate record.

Response Parameters

The response will always be an array of objects, even if only one candidate_id is provided.

Post Candidates

curl -X POST 'https://api.greenhouse.io/v1/partner/candidates'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
-H "Content-Type: application/json"

{
    "prospect": "true",
    "first_name": "Harry",
    "last_name": "Potter",
    "company": "Hogwarts",
    "title": "Student",
    "resume": "https://hogwarts.com/resume",
    "phone_numbers": [
        {
            "phone_number": "123-456-7890",
            "type": "home"
        }
    ],
    "emails": [
        {
            "email": "hpotter@hogwarts.edu",
            "type": "other"
        }
    ],
    "social_media": [
        {
            "url": "https://twitter.com/hp"
        }
    ],
    "websites": [
        {
            "url": "https://harrypotter.com",
            "type": "blog"
        }
    ],
    "addresses": [
        {
            "address": "4 Privet Dr",
            "type": "home"
        }
    ],
    "job_id": 12345,
    "external_id": "24680",
    "notes": "Good at Quiddich",
    "prospect_pool_id": 123,
    "prospect_pool_stage_id": 456,
    "prospect_owner_email": "prospect_owners_email@example.com"
}

API Response

{
"id": 12345,
"application_id": 17681532,
"external_id": "24680",
"profile_url": "https://app.greenhouse.io/people/17681532?application_id=26234709"
}

Create one or more candidates or prospects

POST https://api.greenhouse.io/v1/partner/candidates

scope: candidates.create

Request Parameters

Response Parameters

The API will respond with a single object if a single object was provided or an array of objects if an array was provided.

Current User

Retrieve Current User

curl 'https://api.greenhouse.io/v1/partner/current_user'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

API Response

{
  "full_name": "Ron Weasley",
  "first_name": "Ron",
  "last_name": "Weasley",
  "email": "rweasley@hogwarts.edu",
  "id": 1234
}

Retrieve details about the current user

GET https://api.greenhouse.io/v1/partner/current_user

Request Parameters

This request is simply the URL. It takes no parameters.

Response Parameters

Jobs

Retrieve Jobs

curl 'https://api.greenhouse.io/v1/partner/jobs'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

API Response

[
  {
    "id": 146859,
    "name": "Auror",
    "status": "open",
    "public": true
  },
  {
    "id": 150050,
    "name": "Professor",
    "status": "open",
    "public": true
  },
  {
    "id": 147886,
    "name": "Caretaker",
    "status": "open",
    "public": false
  }
]

Retrieve jobs that are visible for the current user, including all jobs listed on their organization’s public careers page and unpublished jobs the user can access.

GET https://api.greenhouse.io/v1/partner/jobs

scope: jobs.view

Request Parameters

This request is simply the URL. It takes no parameters.

Response Parameters

Tracking Link

Post Tracking Link

curl -X POST 'https://api.greenhouse.io/v1/partner/tracking_link'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"
-H "Content-Type: application/json"

{
    "job_id": 12345
}

API Response

{ 
    "tracking_link": "http://grnh.se/yvj0bj",
    "job": "Auror", 
    "source": "Campus Recruiting",
    "referrer": "Hermione Granger"
}

Create a new tracking link for a specific job. Candidates that apply using this tracking link will automatically have their source set to your application and their referrer set to the current user.

POST https://api.greenhouse.io/v1/partner/tracking_link

Request Parameters

Response Parameters

Prospect Pools

Retrieve Prospect Pools

curl 'https://api.greenhouse.io/v1/partner/prospect_pools'
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6"

API Response

[
  {
    "id": 123,
    "name": "Cold Outreach: Referred",
    "stages": [
      {
        "id": 1957,
        "name": "Not Contacted"
      },
      {
        "id": 1958,
        "name": "Contacted"
      },
      {
        "id": 1959,
        "name": "1st. Follow Up Sent"
      },
      {
        "id": 1960,
        "name": "2nd Follow Up Sent"
      },
      {
        "id": 1961,
        "name": "In Discussion"
      }
    ]
  },
  {
    "id": 456,
    "name": "Cold Outreach: Sourced",
    "stages": [
      {
        "id": 1962,
        "name": "Not Contacted"
      },
      {
        "id": 1963,
        "name": "Contacted"
      },
      {
        "id": 1964,
        "name": "1st. Follow Up Sent"
      },
      {
        "id": 1965,
        "name": "2nd Follow Up Sent"
      },
      {
        "id": 1966,
        "name": "In Discussion"
      }
    ]
  }
]

Retrieve prospect pools along with their stages for the current user's organization.

GET https://api.greenhouse.io/v1/partner/prospect_pools

scope: prospect_pools.view

Request Parameters

This request is simply the URL. It takes no parameters.

Response Parameters

Errors

{
    "errors": [
        {
            "message": "Your request included invalid JSON.",
            "field": "email"
        }
    ]
}

Successful API responses will have a 200-level HTTP status code. If there is a problem processing your request, you will receive a response with a 4xx- or 5xx-level status code as follows:

Error Properties