GLYDE Unity + Bullhorn

Overview

GLYDE Unity provides the most comprehensive ATS integration with Bullhorn, the staffing and recruiting industry's leading CRM and ATS platform. This integration supports candidates, jobs, applications, notes, activities, email messaging, Lucene and JPQL search, event polling, and full ATS proxy discovery — making it the richest connector in the GLYDE ecosystem.

The integration spans the full GLYDE platform: Microsoft Teams, Copilot for Microsoft 365, Power Automate, the GLYDE Unity SDK, the Model Context Protocol (MCP) for AI agents, and the GLYDE Voice Agent. All operations are tenant-isolated using client_uuid and authenticated via a 4-tier OAuth2 strategy with automatic data center resolution and BhRestToken management.

Bullhorn data flows through GLYDE Unity's index-centric normalization pipeline, converting Bullhorn's camelCase field naming and epoch-millisecond dates to GLYDE's canonical snake_case format. The adaptor automatically routes queries between Lucene (searchEntities) for indexed entities and JPQL (queryOrFindEntities) for non-indexed entities.

Architecture & Data Flow

GLYDE Unity acts as an orchestration layer between consuming platforms (Teams, Copilot, Power Platform, SDK) and the Bullhorn REST API. Requests are authenticated, normalized, and routed through the integration adaptor's 8 entity sub-adaptors, which handle entity-specific business logic, data mapping, and dual query syntax (Lucene for indexed entities, JPQL for non-indexed entities).

Teams / Copilot / Power Platform / SDK / MCP Client
                    |
                    v
    ┌─────────────────────────────────────┐
    │     GLYDE Unity REST API            │
    │   api.glydeunity.com/api/unity/*    │
    │                                     │
    │  ┌─ Auth Middleware ─────────────┐   │
    │  │  API Key / JWT / Trusted App │   │
    │  │  Role-based access control   │   │
    │  └──────────────────────────────┘   │
    │                                     │
    │  ┌─ Workflow Route Handler ──────┐  │
    │  │  Validation + Orchestration   │  │
    │  └──────────────────────────────┘   │
    │              |                       │
    │              v                       │
    │  ┌─ Bullhorn Integration Adaptor ─┐ │
    │  │  8 Entity Sub-Adaptors:        │ │
    │  │  candidates / applications /   │ │
    │  │  search / messages / activities│ │
    │  │  activities-unified / notes    │ │
    │  │                                │ │
    │  │  Auto-Routing: Lucene vs JPQL  │ │
    │  │  Template Method Pattern       │ │
    │  │  Index-centric Data Mapping    │ │
    │  └────────────────────────────────┘ │
    │              |                       │
    │              v                       │
    │  ┌─ Bullhorn External Connector ──┐ │
    │  │  bullhorn-connector.ts         │ │
    │  │  16 OpenAPI Operations         │ │
    │  │  BullhornConnectorAuthManager  │ │
    │  │  4-Tier OAuth2 + Data Center   │ │
    │  │  Resolution (loginInfo)        │ │
    │  └────────────────────────────────┘ │
    └──────────────|──────────────────────┘
                   |
                   v
    ┌──────────────────────────────────────┐
    │        Bullhorn REST API             │
    │  rest{DC}.bullhornstaffing.com       │
    │  /{corpToken}/...                    │
    │                                      │
    │  Candidate | JobOrder | JobSubmission │
    │  Note | Placement | ClientContact    │
    │  ClientCorporation | Events          │
    └──────────────────────────────────────┘

Authentication

Credential Fields

Session Management

Sessions are cached in Redis with the key pattern auth:session:{clientUuid}:bullhorn. The session includes the BhRestToken, dynamic rest_url (with corpToken), expiration timestamp, refresh token, access token, data center identifier, and resolved auth URL. Sessions are automatically invalidated when the BhRestToken expires and re-authenticated on the next request.

Token Refresh

The BullhornConnectorAuthManager validates the BhRestToken before each API call by checking the rest_token_expires_at field or parsing the JWT exp claim. If expired, Tier 2 (refresh token) is attempted first, falling back to Tier 3 (programmatic OAuth). The data center is resolved via https://rest.bullhornstaffing.com/rest-services/loginInfo?username=... and cached in Redis with a 24-hour TTL. The auth URL is derived from the data center: https://auth-{dataCenter}.bullhornstaffing.com.

Capabilities

Platform Access

GLYDE Unity provides unified access to Bullhorn across multiple Microsoft 365 and developer platforms.

Entity Mappings

Bullhorn uses different entity names and field conventions. GLYDE Unity normalizes these through the index-centric data pipeline.

Candidate → Candidate

Job → JobOrder

Application → JobSubmission

Note → Note

Activity → Note (via BullhornActivityMapper)

Endpoint Reference

Events & Webhooks

Bullhorn supports subscription-based event polling via the BullhornEventPoller. GLYDE Unity creates event subscriptions for specified entity types and event types, then polls the /event/events endpoint for new events using sequence-based pagination. Events are normalized to the canonical EventObject format via the BullhornEventNormalizer.

Subscription Management

Subscriptions are created via PUT /event/subscription/{subscriptionId} with configurable entity names and event types. The poller gracefully handles 409 (subscription exists) and 404 (subscription not found, triggers recreation).

Event Polling

Events are retrieved via GET /event/events with startSequence for pagination. The sequence is extracted from eventId or requestId in the response. Events are dispatched to handlers for processing (e.g., syncing changes to GLYDE DB).

Configuration Requirements

• OAuth2 Client CredentialsREQUIRED

  Bullhorn issues client_id and client_secret for API access. These must be stored in Azure Key Vault via the GLYDE Unity client configuration.

  client_id: "glyde-bullhorn-client"

• OAuth2 Username/Password (Tier 3)

  For programmatic OAuth authentication without browser redirect. Required only when refresh tokens are unavailable. Stored in Azure Key Vault.

  username: "api_user", password: "********"

• Data Center

  Bullhorn data center identifier (e.g., "rest91"). Auto-resolved via the loginInfo endpoint if not pre-configured. Cached in Redis with 24-hour TTL.

  data_center: "rest91"

• Commenting Person IDREQUIRED

  The Bullhorn user ID used as the author (commentingPerson) for GLYDE-created Note entities. Configured in the client's integration configuration.

  commentingPerson: 12345

• Integration TypeREQUIRED

  The client's integration_type must be set to "bullhorn" in the GLYDE client configuration for the adaptor router to select the correct integration.

  integration_type: "bullhorn"

• Event Subscription Configuration

  Entity types and event types for the BullhornEventPoller subscription. Defaults to JobSubmission and JobOrder with INSERTED, UPDATED, DELETED events.

  entityNames: "JobSubmission,JobOrder", eventTypes: "INSERTED,UPDATED,DELETED"

• REST Token (Pre-supplied)

  An existing BhRestToken can be pre-supplied for Tier 1 authentication, bypassing OAuth entirely. Typically used for quick testing or migration.

  bh_rest_token: "abc123-rest-token"

• REST URL (Pre-supplied)

  A pre-configured dynamic REST URL including corpToken. If not provided, resolved automatically during authentication.

  rest_url: "https://rest91.bullhornstaffing.com/rest-services/arpw2p/"

Known Limitations

• Indexed vs Non-Indexed Entity Routing: Candidate, JobOrder, ClientContact, ClientCorporation, Lead, and Opportunity are indexed and require searchEntities (Lucene syntax). All other entities (JobSubmission, Placement, Note, etc.) require queryOrFindEntities (JPQL syntax). Never mix query syntaxes. The adaptor auto-routes when possible.
• Lucene and JPQL Syntax Must Not Be Mixed: searchEntities uses Lucene (field:value, field:[start TO end]). queryOrFindEntities uses JPQL (field = 'value', field > value). OData operators (ge, le, gt, lt, eq, ne) are never supported.
• searchEntities Prunes Nested Field Projections: The fields parameter for searchEntities only accepts scalar field names. Nested field syntax like candidate(id,firstName) is automatically pruned by the connector. Use queryOrFindEntities with nested fields for non-indexed entities.
• TO_MANY Associations Cannot Be Direct Fields: Fields like skills, certifications, education, and experience are TO_MANY associations in Bullhorn and cannot be requested as direct fields in searchEntities or queryOrFindEntities (returns 400). Use separate entity queries to retrieve associated data.
• Dates Are Epoch Milliseconds: All date fields in Bullhorn are stored as epoch milliseconds (e.g., 1707523200000), not ISO strings. JPQL date comparisons use epoch ms directly. Lucene date ranges can use yyyyMMdd format or epoch ms. The mapper converts to ISO strings for GLYDE consumers.
• orderBy Accepts Property Name Only: The orderBy parameter for queryOrFindEntities accepts only the property name (e.g., dateAdded). Do NOT include ASC/DESC suffixes. For searchEntities, use the sort parameter with -field prefix for descending.
• Job Operations Live in Candidates Adaptor: createJob() and updateJob() are implemented in BullhornAdaptorCandidates, not in a separate Jobs adaptor class. This is a structural quirk, not a functional limitation.
• listCandidateHotlistsByAtsId() Not Implemented: The Tearsheet (hotlist) retrieval operation returns false (not supported) in the current implementation.
• Address Field Returns Object: Bullhorn returns the address field as a full sub-object with city, state, zip, country, latitude, longitude. The mapper handles both object and JSON string formats for compatibility.
• Nested Field Syntax Uses Parentheses: Bullhorn uses parenthesis notation for nested fields: candidate(id,firstName), NOT dot notation (candidate.id). This applies to both fields projection and association traversal.

Version History