# Bullhorn

> Run your staffing desk in Bullhorn: find, add and update candidates, contacts, companies and jobs, submit candidates to jobs and move them through statuses, read placements, add notes and tasks, and start workflows when records are added or change.

App · 25 actions. Web page: https://docs.lodol.com/docs/integrations/bullhorn

## Actions

### Add note

Add a note to a candidate or contact, as the API user, optionally about a job.

**Inputs**

- Candidate or contact ID (`person_id`, text, required): The Bullhorn id of the candidate or contact the note is about.
- Note (`comments`, text, required): The note's text.
- Action (`note_action`, text): What the note records, from your Bullhorn note actions, such as Call.
- Job (`job_id`, text): The job the note is about, if any.

**Outputs**

- `note` (object): The note

**Example output**

```json
{
  "note": {
    "action": "Call",
    "commentingPerson": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "comments": "Spoke about the Senior Accountant role.",
    "dateAdded": 1763020800000,
    "id": 2552,
    "jobOrder": {
      "id": 4401,
      "title": "Senior Accountant"
    },
    "personReference": {
      "firstName": "Jo",
      "id": 5059165,
      "lastName": "Bloggs"
    }
  }
}
```

### Create candidate

Add a candidate to Bullhorn with their contact details, status and owner.

**Inputs**

- First name (`first_name`, text, required): The candidate's first name.
- Last name (`last_name`, text, required): The candidate's last name.
- Email (`email`, text): The candidate's email address.
- Phone (`phone`, text): The candidate's phone number.
- Mobile (`mobile`, text): The candidate's mobile number.
- Status (`status`, text): One of your Bullhorn candidate statuses, such as Active or New Lead.
- Source (`source`, text): Where the candidate came from, such as LinkedIn.
- Current job title (`occupation`, text): Their current job title.
- Current employer (`company_name`, text): Their current employer.
- Owner (`owner_id`, text): The Bullhorn user who owns the candidate. Leave empty for the API user.
- Available from (`date_available`, date and time): When the candidate can start.
- Street address (`address1`, text): The candidate's street address.
- City (`city`, text): The candidate's city.
- State (`state`, text): The candidate's state or region, such as MA.
- Postal code (`zip_code`, text): The candidate's ZIP or postal code.
- Country (`country_id`, text): The candidate's country.

**Outputs**

- `candidate` (object): The candidate

**Example output**

```json
{
  "candidate": {
    "address": {
      "address1": "100 Summer Street",
      "address2": "",
      "city": "Boston",
      "countryID": 1,
      "state": "MA",
      "zip": "02110"
    },
    "companyName": "Example Co",
    "dateAdded": 1763020800000,
    "dateAvailable": 1767225600000,
    "dateLastModified": 1763024400000,
    "email": "jo@example.com",
    "firstName": "Jo",
    "id": 5059165,
    "lastName": "Bloggs",
    "mobile": "617-555-0101",
    "name": "Jo Bloggs",
    "occupation": "Accountant",
    "owner": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "phone": "617-555-0100",
    "source": "LinkedIn",
    "status": "Active"
  }
}
```

### Create company

Add a client company. Bullhorn can't delete companies, so check it isn't there first.

**Inputs**

- Name (`name`, text, required): The company's name.
- Status (`status`, text): One of your Bullhorn company statuses, such as Prospect or Active Account.
- Phone (`phone`, text): The company's main phone number.
- Website (`website`, text): The company's website address.
- Description (`description`, text): About the company.
- Street address (`address1`, text): The company's street address.
- City (`city`, text): The company's city.
- State (`state`, text): The company's state or region, such as MA.
- Postal code (`zip_code`, text): The company's ZIP or postal code.
- Country (`country_id`, text): The company's country.

**Outputs**

- `company` (object): The company

**Example output**

```json
{
  "company": {
    "address": {
      "address1": "100 Summer Street",
      "address2": "",
      "city": "Boston",
      "countryID": 1,
      "state": "MA",
      "zip": "02110"
    },
    "companyDescription": "A client company.",
    "companyURL": "https://example.com",
    "dateAdded": 1763020800000,
    "dateLastModified": 1763024400000,
    "id": 301,
    "name": "Example Co",
    "phone": "617-555-0300",
    "status": "Active Account"
  }
}
```

### Create contact

Add a client contact at a company, with their contact details and owner.

**Inputs**

- First name (`first_name`, text, required): The contact's first name.
- Last name (`last_name`, text, required): The contact's last name.
- Company (`company_id`, text, required): The company the contact works for.
- Email (`email`, text): The contact's email address.
- Phone (`phone`, text): The contact's phone number.
- Mobile (`mobile`, text): The contact's mobile number.
- Job title (`occupation`, text): The contact's job title.
- Status (`status`, text): One of your Bullhorn contact statuses, such as Active.
- Owner (`owner_id`, text): The Bullhorn user who owns the contact. Leave empty for the API user.
- Street address (`address1`, text): The contact's street address.
- City (`city`, text): The contact's city.
- State (`state`, text): The contact's state or region, such as MA.
- Postal code (`zip_code`, text): The contact's ZIP or postal code.
- Country (`country_id`, text): The contact's country.

**Outputs**

- `contact` (object): The contact

**Example output**

```json
{
  "contact": {
    "address": {
      "address1": "100 Summer Street",
      "address2": "",
      "city": "Boston",
      "countryID": 1,
      "state": "MA",
      "zip": "02110"
    },
    "clientCorporation": {
      "id": 301,
      "name": "Example Co"
    },
    "dateAdded": 1763020800000,
    "dateLastModified": 1763024400000,
    "email": "sam@example.com",
    "firstName": "Sam",
    "id": 8592,
    "lastName": "Lee",
    "mobile": "617-555-0201",
    "name": "Sam Lee",
    "occupation": "Finance Director",
    "owner": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "phone": "617-555-0200",
    "status": "Active"
  }
}
```

### Create job

Add a job for a client contact and company, with its status, openings, start date and rates.

**Inputs**

- Title (`title`, text, required): The job's title.
- Hiring contact (`contact_id`, text, required): The client contact the job is for.
- Company (`company_id`, text, required): The hiring company, the contact's company.
- Status (`status`, text): One of your Bullhorn job statuses, such as Accepting Candidates.
- Open (`is_open`, text): Whether the job is open. Leave empty for Bullhorn’s default. One of: `yes`, `no`.
- Employment type (`employment_type`, text): One of your Bullhorn employment types, such as Contract or Direct Hire.
- Openings (`num_openings`, number): How many people are wanted. At least 1.
- Start date (`start_date`, date and time): When the job starts.
- Description (`description`, text): The job description.
- Owner (`owner_id`, text): The Bullhorn user who owns the job. Leave empty for the API user.
- Salary (`salary`, number): The salary offered. At least 0.
- Pay rate (`pay_rate`, number): The pay rate, for contract jobs. At least 0.
- Bill rate (`bill_rate`, number): The rate billed to the client. At least 0.

**Outputs**

- `job` (object): The job

**Example output**

```json
{
  "job": {
    "address": {
      "address1": "100 Summer Street",
      "address2": "",
      "city": "Boston",
      "countryID": 1,
      "state": "MA",
      "zip": "02110"
    },
    "clientBillRate": 0,
    "clientContact": {
      "firstName": "Sam",
      "id": 8592,
      "lastName": "Lee"
    },
    "clientCorporation": {
      "id": 301,
      "name": "Example Co"
    },
    "dateAdded": 1763020800000,
    "dateLastModified": 1763024400000,
    "description": "Lead month-end close.",
    "employmentType": "Direct Hire",
    "id": 4401,
    "isOpen": true,
    "numOpenings": 1,
    "owner": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "payRate": 0,
    "salary": 85000,
    "startDate": 1767225600000,
    "status": "Accepting Candidates",
    "title": "Senior Accountant"
  }
}
```

### Create task

Add a task to a recruiter's list, optionally about a candidate, contact or job.

**Inputs**

- Subject (`subject`, text, required): What the task is.
- Due (`due`, date and time): When it is due. Leave empty for now.
- Description (`description`, text): More about the task.
- Type (`task_type`, text): One of your Bullhorn task types, such as Call or Meeting.
- Candidate ID (`candidate_id`, text): The candidate it is about.
- Contact (`contact_id`, text): The contact it is about.
- Job (`job_id`, text): The job it is about.
- Assigned to (`owner_id`, text): The Bullhorn user it is for. Leave empty for the API user.

**Outputs**

- `task` (object): The task

**Example output**

```json
{
  "task": {
    "candidate": {
      "firstName": "Jo",
      "id": 5059165,
      "lastName": "Bloggs"
    },
    "clientContact": null,
    "dateAdded": 1763020800000,
    "dateBegin": 1763107200000,
    "dateEnd": 1763107200000,
    "description": "Ask about notice period.",
    "id": 3301,
    "isCompleted": false,
    "jobOrder": {
      "id": 4401,
      "title": "Senior Accountant"
    },
    "owner": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "subject": "Follow up with Jo",
    "type": "Call"
  }
}
```

### Delete record

Delete a candidate, contact, job, submission, note or task. Bullhorn marks it deleted and hides it; an admin can still restore it.

**Inputs**

- Record type (`record_type`, text, required): What kind of record it is. One of: `Candidate`, `ClientContact` (Contact), `JobOrder` (Job), `JobSubmission` (Submission), `Note`, `Task`.
- Record ID (`record_id`, text, required): The record's Bullhorn id.

**Outputs**

- `deleted` (true/false): True once Bullhorn deleted it
- `id` (number): The deleted record's id
- `record_type` (text): The kind of record deleted

**Example output**

```json
{
  "deleted": true,
  "id": 2552,
  "record_type": "Note"
}
```

### Get candidate

Get one candidate with their contact details, status, owner and availability.

**Inputs**

- Candidate ID (`candidate_id`, text, required): The candidate's Bullhorn id.

**Outputs**

- `candidate` (object): The candidate

**Example output**

```json
{
  "candidate": {
    "address": {
      "address1": "100 Summer Street",
      "address2": "",
      "city": "Boston",
      "countryID": 1,
      "state": "MA",
      "zip": "02110"
    },
    "companyName": "Example Co",
    "dateAdded": 1763020800000,
    "dateAvailable": 1767225600000,
    "dateLastModified": 1763024400000,
    "email": "jo@example.com",
    "firstName": "Jo",
    "id": 5059165,
    "lastName": "Bloggs",
    "mobile": "617-555-0101",
    "name": "Jo Bloggs",
    "occupation": "Accountant",
    "owner": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "phone": "617-555-0100",
    "source": "LinkedIn",
    "status": "Active"
  }
}
```

### Get company

Get one client company with its status, phone, website and address.

**Inputs**

- Company (`company_id`, text, required): The company. Pick one, or give its id.

**Outputs**

- `company` (object): The company

**Example output**

```json
{
  "company": {
    "address": {
      "address1": "100 Summer Street",
      "address2": "",
      "city": "Boston",
      "countryID": 1,
      "state": "MA",
      "zip": "02110"
    },
    "companyDescription": "A client company.",
    "companyURL": "https://example.com",
    "dateAdded": 1763020800000,
    "dateLastModified": 1763024400000,
    "id": 301,
    "name": "Example Co",
    "phone": "617-555-0300",
    "status": "Active Account"
  }
}
```

### Get contact

Get one client contact with their company, contact details and owner.

**Inputs**

- Contact (`contact_id`, text, required): The contact. Pick one, or give their id.

**Outputs**

- `contact` (object): The contact

**Example output**

```json
{
  "contact": {
    "address": {
      "address1": "100 Summer Street",
      "address2": "",
      "city": "Boston",
      "countryID": 1,
      "state": "MA",
      "zip": "02110"
    },
    "clientCorporation": {
      "id": 301,
      "name": "Example Co"
    },
    "dateAdded": 1763020800000,
    "dateLastModified": 1763024400000,
    "email": "sam@example.com",
    "firstName": "Sam",
    "id": 8592,
    "lastName": "Lee",
    "mobile": "617-555-0201",
    "name": "Sam Lee",
    "occupation": "Finance Director",
    "owner": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "phone": "617-555-0200",
    "status": "Active"
  }
}
```

### Get job

Get one job with its company, hiring contact, status, rates and description.

**Inputs**

- Job (`job_id`, text, required): The job. Pick one, or give its id.

**Outputs**

- `job` (object): The job

**Example output**

```json
{
  "job": {
    "address": {
      "address1": "100 Summer Street",
      "address2": "",
      "city": "Boston",
      "countryID": 1,
      "state": "MA",
      "zip": "02110"
    },
    "clientBillRate": 0,
    "clientContact": {
      "firstName": "Sam",
      "id": 8592,
      "lastName": "Lee"
    },
    "clientCorporation": {
      "id": 301,
      "name": "Example Co"
    },
    "dateAdded": 1763020800000,
    "dateLastModified": 1763024400000,
    "description": "Lead month-end close.",
    "employmentType": "Direct Hire",
    "id": 4401,
    "isOpen": true,
    "numOpenings": 1,
    "owner": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "payRate": 0,
    "salary": 85000,
    "startDate": 1767225600000,
    "status": "Accepting Candidates",
    "title": "Senior Accountant"
  }
}
```

### Get placement

Get one placement with its candidate, job, dates and rates.

**Inputs**

- Placement ID (`placement_id`, text, required): The placement's Bullhorn id.

**Outputs**

- `placement` (object): The placement

**Example output**

```json
{
  "placement": {
    "candidate": {
      "firstName": "Jo",
      "id": 5059165,
      "lastName": "Bloggs"
    },
    "clientBillRate": 0,
    "dateAdded": 1763020800000,
    "dateBegin": 1767225600000,
    "dateEnd": null,
    "dateLastModified": 1763024400000,
    "employmentType": "Direct Hire",
    "id": 7701,
    "jobOrder": {
      "id": 4401,
      "title": "Senior Accountant"
    },
    "owner": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "payRate": 0,
    "salary": 85000,
    "salaryUnit": "Yearly",
    "status": "Approved"
  }
}
```

### List notes

List the notes on a candidate or contact, or about a job, newest first. Gets one page; to see more, run it again with the next start it gives.

**Inputs**

- Candidate or contact ID (`person_id`, text): Notes about this candidate or contact. Give this, a job, or both.
- Job (`job_id`, text): Notes about this job.
- Action (`note_action`, text): Only notes with this action.
- How many (`count`, number): How many to return, 1 to 500. Defaults to 20. From 1 to 500.
- Start (`start`, number): Where to start, from 0. Use the 'next_start' an earlier run gave. At least 0.

**Outputs**

- `next_start` (number): The Start to give for the next page; 0 when this is the last
- `notes` (list): The notes
- `total` (number): How many match in all (for submissions and notes, how many were read)

**Example output**

```json
{
  "next_start": 0,
  "notes": [
    {
      "action": "Call",
      "commentingPerson": {
        "firstName": "Alex",
        "id": 7,
        "lastName": "Recruiter"
      },
      "comments": "Spoke about the Senior Accountant role.",
      "dateAdded": 1763020800000,
      "id": 2552,
      "jobOrder": {
        "id": 4401,
        "title": "Senior Accountant"
      },
      "personReference": {
        "firstName": "Jo",
        "id": 5059165,
        "lastName": "Bloggs"
      }
    }
  ],
  "total": 1
}
```

### List submissions

List the submissions to a job, of a candidate, or in a status, newest first. Gets one page; to see more, run it again with the next start it gives.

**Inputs**

- Job (`job_id`, text): Only submissions to this job.
- Candidate ID (`candidate_id`, text): Only this candidate's submissions.
- Status (`status`, text): Only submissions in this status.
- How many (`count`, number): How many to return, 1 to 500. Defaults to 20. From 1 to 500.
- Start (`start`, number): Where to start, from 0. Use the 'next_start' an earlier run gave. At least 0.

**Outputs**

- `next_start` (number): The Start to give for the next page; 0 when this is the last
- `submissions` (list): The submissions
- `total` (number): How many match in all (for submissions and notes, how many were read)

**Example output**

```json
{
  "next_start": 0,
  "submissions": [
    {
      "candidate": {
        "firstName": "Jo",
        "id": 5059165,
        "lastName": "Bloggs"
      },
      "comments": "Strong match.",
      "dateAdded": 1763020800000,
      "dateLastModified": 1763024400000,
      "dateWebResponse": 1763020800000,
      "id": 9901,
      "jobOrder": {
        "id": 4401,
        "title": "Senior Accountant"
      },
      "sendingUser": {
        "firstName": "Alex",
        "id": 7,
        "lastName": "Recruiter"
      },
      "source": "Lodol",
      "status": "Submitted"
    }
  ],
  "total": 1
}
```

### Search candidates

Find candidates by name, email, status or owner, or any Lucene query. Gets one page; to see more, run it again with the next start it gives.

**Inputs**

- Name (`name`, text): Only candidates with this name.
- Email (`email`, text): Only candidates with this email address.
- Status (`status`, text): Only candidates with this status, such as Active.
- Owner (`owner_id`, text): Only ones this Bullhorn user owns.
- Advanced query (`query`, text): Any further Lucene search, added to the fields given, such as skillSet:java OR address.city:Boston.
- Order (`sort`, text): Which come first. Defaults to newest first. One of: `-dateAdded` (Newest first), `dateAdded` (Oldest first), `-dateLastModified` (Most recently changed first).
- How many (`count`, number): How many to return, 1 to 500. Defaults to 20. From 1 to 500.
- Start (`start`, number): Where to start, from 0. Use the 'next_start' an earlier run gave. At least 0.

**Outputs**

- `candidates` (list): The candidates
- `next_start` (number): The Start to give for the next page; 0 when this is the last
- `total` (number): How many match in all (for submissions and notes, how many were read)

**Example output**

```json
{
  "candidates": [
    {
      "address": {
        "address1": "100 Summer Street",
        "address2": "",
        "city": "Boston",
        "countryID": 1,
        "state": "MA",
        "zip": "02110"
      },
      "companyName": "Example Co",
      "dateAdded": 1763020800000,
      "dateAvailable": 1767225600000,
      "dateLastModified": 1763024400000,
      "email": "jo@example.com",
      "firstName": "Jo",
      "id": 5059165,
      "lastName": "Bloggs",
      "mobile": "617-555-0101",
      "name": "Jo Bloggs",
      "occupation": "Accountant",
      "owner": {
        "firstName": "Alex",
        "id": 7,
        "lastName": "Recruiter"
      },
      "phone": "617-555-0100",
      "source": "LinkedIn",
      "status": "Active"
    }
  ],
  "next_start": 0,
  "total": 1
}
```

### Search companies

Find client companies by name or status, or any Lucene query. Gets one page; to see more, run it again with the next start it gives.

**Inputs**

- Name (`name`, text): Only companies with this name.
- Status (`status`, text): Only companies with this status.
- Advanced query (`query`, text): Any further Lucene search, added to the fields given, such as skillSet:java OR address.city:Boston.
- Order (`sort`, text): Which come first. Defaults to newest first. One of: `-dateAdded` (Newest first), `dateAdded` (Oldest first), `-dateLastModified` (Most recently changed first).
- How many (`count`, number): How many to return, 1 to 500. Defaults to 20. From 1 to 500.
- Start (`start`, number): Where to start, from 0. Use the 'next_start' an earlier run gave. At least 0.

**Outputs**

- `companies` (list): The companies
- `next_start` (number): The Start to give for the next page; 0 when this is the last
- `total` (number): How many match in all (for submissions and notes, how many were read)

**Example output**

```json
{
  "companies": [
    {
      "address": {
        "address1": "100 Summer Street",
        "address2": "",
        "city": "Boston",
        "countryID": 1,
        "state": "MA",
        "zip": "02110"
      },
      "companyDescription": "A client company.",
      "companyURL": "https://example.com",
      "dateAdded": 1763020800000,
      "dateLastModified": 1763024400000,
      "id": 301,
      "name": "Example Co",
      "phone": "617-555-0300",
      "status": "Active Account"
    }
  ],
  "next_start": 0,
  "total": 1
}
```

### Search contacts

Find client contacts by name, email, company, status or owner, or any Lucene query. Gets one page; to see more, run it again with the next start it gives.

**Inputs**

- Name (`name`, text): Only contacts with this name.
- Email (`email`, text): Only contacts with this email address.
- Company (`company_id`, text): Only ones at this company.
- Status (`status`, text): Only contacts with this status.
- Owner (`owner_id`, text): Only ones this Bullhorn user owns.
- Advanced query (`query`, text): Any further Lucene search, added to the fields given, such as skillSet:java OR address.city:Boston.
- Order (`sort`, text): Which come first. Defaults to newest first. One of: `-dateAdded` (Newest first), `dateAdded` (Oldest first), `-dateLastModified` (Most recently changed first).
- How many (`count`, number): How many to return, 1 to 500. Defaults to 20. From 1 to 500.
- Start (`start`, number): Where to start, from 0. Use the 'next_start' an earlier run gave. At least 0.

**Outputs**

- `contacts` (list): The contacts
- `next_start` (number): The Start to give for the next page; 0 when this is the last
- `total` (number): How many match in all (for submissions and notes, how many were read)

**Example output**

```json
{
  "contacts": [
    {
      "address": {
        "address1": "100 Summer Street",
        "address2": "",
        "city": "Boston",
        "countryID": 1,
        "state": "MA",
        "zip": "02110"
      },
      "clientCorporation": {
        "id": 301,
        "name": "Example Co"
      },
      "dateAdded": 1763020800000,
      "dateLastModified": 1763024400000,
      "email": "sam@example.com",
      "firstName": "Sam",
      "id": 8592,
      "lastName": "Lee",
      "mobile": "617-555-0201",
      "name": "Sam Lee",
      "occupation": "Finance Director",
      "owner": {
        "firstName": "Alex",
        "id": 7,
        "lastName": "Recruiter"
      },
      "phone": "617-555-0200",
      "status": "Active"
    }
  ],
  "next_start": 0,
  "total": 1
}
```

### Search jobs

Find jobs by title, status, company or owner, open or not, or any Lucene query. Gets one page; to see more, run it again with the next start it gives.

**Inputs**

- Title (`title`, text): Only jobs with this title.
- Status (`status`, text): Only jobs with this status.
- Open (`is_open`, text): Only open jobs (Yes) or closed ones (No). Leave empty for both. One of: `yes`, `no`.
- Company (`company_id`, text): Only ones at this company.
- Owner (`owner_id`, text): Only ones this Bullhorn user owns.
- Advanced query (`query`, text): Any further Lucene search, added to the fields given, such as skillSet:java OR address.city:Boston.
- Order (`sort`, text): Which come first. Defaults to newest first. One of: `-dateAdded` (Newest first), `dateAdded` (Oldest first), `-dateLastModified` (Most recently changed first).
- How many (`count`, number): How many to return, 1 to 500. Defaults to 20. From 1 to 500.
- Start (`start`, number): Where to start, from 0. Use the 'next_start' an earlier run gave. At least 0.

**Outputs**

- `jobs` (list): The jobs
- `next_start` (number): The Start to give for the next page; 0 when this is the last
- `total` (number): How many match in all (for submissions and notes, how many were read)

**Example output**

```json
{
  "jobs": [
    {
      "address": {
        "address1": "100 Summer Street",
        "address2": "",
        "city": "Boston",
        "countryID": 1,
        "state": "MA",
        "zip": "02110"
      },
      "clientBillRate": 0,
      "clientContact": {
        "firstName": "Sam",
        "id": 8592,
        "lastName": "Lee"
      },
      "clientCorporation": {
        "id": 301,
        "name": "Example Co"
      },
      "dateAdded": 1763020800000,
      "dateLastModified": 1763024400000,
      "description": "Lead month-end close.",
      "employmentType": "Direct Hire",
      "id": 4401,
      "isOpen": true,
      "numOpenings": 1,
      "owner": {
        "firstName": "Alex",
        "id": 7,
        "lastName": "Recruiter"
      },
      "payRate": 0,
      "salary": 85000,
      "startDate": 1767225600000,
      "status": "Accepting Candidates",
      "title": "Senior Accountant"
    }
  ],
  "next_start": 0,
  "total": 1
}
```

### Search placements

Find placements by candidate, job or status, or any Lucene query. Gets one page; to see more, run it again with the next start it gives.

**Inputs**

- Candidate ID (`candidate_id`, text): Only this candidate's placements.
- Job (`job_id`, text): Only placements in this job.
- Status (`status`, text): Only placements with this status, such as Approved.
- Advanced query (`query`, text): Any further Lucene search, added to the fields given, such as skillSet:java OR address.city:Boston.
- Order (`sort`, text): Which come first. Defaults to newest first. One of: `-dateAdded` (Newest first), `dateAdded` (Oldest first), `-dateLastModified` (Most recently changed first).
- How many (`count`, number): How many to return, 1 to 500. Defaults to 20. From 1 to 500.
- Start (`start`, number): Where to start, from 0. Use the 'next_start' an earlier run gave. At least 0.

**Outputs**

- `next_start` (number): The Start to give for the next page; 0 when this is the last
- `placements` (list): The placements
- `total` (number): How many match in all (for submissions and notes, how many were read)

**Example output**

```json
{
  "next_start": 0,
  "placements": [
    {
      "candidate": {
        "firstName": "Jo",
        "id": 5059165,
        "lastName": "Bloggs"
      },
      "clientBillRate": 0,
      "dateAdded": 1763020800000,
      "dateBegin": 1767225600000,
      "dateEnd": null,
      "dateLastModified": 1763024400000,
      "employmentType": "Direct Hire",
      "id": 7701,
      "jobOrder": {
        "id": 4401,
        "title": "Senior Accountant"
      },
      "owner": {
        "firstName": "Alex",
        "id": 7,
        "lastName": "Recruiter"
      },
      "payRate": 0,
      "salary": 85000,
      "salaryUnit": "Yearly",
      "status": "Approved"
    }
  ],
  "total": 1
}
```

### Submit candidate to job

Submit a candidate to a job, as the API user. The candidate then shows in the job's pipeline.

**Inputs**

- Candidate ID (`candidate_id`, text, required): The candidate's Bullhorn id.
- Job (`job_id`, text, required): The job. Pick one, or give its id.
- Status (`status`, text): One of your Bullhorn submission statuses. Defaults to Submitted; New Lead makes it a web response instead.
- Source (`source`, text): Where the submission came from.
- Comments (`comments`, text): Comments on the submission.

**Outputs**

- `submission` (object): The submission

**Example output**

```json
{
  "submission": {
    "candidate": {
      "firstName": "Jo",
      "id": 5059165,
      "lastName": "Bloggs"
    },
    "comments": "Strong match.",
    "dateAdded": 1763020800000,
    "dateLastModified": 1763024400000,
    "dateWebResponse": 1763020800000,
    "id": 9901,
    "jobOrder": {
      "id": 4401,
      "title": "Senior Accountant"
    },
    "sendingUser": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "source": "Lodol",
    "status": "Submitted"
  }
}
```

### Update candidate

Change a candidate's details, status, owner or address. Fields left empty stay as they are.

**Inputs**

- Candidate ID (`candidate_id`, text, required): The candidate's Bullhorn id.
- First name (`first_name`, text): The candidate's first name. Leave empty to keep it.
- Last name (`last_name`, text): The candidate's last name. Leave empty to keep it.
- Email (`email`, text): The candidate's email address. Leave empty to keep it.
- Phone (`phone`, text): The candidate's phone number. Leave empty to keep it.
- Mobile (`mobile`, text): The candidate's mobile number. Leave empty to keep it.
- Status (`status`, text): One of your Bullhorn candidate statuses, such as Active or New Lead. Leave empty to keep it.
- Source (`source`, text): Where the candidate came from, such as LinkedIn. Leave empty to keep it.
- Current job title (`occupation`, text): Their current job title. Leave empty to keep it.
- Current employer (`company_name`, text): Their current employer. Leave empty to keep it.
- Owner (`owner_id`, text): The Bullhorn user who owns the candidate. Leave empty to keep it.
- Available from (`date_available`, date and time): When the candidate can start. Leave empty to keep it.
- Street address (`address1`, text): The candidate's street address. Leave empty to keep it.
- City (`city`, text): The candidate's city. Leave empty to keep it.
- State (`state`, text): The candidate's state or region, such as MA. Leave empty to keep it.
- Postal code (`zip_code`, text): The candidate's ZIP or postal code. Leave empty to keep it.
- Country (`country_id`, text): The candidate's country. Leave empty to keep it.

**Outputs**

- `candidate` (object): The candidate

**Example output**

```json
{
  "candidate": {
    "address": {
      "address1": "100 Summer Street",
      "address2": "",
      "city": "Boston",
      "countryID": 1,
      "state": "MA",
      "zip": "02110"
    },
    "companyName": "Example Co",
    "dateAdded": 1763020800000,
    "dateAvailable": 1767225600000,
    "dateLastModified": 1763024400000,
    "email": "jo@example.com",
    "firstName": "Jo",
    "id": 5059165,
    "lastName": "Bloggs",
    "mobile": "617-555-0101",
    "name": "Jo Bloggs",
    "occupation": "Accountant",
    "owner": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "phone": "617-555-0100",
    "source": "LinkedIn",
    "status": "Active"
  }
}
```

### Update company

Change a client company's name, status, contact details or address. Fields left empty stay as they are.

**Inputs**

- Company (`company_id`, text, required): The company. Pick one, or give its id.
- Name (`name`, text): The company's name. Leave empty to keep it.
- Status (`status`, text): One of your Bullhorn company statuses, such as Prospect or Active Account. Leave empty to keep it.
- Phone (`phone`, text): The company's main phone number. Leave empty to keep it.
- Website (`website`, text): The company's website address. Leave empty to keep it.
- Description (`description`, text): About the company. Leave empty to keep it.
- Street address (`address1`, text): The company's street address. Leave empty to keep it.
- City (`city`, text): The company's city. Leave empty to keep it.
- State (`state`, text): The company's state or region, such as MA. Leave empty to keep it.
- Postal code (`zip_code`, text): The company's ZIP or postal code. Leave empty to keep it.
- Country (`country_id`, text): The company's country. Leave empty to keep it.

**Outputs**

- `company` (object): The company

**Example output**

```json
{
  "company": {
    "address": {
      "address1": "100 Summer Street",
      "address2": "",
      "city": "Boston",
      "countryID": 1,
      "state": "MA",
      "zip": "02110"
    },
    "companyDescription": "A client company.",
    "companyURL": "https://example.com",
    "dateAdded": 1763020800000,
    "dateLastModified": 1763024400000,
    "id": 301,
    "name": "Example Co",
    "phone": "617-555-0300",
    "status": "Active Account"
  }
}
```

### Update contact

Change a client contact's details, company, status or owner. Fields left empty stay as they are.

**Inputs**

- Contact (`contact_id`, text, required): The contact. Pick one, or give their id.
- First name (`first_name`, text): The contact's first name. Leave empty to keep it.
- Last name (`last_name`, text): The contact's last name. Leave empty to keep it.
- Company (`company_id`, text): The company the contact works for. Leave empty to keep it.
- Email (`email`, text): The contact's email address. Leave empty to keep it.
- Phone (`phone`, text): The contact's phone number. Leave empty to keep it.
- Mobile (`mobile`, text): The contact's mobile number. Leave empty to keep it.
- Job title (`occupation`, text): The contact's job title. Leave empty to keep it.
- Status (`status`, text): One of your Bullhorn contact statuses, such as Active. Leave empty to keep it.
- Owner (`owner_id`, text): The Bullhorn user who owns the contact. Leave empty to keep it.
- Street address (`address1`, text): The contact's street address. Leave empty to keep it.
- City (`city`, text): The contact's city. Leave empty to keep it.
- State (`state`, text): The contact's state or region, such as MA. Leave empty to keep it.
- Postal code (`zip_code`, text): The contact's ZIP or postal code. Leave empty to keep it.
- Country (`country_id`, text): The contact's country. Leave empty to keep it.

**Outputs**

- `contact` (object): The contact

**Example output**

```json
{
  "contact": {
    "address": {
      "address1": "100 Summer Street",
      "address2": "",
      "city": "Boston",
      "countryID": 1,
      "state": "MA",
      "zip": "02110"
    },
    "clientCorporation": {
      "id": 301,
      "name": "Example Co"
    },
    "dateAdded": 1763020800000,
    "dateLastModified": 1763024400000,
    "email": "sam@example.com",
    "firstName": "Sam",
    "id": 8592,
    "lastName": "Lee",
    "mobile": "617-555-0201",
    "name": "Sam Lee",
    "occupation": "Finance Director",
    "owner": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "phone": "617-555-0200",
    "status": "Active"
  }
}
```

### Update job

Change a job's title, status, openings, dates, rates or owner, or open or close it. Fields left empty stay as they are.

**Inputs**

- Job (`job_id`, text, required): The job. Pick one, or give its id.
- Title (`title`, text): The job's title. Leave empty to keep it.
- Hiring contact (`contact_id`, text): The client contact the job is for. Leave empty to keep it.
- Status (`status`, text): One of your Bullhorn job statuses, such as Accepting Candidates. Leave empty to keep it.
- Open (`is_open`, text): Whether the job is open. Leave empty to keep it. One of: `yes`, `no`.
- Employment type (`employment_type`, text): One of your Bullhorn employment types, such as Contract or Direct Hire. Leave empty to keep it.
- Openings (`num_openings`, number): How many people are wanted. Leave empty to keep it. At least 1.
- Start date (`start_date`, date and time): When the job starts. Leave empty to keep it.
- Description (`description`, text): The job description. Leave empty to keep it.
- Owner (`owner_id`, text): The Bullhorn user who owns the job. Leave empty to keep it.
- Salary (`salary`, number): The salary offered. Leave empty to keep it. At least 0.
- Pay rate (`pay_rate`, number): The pay rate, for contract jobs. Leave empty to keep it. At least 0.
- Bill rate (`bill_rate`, number): The rate billed to the client. Leave empty to keep it. At least 0.

**Outputs**

- `job` (object): The job

**Example output**

```json
{
  "job": {
    "address": {
      "address1": "100 Summer Street",
      "address2": "",
      "city": "Boston",
      "countryID": 1,
      "state": "MA",
      "zip": "02110"
    },
    "clientBillRate": 0,
    "clientContact": {
      "firstName": "Sam",
      "id": 8592,
      "lastName": "Lee"
    },
    "clientCorporation": {
      "id": 301,
      "name": "Example Co"
    },
    "dateAdded": 1763020800000,
    "dateLastModified": 1763024400000,
    "description": "Lead month-end close.",
    "employmentType": "Direct Hire",
    "id": 4401,
    "isOpen": true,
    "numOpenings": 1,
    "owner": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "payRate": 0,
    "salary": 85000,
    "startDate": 1767225600000,
    "status": "Accepting Candidates",
    "title": "Senior Accountant"
  }
}
```

### Update submission

Move a submission to another status, such as Interview Scheduled, or change its comments.

**Inputs**

- Submission ID (`submission_id`, text, required): The submission's Bullhorn id.
- Status (`status`, text): One of your Bullhorn submission statuses, such as Interview Scheduled. Leave empty to keep it.
- Comments (`comments`, text): New comments. Leave empty to keep them.

**Outputs**

- `submission` (object): The submission

**Example output**

```json
{
  "submission": {
    "candidate": {
      "firstName": "Jo",
      "id": 5059165,
      "lastName": "Bloggs"
    },
    "comments": "Strong match.",
    "dateAdded": 1763020800000,
    "dateLastModified": 1763024400000,
    "dateWebResponse": 1763020800000,
    "id": 9901,
    "jobOrder": {
      "id": 4401,
      "title": "Senior Accountant"
    },
    "sendingUser": {
      "firstName": "Alex",
      "id": 7,
      "lastName": "Recruiter"
    },
    "source": "Lodol",
    "status": "Submitted"
  }
}
```
