> For the complete documentation index, see [llms.txt](https://atlas.anywhere.now/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atlas.anywhere.now/channels-integrations/crm-service/bullhorn.md).
# Bullhorn CRM Service
Configure CRM Service for Bullhorn.
Configure CRM Service for Bullhorn when WebAgent must retrieve Bullhorn information through the Bullhorn REST API.
Before requesting the service, confirm the [shared CRM connector licensing prerequisites](/channels-integrations/crm-service.md#licensing-prerequisites).
## Request Bullhorn CRM Service in OnePortal
1. Request the Bullhorn CRM Service for the customer environment through the current OnePortal, delivery, or support process.
2. Confirm which UCC and WebAgent configuration must consume Bullhorn data.
3. Confirm that Bullhorn is the enabled CRM Service provider before changing provider settings.
4. Use [Configure CRM Service settings](/channels-integrations/crm-service/configure-crm-service-settings.md) for shared request, change, `PluginSettings`, `PluginAttributes`, and secret-handling rules.
{% hint style="info" %}
Exact OnePortal labels can differ by release. Use the current customer-specific request path instead of legacy labels.
{% endhint %}
## Prepare Bullhorn
Prepare the Bullhorn API user and OAuth application before entering CRM Service settings.
| Preparation item | What to prepare | Used by CRM Service |
| -------------------------- | ------------------------------------------------------------------------------ | --------------------------------------- |
| API user | Bullhorn user approved for API access to the objects WebAgent must display. | `Username` and encrypted `Password` |
| OAuth application | Bullhorn OAuth application values approved for CRM Service. | `ClientId` and encrypted `ClientSecret` |
| Login-information endpoint | Endpoint used to retrieve environment-specific Bullhorn URLs for the API user. | Endpoint preparation |
| Bullhorn object scope | Contacts, leads, cases, or related objects that WebAgent must retrieve. | Query and `PluginAttributes` design |
Use [Bullhorn's REST getting-started guidance](https://bullhorn.github.io/Getting-Started-with-REST/) with the approved API user and OAuth application.
To retrieve environment-specific URLs for the API user, use the Bullhorn login-information request:
```http
GET https://rest.bullhornstaffing.com/rest-services/loginInfo?username={API_Username}
```
The response includes Bullhorn environment URLs and identifiers, including `atsUrl`, `oauthUrl`, `restUrl`, `novoUrl`, `dataCenterId`, and `superClusterId`.
| Response value | Use |
| -------------- | ----------------------------------------------------------------- |
| `atsUrl` | Use as `ApplicationHost` when it is the approved customer value. |
| `oauthUrl` | Use as `AuthorizationUrl` when it is the approved customer value. |
| `restUrl` | Use as `RestApiLoginUrl` when it is the approved customer value. |
## Configure Bullhorn CRM Service in Dialogue Cloud Neo / SharePoint
Enter or request these values in the active configuration source for `CrmService` `PluginSettings`.
| Setting | Requirement | Value |
| ------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| `ApplicationHost` | Required | Bullhorn application URL supplied for the environment. Example: `https://api-[CLUSTER_ID].bullhornstaffing.com`. |
| `AuthorizationUrl` | Required | Bullhorn OAuth authorization endpoint supplied for CRM Service. Example: `https://auth-[CLUSTER_ID].bullhornstaffing.com`. |
| `RestApiLoginUrl` | Required | Bullhorn REST API login endpoint supplied for CRM Service. Example: `https://rest-[CLUSTER_ID].bullhornstaffing.com`. |
| `Username` | Required | Bullhorn API-user username. |
| `Password` | Required | Encrypted Bullhorn API-user password handled through the approved secret process. |
| `ClientId` | Required | Bullhorn OAuth application client ID. |
| `ClientSecret` | Required | Encrypted Bullhorn OAuth application client secret handled through the approved secret process. |
Configure Bullhorn field mappings in `CrmService` `PluginAttributes` when the default mapping is not sufficient for the customer data model.
## Configure optional Bullhorn settings in Dialogue Cloud Neo / SharePoint
Add optional settings with scope `CrmService`.
| Setting | Where configured | Default or value guidance |
| ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ShowStatus` | `PluginSettings` | Shows whether the caller is a contact, lead, or unknown. Default: `True`. |
| `DefaultPhoneNumberRegion` | `PluginSettings` | ISO 3166 alpha-2 region code. Default: `ZZ`. |
| `PhoneNumberFormat` | `PluginSettings` | Default: `Wildcard`. Use a more exact supported format when Bullhorn phone fields store numbers consistently. |
| `BaseContactQuery` | `PluginSettings` | Contact search template. Default: `search/ClientContact?BhRestToken={0}&fields={1}&query={2}&count=100`. |
| `BaseLeadQuery` | `PluginSettings` | Lead search template. Default: `search/Candidate?BhRestToken={0}&fields={1}&query={2}&count=100`. |
| `BaseAuthCodeQuery` | `PluginSettings` | Authorization-code request template. Default behavior uses the OAuth authorize path and placeholders for client/user credentials; keep secrets in the approved secret process. |
| `BaseTokenQuery` | `PluginSettings` | Token request template. Default: `/oauth/token?{0}`. |
| `BaseLoginQuery` | `PluginSettings` | REST login template. Default: `/rest-services/login?access_token={0}&version=*`. |
| `BaseCaseContactQuery` | `PluginSettings` | Case retrieval for contacts. Default: `search/JobOrder?BhRestToken={0}&fields={1}&query={2}&count=100`. |
| `BaseCaseLeadQuery` | `PluginSettings` | Case retrieval for leads. Default: `search/JobSubmission?BhRestToken={0}&fields={1}&query={2}&count=100`. |
| `ContactCaseFilter` | `PluginSettings` | Contact-to-case filter. Default: `clientContact.id:{0}`. |
| `LeadCaseFilter` | `PluginSettings` | Lead-to-case filter. Default: `candidate.id:{0}`. |
| `CaseStatus` | `PluginSettings` | Maps Bullhorn status text to WebAgent status. Default mappings include `Resolved`, `Canceled`, and `Problem Solved` as `Closed`; `Active`, `In Progress`, `On Hold`, `Waiting for Details`, and `Researching` as `Open`. |
| `UseDefaultPluginAttributes` | `PluginSettings` | Default behavior: if the setting is absent or `True`, CRM Service uses default Bullhorn `PluginAttributes`. Set to `False` only when all required Bullhorn `PluginAttributes` will be maintained manually. |
| Bullhorn `PluginAttributes` | `PluginAttributes` | Map Bullhorn attributes to WebAgent contact, contact-search, case, and case-search output. |
Bullhorn query and mapping guidance
For Bullhorn `PluginAttributes`, use Bullhorn attributes as `SystemName` values. If an attribute comes from a linked entity, include the alias before the attribute. Use:
* `DisplayName` for the label shown in WebAgent.
* `ShowOnExtensionWindow` to control whether WebAgent displays the value.
* `Order`; restart numbering for each `Category`.
* `FieldType` values such as `Id`, `Name`, `PhoneNumber`, `SipAddress`, `Email`, `Date`, and `Search`.
* `Hyperlink` to make a value clickable; include `SystemName` placeholders in square brackets when the link needs field values.
* `ShowOnToast` to force the attribute into the query.
Only disable default Bullhorn attributes when the replacement mapping includes the required identifier, searchable phone/email/SIP fields, and case fields.
### Default `PluginAttributes`
The default Bullhorn rows are used when `UseDefaultPluginAttributes` is absent or `True`. Preserve the default spelling and punctuation in `FieldTypes` and `Hyperlink` values, including `Sipaddress`, `Email. Search`, and the Submission link spacing.
| DisplayName | SystemName | Category | Order | ShowOnExtensionWindow | FieldTypes | Hyperlink | ShowOnToast |
| -------------------- | ---------------------- | ---------------- | ----: | --------------------- | --------------------- | ------------------------------------------------------------------------ | ----------- |
| Case ID | `id` | Case | 0 | No | `Id` | `[HOSTURL]/BullhornSTAFFING/OpenWindow.cfm?Entity=JobOrder&id=[id]` | Yes |
| Title | `title` | Case | 1 | Yes | `Name, Search` | | |
| Description | `description` | Case | 2 | Yes | | | |
| Date | `dateLastModified` | Case | 3 | Yes | `Date` | | |
| Status | `status` | Case | 4 | Yes | `FormattedValue` | | |
| Id | `id` | Contact | 0 | No | `Id` | `[HOSTURL]/BullhornSTAFFING/OpenWindow.cfm?Entity=ClientContact&id=[id]` | Yes |
| Name | `name` | Contact | 1 | Yes | `Name` | | No |
| Email | `email` | Contact | 2 | Yes | `Email, SipAddress` | | No |
| Phone | `phone` | Contact | 3 | Yes | `PhoneNumber` | | No |
| Occupation | `occupation` | Contact | 4 | Yes | | | No |
| Address | `address` | Contact | 5 | Yes | | | No |
| Office | `office` | Contact | 6 | Yes | | | No |
| Division | `division` | Contact | 7 | Yes | | | No |
| PreferredContact | `preferredContact` | Contact | 8 | Yes | | | No |
| ReferredByPerson | `referredByPerson` | Contact | 9 | Yes | | | No |
| Category | `category` | Contact | 10 | Yes | | | No |
| Description | `description` | Contact | 11 | Yes | | | No |
| ReportToPerson | `reportToPerson` | Contact | 12 | Yes | | | No |
| Comments | `comments` | Contact | 13 | Yes | | | No |
| Phone2 | `phone2` | Contact | 14 | Yes | `PhoneNumber` | | No |
| Phone3 | `phone3` | Contact | 15 | Yes | `PhoneNumber` | | No |
| Mobile | `mobile` | Contact | 16 | Yes | `PhoneNumber` | | No |
| Email2 | `email2` | Contact | 17 | Yes | `Email, SipAddress` | | No |
| Email3 | `email3` | Contact | 18 | Yes | `Email, Sipaddress` | | No |
| Name | `name` | ContactSearch | 0 | No | `Name, Search` | | Yes |
| Email | `email` | ContactSearch | 1 | No | `Email, Search` | | Yes |
| Email2 | `email2` | ContactSearch | 2 | No | `Email, Search` | | Yes |
| Email3 | `email3` | ContactSearch | 3 | No | `Email. Search` | | Yes |
| Phone | `phone` | ContactSearch | 4 | No | `PhoneNumber, Search` | | Yes |
| Mobile | `mobile` | ContactSearch | 5 | No | `PhoneNumber, Search` | | Yes |
| Phone2 | `phone2` | ContactSearch | 6 | No | `PhoneNumber, Search` | | Yes |
| Phone3 | `phone3` | ContactSearch | 7 | No | `PhoneNumber, Search` | | Yes |
| Id | `id` | ContactSearch | 8 | No | `Id, Search` | | Yes |
| Id | `id` | Lead | 0 | No | `Id` | `[HOSTURL]/BullhornSTAFFING/OpenWindow.cfm?Entity=Candidate&id=[id]` | Yes |
| CompanyUrl | `companyURL` | Lead | 1 | No | | | Yes |
| Name | `name` | Lead | 2 | No | `Name` | | Yes |
| Email | `email` | Lead | 3 | Yes | `Email, SipAddress` | | No |
| Phone | `phone` | Lead | 4 | Yes | `PhoneNumber` | | No |
| Occupation | `occupation` | Lead | 5 | Yes | | | No |
| Address | `address` | Lead | 6 | Yes | | | No |
| Salary | `salary` | Lead | 7 | Yes | | | No |
| CompanyName | `companyName` | Lead | 8 | Yes | | | No |
| Type | `type` | Lead | 9 | Yes | | | No |
| EmploymentPreference | `employmentPreference` | Lead | 10 | Yes | | | No |
| PreferredContact | `preferredContact` | Lead | 11 | Yes | | | No |
| Owner | `owner` | Lead | 12 | Yes | | | No |
| Comments | `comments` | Lead | 13 | Yes | | | No |
| Description | `description` | Lead | 14 | Yes | | | No |
| TravelMethod | `travelMethod` | Lead | 15 | Yes | | | No |
| TravelLimit | `travelLimit` | Lead | 16 | Yes | | | No |
| ReferredBy | `referredBy` | Lead | 17 | Yes | | | No |
| Phone2 | `phone2` | Lead | 18 | Yes | `PhoneNumber` | | No |
| Phone3 | `phone3` | Lead | 19 | Yes | `PhoneNumber` | | No |
| Mobile | `mobile` | Lead | 20 | Yes | `PhoneNumber` | | No |
| WorkPhone | `workPhone` | Lead | 21 | Yes | `PhoneNumber` | | No |
| WillRelocate | `willRelocate` | Lead | 22 | Yes | `PhoneNumber` | | No |
| Email2 | `email2` | Lead | 23 | Yes | `Email, SipAddress` | | No |
| Email3 | `email3` | Lead | 24 | Yes | `Email, Sipaddress` | | No |
| Id | `id` | LeadSearch | 0 | No | `Id, Search` | | Yes |
| Name | `name` | LeadSearch | 1 | No | `Name, Search` | | Yes |
| Mobile | `mobile` | LeadSearch | 2 | No | `PhoneNumber, Search` | | Yes |
| Email | `email` | LeadSearch | 3 | No | `Email, Search` | | Yes |
| Email2 | `email2` | LeadSearch | 4 | No | `Email, Search` | | Yes |
| Email3 | `email3` | LeadSearch | 5 | No | `Email. Search` | | Yes |
| Phone | `phone` | LeadSearch | 6 | No | `PhoneNumber, Search` | | Yes |
| Phone2 | `phone2` | LeadSearch | 7 | No | `PhoneNumber, Search` | | Yes |
| Phone3 | `phone3` | LeadSearch | 8 | No | `PhoneNumber, Search` | | Yes |
| WorkPhone | `workPhone` | LeadSearch | 9 | No | `PhoneNumber, Search` | | Yes |
| Submission ID | `id` | Submission | 0 | No | `Id, Search` | `[HOSTURL]/ BullhornSTAFFING/OpenWindow.cfm?Entity=jobOrder&id=[id]` | Yes |
| Title | `jobOrder.title` | Submission | 1 | Yes | `Name, Search` | | |
| Description | `jobOrder.description` | Submission | 2 | Yes | | | |
| Date | `dateLastModified` | Submission | 3 | Yes | `Date` | | |
| Status | `status` | Submission | 4 | Yes | `FormattedValue` | | |
| Submission ID | `id` | SubmissionSearch | 0 | No | `Id, Search` | `[HOSTURL]BullhornSTAFFING/OpenWindow.cfm?Entity=jobOrder&id=[id]` | Yes |
| Title | `jobOrder.title` | SubmissionSearch | 1 | Yes | `Name, Search` | | |
## Validate Bullhorn CRM Service
1. Confirm that CRM Service can reach the Bullhorn endpoint.
2. Search for a known Bullhorn contact or lead from WebAgent.
3. Confirm that expected Bullhorn fields appear in WebAgent.
4. Confirm that phone-number recognition returns the expected Bullhorn record.
## References
* [Bullhorn REST getting-started guidance](https://bullhorn.github.io/Getting-Started-with-REST/)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://atlas.anywhere.now/channels-integrations/crm-service/bullhorn.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.