Permissions: Site Admin

Product tier: Available for Expert subscription tier

An external ID is an optional free-text field available on offices and departments that allow your organization to assign non-Greenhouse alphanumeric identifiers to each of your Greenhouse Offices and Departments. This external ID is intended to improve third-party integrations by allowing customers to assign unique department and/or office identifiers that tie to an external or third-party system.

 

Add external ID to offices

To add an External ID to an office in your organization, click the Configure icon Configure icon on your navigation bar, then click Organization on the left.

Screenshot of Configure > Organization

Hover over the name of an office that you'd like to edit, and click the Edit icon Edit icon.

Screenshot of edit an office

Use the External ID field to input an external ID for the office.

Screenshot of an office external ID

When finished, click Save.

Repeat as necessary for other offices in your organization.

 

Add external ID to departments

To add an external ID to a department in your organization, click the Configure icon Configure icon on your navigation bar, then click Organization on the left.

Screenshot of Configure > Organization

Hover over the name of a department you'd like to edit, and click the Edit icon Edit icon.

Screenshot of edit a department

Use the provided External ID field to input an external ID for the department.

Screenshot of a department external ID

When finished, click Save.

Repeat as necessary for other departments in your organization.

 

External ID in API Requests (for developers)

Once external IDs are set up, they will appear in web hooks that include the office and department objects, and in Harvest API responses, including for the jobs, offices, and departments endpoints.

Additionally, you can make an API call for all jobs in a specific office or department by adding the external_office_id and external_department_id query string parameters.

Example:

curl -X GET \  'https://harvest.greenhouse.io/v1/jobs?external_office_id=OFFICE_1&external_department_id=DEPT_A' \
    -H 'Authorization: Basic *****' \

External IDs also remove the need to maintain a separate mapping of IDs between applications, and allow you to directly assign or update a job's office or department using external IDs (instead of Greenhouse Recruiting office or department IDs) via the POST Create Job and PATCH Update Job API endpoints.

Example:

curl -X POST \
https://harvest.greenhouse.io/v1/jobs \
-H 'Authorization: Basic ****' \
-H 'Content-Type: application/json' \
-H 'on-behalf-of: 123456 \
-d '{
"template_job_id": 654321,
"number_of_openings": 1,
"external_department_id": "test-456",
"external_office_ids": ["test-123"],
"job_name": " Example API Job",
"requisition_id": "xyz",
"opening_ids": [
"xyz-1"
]
}'