CINXE.COM

<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible"> <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1"> <link rel="manifest" href="/images/favicons/manifest.json"> <link rel="icon" href="images/favicons/favicon.ico" sizes="32x32"> <link rel="icon" href="images/favicons/icon.svg" type="image/svg+xml"> <link rel="apple-touch-icon" href="images/favicons/apple-touch-icon.png"> <meta name="theme-color" content="#047957"> <title>Candidate Ingestion API | Greenhouse</title> <style media="screen"> .highlight table td { padding: 5px; } .highlight table pre { margin: 0; } .highlight, .highlight .w { color: #f8f8f2; background-color: #272822; } .highlight .err { color: #272822; background-color: #f92672; } .highlight .c, .highlight .ch, .highlight .cd, .highlight .cm, .highlight .cpf, .highlight .c1, .highlight .cs { color: #75715e; } .highlight .cp { color: #f4bf75; } .highlight .nt { color: #f4bf75; } .highlight .o, .highlight .ow { color: #f8f8f2; } .highlight .p, .highlight .pi { color: #f8f8f2; } .highlight .gi { color: #a6e22e; } .highlight .gd { color: #f92672; } .highlight .gh { color: #66d9ef; background-color: #272822; font-weight: bold; } .highlight .k, .highlight .kn, .highlight .kp, .highlight .kr, .highlight .kv { color: #ae81ff; } .highlight .kc { color: #fd971f; } .highlight .kt { color: #fd971f; } .highlight .kd { color: #fd971f; } .highlight .s, .highlight .sb, .highlight .sc, .highlight .dl, .highlight .sd, .highlight .s2, .highlight .sh, .highlight .sx, .highlight .s1 { color: #a6e22e; } .highlight .sa { color: #ae81ff; } .highlight .sr { color: #a1efe4; } .highlight .si { color: #cc6633; } .highlight .se { color: #cc6633; } .highlight .nn { color: #f4bf75; } .highlight .nc { color: #f4bf75; } .highlight .no { color: #f4bf75; } .highlight .na { color: #66d9ef; } .highlight .m, .highlight .mb, .highlight .mf, .highlight .mh, .highlight .mi, .highlight .il, .highlight .mo, .highlight .mx { color: #a6e22e; } .highlight .ss { color: #a6e22e; } </style> <style media="print"> * { -webkit-transition:none!important; transition:none!important; } .highlight table td { padding: 5px; } .highlight table pre { margin: 0; } .highlight, .highlight .w { color: #586e75; } .highlight .err { color: #002b36; background-color: #dc322f; } .highlight .c, .highlight .ch, .highlight .cd, .highlight .cm, .highlight .cpf, .highlight .c1, .highlight .cs { color: #657b83; } .highlight .cp { color: #b58900; } .highlight .nt { color: #b58900; } .highlight .o, .highlight .ow { color: #93a1a1; } .highlight .p, .highlight .pi { color: #93a1a1; } .highlight .gi { color: #859900; } .highlight .gd { color: #dc322f; } .highlight .gh { color: #268bd2; background-color: #002b36; font-weight: bold; } .highlight .k, .highlight .kn, .highlight .kp, .highlight .kr, .highlight .kv { color: #6c71c4; } .highlight .kc { color: #cb4b16; } .highlight .kt { color: #cb4b16; } .highlight .kd { color: #cb4b16; } .highlight .s, .highlight .sb, .highlight .sc, .highlight .dl, .highlight .sd, .highlight .s2, .highlight .sh, .highlight .sx, .highlight .s1 { color: #859900; } .highlight .sa { color: #6c71c4; } .highlight .sr { color: #2aa198; } .highlight .si { color: #d33682; } .highlight .se { color: #d33682; } .highlight .nn { color: #b58900; } .highlight .nc { color: #b58900; } .highlight .no { color: #b58900; } .highlight .na { color: #268bd2; } .highlight .m, .highlight .mb, .highlight .mf, .highlight .mh, .highlight .mi, .highlight .il, .highlight .mo, .highlight .mx { color: #859900; } .highlight .ss { color: #859900; } </style> <link href="stylesheets/screen_candidate-ingestion.css" rel="stylesheet" media="screen" /> <link href="stylesheets/print.css" rel="stylesheet" media="print" /> <script src="javascripts/all.js"></script> <script type="text/javascript"> !function(){var analytics=window.analytics=window.analytics||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Segment snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","page","once","off","on"];analytics.factory=function(t){return function(){var e=Array.prototype.slice.call(arguments);e.unshift(t);analytics.push(e);return analytics}};for(var t=0;t<analytics.methods.length;t++){var e=analytics.methods[t];analytics[e]=analytics.factory(e)}analytics.load=function(t){var e=document.createElement("script");e.type="text/javascript";e.async=!0;e.src=("https:"===document.location.protocol?"https://":"http://")+"cdn.segment.com/analytics.js/v1/"+t+"/analytics.min.js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(e,n)};analytics.SNIPPET_VERSION="3.1.0"; analytics.load("2q7wwCrJormvWKrplqZYR2gXyxLK5Uhx"); analytics.page() }}(); </script> </head> <body class="candidate-ingestion" data-languages="["shell"]"> <a href="#" id="nav-button"> NAV <img src="images/navbar.png" alt="" /> </a> <div class="toc-wrapper"> <a href="/" class="nav-home-link"> <div class="nav-home"> <img src="images/logo.png" class="logo" alt="" /> Developers Home </div> </a> <div class="lang-selector"> <a href="#" data-language-name="shell">shell</a> </div> <div class="search"> <input type="text" class="search" id="input-search" placeholder="Search"> </div> <ul class="search-results"></ul> <ul id="toc" class="toc-list-h1"> <li> <a href="#introduction" class="toc-h1 toc-link" data-title="Introduction">Introduction</a> <ul class="toc-list-h2"> <li> <a href="#authentication" class="toc-h2 toc-link" data-title="Authentication">Authentication</a> </li> <li> <a href="#oauth-scopes" class="toc-h2 toc-link" data-title="OAuth Scopes">OAuth Scopes</a> </li> <li> <a href="#general-considerations" class="toc-h2 toc-link" data-title="General considerations">General considerations</a> </li> <li> <a href="#ingestion-api-change-log" class="toc-h2 toc-link" data-title="Ingestion API Change Log">Ingestion API Change Log</a> </li> </ul> </li> <li> <a href="#candidates" class="toc-h1 toc-link" data-title="Candidates">Candidates</a> <ul class="toc-list-h2"> <li> <a href="#retrieve-candidates" class="toc-h2 toc-link" data-title="Retrieve Candidates">Retrieve Candidates</a> </li> <li> <a href="#post-candidates" class="toc-h2 toc-link" data-title="Post Candidates">Post Candidates</a> </li> </ul> </li> <li> <a href="#current-user" class="toc-h1 toc-link" data-title="Current User">Current User</a> <ul class="toc-list-h2"> <li> <a href="#retrieve-current-user" class="toc-h2 toc-link" data-title="Retrieve Current User">Retrieve Current User</a> </li> </ul> </li> <li> <a href="#jobs" class="toc-h1 toc-link" data-title="Jobs">Jobs</a> <ul class="toc-list-h2"> <li> <a href="#retrieve-jobs" class="toc-h2 toc-link" data-title="Retrieve Jobs">Retrieve Jobs</a> </li> </ul> </li> <li> <a href="#tracking-link" class="toc-h1 toc-link" data-title="Tracking Link">Tracking Link</a> <ul class="toc-list-h2"> <li> <a href="#post-tracking-link" class="toc-h2 toc-link" data-title="Post Tracking Link">Post Tracking Link</a> </li> </ul> </li> <li> <a href="#prospect-pools" class="toc-h1 toc-link" data-title="Prospect Pools">Prospect Pools</a> <ul class="toc-list-h2"> <li> <a href="#retrieve-prospect-pools" class="toc-h2 toc-link" data-title="Retrieve Prospect Pools">Retrieve Prospect Pools</a> </li> </ul> </li> <li> <a href="#errors" class="toc-h1 toc-link" data-title="Errors">Errors</a> <ul class="toc-list-h2"> <li> <a href="#error-properties" class="toc-h2 toc-link" data-title="Error Properties">Error Properties</a> </li> </ul> </li> </ul> <ul class="toc-appendage"> <li id="github_link"><a href="https://github.com/grnhse/greenhouse-api-docs/tree/master/source/includes/candidate-ingestion" title="View on Github" target="_blank">View on GitHub</a></li> </ul> <ul class="toc-footer"> <li><a href='/assessment.html' title="Assessment API">Assessment API</a></li> <li><a href='/audit-log.html' title="Audit Log API">Audit Log API</a></li> <li><a href="/harvest.html" title="Harvest API">Harvest API</a></li> <li><a href="/job-board.html" title="Job Board API">Job Board API</a></li> <li><a href='/gho.html' title="Onboarding API">Onboarding API</a></li> <li><a href='/webhooks.html' title="Webhooks">Webhooks</a></li> </ul> </div> <div class="page-wrapper"> <div class="dark-box"></div> <div class="content"> <h1 id='introduction'>Introduction</h1> The Candidate Ingestion API enables sourcing partners with whom Greenhouse shares mutual customers to submit prospects and candidates. The API allows partners to: <ol> <li>Send candidates from the partner application to Greenhouse.</li> <li>Retrieve the current stage and status of candidates.</li> <li>Retrieve jobs on which the Greenhouse user is allowed to operate.</li> </ol> Note: The organization must be able to create prospects in order to create prospects using the Candidate Ingestion API. <h2 id='authentication'>Authentication</h2> This API offers two methods of authentication: OAuth 2.0 and Basic Auth. <h3 id='authentication-via-oauth-2-0'>Authentication via OAuth 2.0</h3> If the mutual customer’s users have accounts in both Greenhouse and the partner’s system, the preferred authentication method is <a href="https://tools.ietf.org/html/rfc6749">OAuth 2.0</a>. 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: <ol> <li>Application Name: The name of the application as it would appear in Greenhouse.</li> <li>Application URL: The URL to the primary application.</li> <li>Callback URL: This is the URL to which Greenhouse will send authenticated users.</li> <li>Logo Image: This is a 128x128 image that will be included in the permissions modal.</li> </ol> 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: <table><thead> <tr> <th>Attribute</th> <th>Example Value</th> </tr> </thead><tbody> <tr> <td>Consumer Key</td> <td>bMipe4KWf987654321GrLG1Nfk1234567UshvloD</td> </tr> <tr> <td>Consumer Secret</td> <td>LQdulabcdefghijklEZok2fE5xGzeBcDa123gNXtN</td> </tr> <tr> <td>Token URL</td> <td>https://api.greenhouse.io/oauth/token</td> </tr> <tr> <td>Authorize URL</td> <td>https://api.greenhouse.io/oauth/authorize</td> </tr> </tbody></table> <aside class="notice"> Your Consumer Secret is confidential, and is best kept private. Greenhouse will request to encrypt the Consumer Secret before we send it to you via email. </aside> 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. <img src="images/prompt.png" alt= "Prompt Image" max-width> 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: <code>Authorization: Bearer <access_token></code> <h3 id='authentication-via-basic-auth'>Authentication via Basic Auth</h3> 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: <code>On-Behalf-Of: john.smith@example.com</code> 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: <code>https://<base64_encoded_api_key>:@api.greenhouse.io/v1/partners/candidates</code> or as an authorized header: <code>Authorization: Basic base64_encoded_api_key:</code> 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. <h3 id='note-capabilities-with-the-ingestion-api-will-be-limited-to-the-permissions-of-the-on-behalf-of-user'>Note: Capabilities with the Ingestion API will be limited to the permissions of the On-Behalf-Of user</h3> 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: <ul> <li>Retrieve jobs</li> <li>Retrieve information about the current user</li> <li>Create prospects on no jobs </li> <li>Create candidates on jobs</li> </ul> They can't: <ul> <li>Retrieve prospects</li> <li>Retrieve candidates</li> <li>Create a tracking link</li> </ul> <aside class="warning"> All user accounts must be active. Disabled users won't be able to do anything with the Ingestion API. </aside> <h2 id='oauth-scopes'>OAuth Scopes</h2> 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. <ul> <li><code>candidates.create</code>: Create new candidates or prospects</li> <li><code>candidates.view</code>: View candidates imported via this partner</li> <li><code>jobs.view</code>: View my jobs.</li> </ul> <aside class="warning"> These scopes do not apply if you are authenticating via Basic Auth. </aside> <h2 id='general-considerations'>General considerations</h2> Unless otherwise specified, API methods generally conform to the following: <ul> <li>Properties without a value will use <code>null</code> instead of being undefined</li> <li>"Snake Case" is used for attribute names (e.g. <code>first_name</code>)</li> <li>We reserve the right to add more properties to objects, but will never change or remove them</li> </ul> <h2 id='ingestion-api-change-log'>Ingestion API Change Log</h2> The timestamps below are Eastern Time. <table><thead> <tr> <th>Date</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>Oct 7, 2024</td> <td>Updated favicon, github mark, and color palette. Fixed typos and formatting errors.</td> </tr> <tr> <td>Apr 15, 2021 03:00:00PM</td> <td>Added <code>full_name</code> and <code>id</code> to the [GET current_user] response</td> </tr> <tr> <td>Aug 22, 2019 11:00:00AM</td> <td>Added Change Log and General Consideration sections to the Ingestion API documentation</td> </tr> </tbody></table> <h1 id='candidates'>Candidates</h1><h2 id='retrieve-candidates'>Retrieve Candidates</h2><div class="highlight"><pre class="highlight shell tab-shell"><code>curl 'https://api.greenhouse.io/v1/partner/candidates' -H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6" </code></pre></div><div class="highlight"><pre class="highlight json tab-json"><code>{ "candidate_ids": 17681532 } </code></pre></div> <blockquote> API Response </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "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" } ] } </code></pre></div> Retrieve a candidate's data. Note that this call will only return candidates that the current user has permission to view. <code>GET https://api.greenhouse.io/v1/partner/candidates</code> scope: candidates.view <h3 id='request-parameters'>Request Parameters</h3> 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: <ol> <li>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). </li> <li>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.</li> <li>The candidate profile was manually deleted by the organization.</li> <li>The source on the candidate profile was manually changed to a new source different from the original partner source.</li> <li>The candidate has been merged with another profile generating a new candidate ID.</li> </ol> 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. <table><thead> <tr> <th>Query Parameter Name</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>candidate_ids</td> <td>Yes</td> <td>Comma-delimited list of Candidate IDs (e.g. 123, 456)</td> </tr> </tbody></table> <h3 id='response-parameters'>Response Parameters</h3> The response will always be an array of objects, even if only one <code>candidate_id</code> is provided. <table><thead> <tr> <th>Property Name</th> <th>Type</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>id</td> <td>Integer</td> <td>The ID of the candidate</td> </tr> <tr> <td>external_id</td> <td>String</td> <td>The external ID that was provided in your initial candidate creation request. Can be null if you request the status of a candidate not associated with an external entity.</td> </tr> <tr> <td>applications[]</td> <td>Array</td> <td>An array containing 0 or more applications representing the jobs to which this candidate has applied. Each of the sub-elements are required for each of the applications.</td> </tr> <tr> <td>applications.id</td> <td>Integer</td> <td>The ID of the application.</td> </tr> <tr> <td>applications.job</td> <td>String</td> <td>Name of the job this application is for (e.g. "Software developer).</td> </tr> <tr> <td>applications.status</td> <td>String</td> <td>The candidate’s current status. Must be one of "rejected," "active," or "hired."</td> </tr> <tr> <td>applications.stage</td> <td>String</td> <td>The applicant’s current stage in the interview pipeline (e.g. "Recruiter Phone Screen").</td> </tr> <tr> <td>applications.profile_url</td> <td>String</td> <td>A URL to the candidate’s profile in Greenhouse. You must be signed in to Greenhouse to view the profile.</td> </tr> </tbody></table> <h2 id='post-candidates'>Post Candidates</h2><div class="highlight"><pre class="highlight shell tab-shell"><code>curl -X POST 'https://api.greenhouse.io/v1/partner/candidates' -H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6" -H "Content-Type: application/json" </code></pre></div><div class="highlight"><pre class="highlight json tab-json"><code>{ "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" } </code></pre></div> <blockquote> API Response </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 12345, "application_id": 17681532, "external_id": "24680", "profile_url": "https://app.greenhouse.io/people/17681532?application_id=26234709" } </code></pre></div> Create one or more candidates or prospects <code>POST https://api.greenhouse.io/v1/partner/candidates</code> scope: candidates.create <h3 id='request-parameters-2'>Request Parameters</h3> <table><thead> <tr> <th>Property Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>prospect</td> <td>Boolean</td> <td>No</td> <td>True if this candidate should be a prospect. The organization must be able to create prospects to set this field. (Default: true)</td> </tr> <tr> <td>job_id</td> <td>Integer</td> <td>Mixed</td> <td>Required only if prospect is false. The ID of the job to which this candidate or prospect should be added.</td> </tr> <tr> <td>first_name</td> <td>String</td> <td>Yes</td> <td></td> </tr> <tr> <td>last_name</td> <td>String</td> <td>Yes</td> <td></td> </tr> <tr> <td>external_id</td> <td>String</td> <td>Yes</td> <td>The unique id of this candidate in your application’s system.</td> </tr> <tr> <td>company</td> <td>String</td> <td>No</td> <td>Candidate's current company</td> </tr> <tr> <td>title</td> <td>String</td> <td>No</td> <td>Candidate's current title</td> </tr> <tr> <td>resume</td> <td>String</td> <td>No</td> <td>URL to the candidate’s resume. Greenhouse will attempt to ingest the document at this URL and add it to the candidate record.</td> </tr> <tr> <td>phone_numbers[]</td> <td>Array</td> <td>No</td> <td></td> </tr> <tr> <td>phone_numbers.phone_number</td> <td>String</td> <td>Mixed</td> <td>Only required if phone_number is included.</td> </tr> <tr> <td>phone_numbers.type</td> <td>String</td> <td>Mixed</td> <td>Must be "mobile", "home", "work", or "other." Only required if phone_number is included.</td> </tr> <tr> <td>emails[]</td> <td>Array</td> <td>No</td> <td></td> </tr> <tr> <td>emails.email</td> <td>String</td> <td>Mixed</td> <td>Note: Only required if email is included.</td> </tr> <tr> <td>emails.type</td> <td>String</td> <td>Mixed</td> <td>Must be "personal", "work", or "other". Only required if email is included.</td> </tr> <tr> <td>addresses[]</td> <td>Array</td> <td>No</td> <td></td> </tr> <tr> <td>addresses.address</td> <td>String</td> <td>Mixed</td> <td>A free form block of text, which may include newlines ("\n"). Only required if addresses are included.</td> </tr> <tr> <td>addresses.type</td> <td>String</td> <td>Mixed</td> <td>Must be "home", "work", or "other". Only required if addresses are included.</td> </tr> <tr> <td>social_media[]</td> <td>Array</td> <td>No</td> <td></td> </tr> <tr> <td>social_media.url</td> <td>String</td> <td>Mixed</td> <td>Note: Only required if social media urls are included.</td> </tr> <tr> <td>websites[]</td> <td>Array</td> <td>No</td> <td></td> </tr> <tr> <td>websites.url</td> <td>String</td> <td>Mixed</td> <td>Note: Only required if websites are included.</td> </tr> <tr> <td>websites.type</td> <td>String</td> <td>Mixed</td> <td>Must be either “personal”, “company”, “portfolio”, “blog”, or “other”. Only required if websites are included.</td> </tr> <tr> <td>referrer</td> <td>Object</td> <td>No</td> <td>If present, this value will be used to populate the "Who Gets Credit" field for the candidate’s application. If omitted, the "Who Gets Credit" field will be populated with the current user’s information.</td> </tr> <tr> <td>referrer.email</td> <td>String</td> <td>Mixed</td> <td>Used to match this referrer with an existing Greenhouse user, if possible. Only required if referrer is included.</td> </tr> <tr> <td>referrer.first_name</td> <td>String</td> <td>Mixed</td> <td>Used to create a new ‘Referrer’ in Greenhouse if referrer.email does not match an existing user. Only required if referrer is included.</td> </tr> <tr> <td>referrer.last_name</td> <td>String</td> <td>Mixed</td> <td>Used to create a new ‘Referrer’ in Greenhouse if referrer.email does not match an existing user. Only required if referrer is included.</td> </tr> <tr> <td>notes</td> <td>String</td> <td>No</td> <td>Free-form plain-text notes about this candidate. One way for this to be used is to send secondary information that our API can’t capture as structured data. For example: "Skills: Java, C++, Python"</td> </tr> <tr> <td>prospect_pool_id</td> <td>Integer</td> <td>Mixed</td> <td>Used to put a prospect in the Prospect Pool with this id. Only required if prospect_pool_stage_id is included. "prospect" property must be set to true.</td> </tr> <tr> <td>prospect_pool_stage_id</td> <td>Integer</td> <td>No</td> <td>Used to put a prospect in the Prospect Pool Stage with this id. The stage must belong to the prospect pool provided in prospect_pool_id. "prospect" property must be set to true.</td> </tr> <tr> <td>prospect_owner_email</td> <td>String</td> <td>No</td> <td>Used to set the prospect owner for a prospect by providing a valid user's email that exists in Greenhouse. "prospect" property must be set to true.</td> </tr> </tbody></table> <h3 id='response-parameters-2'>Response Parameters</h3> The API will respond with a single object if a single object was provided or an array of objects if an array was provided. <table><thead> <tr> <th>Property Name</th> <th>Type</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>id</td> <td>Integer</td> <td>The ID of the newly created candidate in Greenhouse.</td> </tr> <tr> <td>application_id</td> <td>Integer</td> <td>The ID of the application implicitly created in Greenhouse.</td> </tr> <tr> <td>external_id</td> <td>String</td> <td>The external ID that was provided in your request.</td> </tr> <tr> <td>profile_url</td> <td>String</td> <td>A URL to the candidate’s profile within Greenhouse. The user must be signed into Greenhouse to view the profile.</td> </tr> </tbody></table> <h1 id='current-user'>Current User</h1><h2 id='retrieve-current-user'>Retrieve Current User</h2><div class="highlight"><pre class="highlight shell tab-shell"><code>curl 'https://api.greenhouse.io/v1/partner/current_user' -H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6" </code></pre></div> <blockquote> API Response </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "full_name": "Ron Weasley", "first_name": "Ron", "last_name": "Weasley", "email": "rweasley@hogwarts.edu", "id": 1234 } </code></pre></div> Retrieve details about the current user <code>GET https://api.greenhouse.io/v1/partner/current_user</code> <h3 id='request-parameters'>Request Parameters</h3> This request is simply the URL. It takes no parameters. <h3 id='response-parameters'>Response Parameters</h3> <table><thead> <tr> <th>Property Name</th> <th>Type</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>full_name</td> <td>String</td> <td>The current user's full name</td> </tr> <tr> <td>first_name</td> <td>String</td> <td>The current user's first name</td> </tr> <tr> <td>last_name</td> <td>String</td> <td>The current user's last name</td> </tr> <tr> <td>email</td> <td>String</td> <td>The email address associated with the current user</td> </tr> <tr> <td>id</td> <td>Integer</td> <td>The ID of the current user</td> </tr> </tbody></table> <h1 id='jobs'>Jobs</h1><h2 id='retrieve-jobs'>Retrieve Jobs</h2><div class="highlight"><pre class="highlight shell tab-shell"><code>curl 'https://api.greenhouse.io/v1/partner/jobs' -H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6" </code></pre></div> <blockquote> API Response </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "id": 146859, "name": "Auror", "status": "open", "public": true }, { "id": 150050, "name": "Professor", "status": "open", "public": true }, { "id": 147886, "name": "Caretaker", "status": "open", "public": false } ] </code></pre></div> 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. <code>GET https://api.greenhouse.io/v1/partner/jobs</code> scope: jobs.view <h3 id='request-parameters'>Request Parameters</h3> This request is simply the URL. It takes no parameters. <h3 id='response-parameters'>Response Parameters</h3> <table><thead> <tr> <th>Property Name</th> <th>Type</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>id</td> <td>Integer</td> <td>The ID of the job.</td> </tr> <tr> <td>name</td> <td>String</td> <td>The name as it appears in Greenhouse, NOT necessarily how it appears on the public job board.</td> </tr> <tr> <td>status</td> <td>String</td> <td>Always ‘open’.</td> </tr> <tr> <td>public</td> <td>Boolean</td> <td>True if this job has any job posts that are currently live on any job board.</td> </tr> </tbody></table> <h1 id='tracking-link'>Tracking Link</h1><h2 id='post-tracking-link'>Post Tracking Link</h2><div class="highlight"><pre class="highlight shell tab-shell"><code>curl -X POST 'https://api.greenhouse.io/v1/partner/tracking_link' -H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6" -H "Content-Type: application/json" </code></pre></div><div class="highlight"><pre class="highlight json tab-json"><code>{ "job_id": 12345 } </code></pre></div> <blockquote> API Response </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "tracking_link": "http://grnh.se/yvj0bj", "job": "Auror", "source": "Campus Recruiting", "referrer": "Hermione Granger" } </code></pre></div> 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. <code>POST https://api.greenhouse.io/v1/partner/tracking_link</code> <h3 id='request-parameters'>Request Parameters</h3> <table><thead> <tr> <th>Property Name</th> <th>Type</th> <th>Required</th> </tr> </thead><tbody> <tr> <td>job_id</td> <td>Integer</td> <td>Yes</td> </tr> </tbody></table> <h3 id='response-parameters'>Response Parameters</h3> <table><thead> <tr> <th>Property Name</th> <th>Type</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>tracking_link</td> <td>String</td> <td>URL for newly created tracking link.</td> </tr> <tr> <td>job</td> <td>String</td> <td>The name of the job tied to this tracking link.</td> </tr> <tr> <td>source</td> <td>String</td> <td>The name of the source tied to this tracking link (e.g. the name of your application).</td> </tr> <tr> <td>referrer</td> <td>String</td> <td>The name of the user tied to this tracking link.</td> </tr> </tbody></table> <h1 id='prospect-pools'>Prospect Pools</h1><h2 id='retrieve-prospect-pools'>Retrieve Prospect Pools</h2><div class="highlight"><pre class="highlight shell tab-shell"><code>curl 'https://api.greenhouse.io/v1/partner/prospect_pools' -H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6" </code></pre></div> <blockquote> API Response </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "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" } ] } ] </code></pre></div> Retrieve prospect pools along with their stages for the current user's organization. <code>GET https://api.greenhouse.io/v1/partner/prospect_pools</code> scope: prospect_pools.view <h3 id='request-parameters'>Request Parameters</h3> This request is simply the URL. It takes no parameters. <h3 id='response-parameters'>Response Parameters</h3> <table><thead> <tr> <th>Property Name</th> <th>Type</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>id</td> <td>Integer</td> <td>The ID of the prospect pool.</td> </tr> <tr> <td>name</td> <td>String</td> <td>The name of the prospect pool.</td> </tr> <tr> <td>stages</td> <td>Object</td> <td>The stages that belong to a prospect pool with the id and name of the stage. The list of stages will be ordered the same way that it is configured to be ordered in Greenhouse.</td> </tr> </tbody></table> <h1 id='errors'>Errors</h1><div class="highlight"><pre class="highlight json tab-json"><code>{ "errors": [ { "message": "Your request included invalid JSON.", "field": "email" } ] } </code></pre></div> 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: <table><thead> <tr> <th>Status Code</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>400</td> <td>Your request included invalid JSON.</td> </tr> <tr> <td>401</td> <td>You have not been authenticated.</td> </tr> <tr> <td>403</td> <td>You have been authenticated, but your Greenhouse user does not have permission to the resource.</td> </tr> <tr> <td>404</td> <td>The resource you requested could not be found.</td> </tr> <tr> <td>5xx</td> <td>There was an error on our end. You may retry at a later time or contact support if the problem persists.</td> </tr> </tbody></table> <h3 id='error-properties'>Error Properties</h3> <table><thead> <tr> <th>Property Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>errors[]</td> <td>Array</td> <td></td> <td>Yes</td> </tr> <tr> <td>errors.message</td> <td>String</td> <td>Yes</td> <td>A message describing the error. This is for debugging purposes and is not intended to be displayed to the end-user. The exact text should not be relied on programmatically.</td> </tr> <tr> <td>errors.field</td> <td>String</td> <td>No</td> <td>The offending field in the request that caused the error, if applicable.</td> </tr> </tbody></table> </div> <div class="dark-box"> <div class="lang-selector"> <a href="#" data-language-name="shell">shell</a> </div> </div> </div> </body> </html>