Integration Plugins Framework Overview

Introduction

The Integration Plugins Framework enables third-party providers to build integrations with Pinpoint Applicant Tracking System (ATS) that deliver a seamless, native experience for end users.

Purpose

The framework serves two primary objectives:

1. Native Look and Feel

Integrations built using the Integration Plugins Framework behave and appear exactly as if they were native Pinpoint integrations. This means:

• Consistent User Experience - Actions, forms, and workflows follow Pinpoint's design patterns
• Seamless Integration - Users don't need to leave Pinpoint or learn different interfaces
• Native Components - Forms, buttons, and notifications use Pinpoint's UI components

This native experience ensures that Pinpoint customers can work with external systems without any friction or learning curve.

2. Development Simplicity

The framework is designed to maximize simplicity for developers building integrations by:

• Clear Contract - Defines a set of endpoints that plugins must implement
• Schema-Based Communication - Specifies exact payload and response structures
• Standardized Patterns - Provides consistent patterns across different integration types
• Minimal Implementation - Requires only 3 core endpoints to build a working integration

Supported Integration Types

The framework supports integrations with three types of external providers:

Supported Actions

The framework defines three action types that plugins can implement:

1. Export Candidate (exportCandidate)

Primary Use Case: Export new hire data to HRIS systems

Additional Use Cases: Export candidate data to any external system at any stage of the hiring process

Key Features:

• Flexible field mapping
• Support for custom fields
• Document/file attachments
• Bi-directional sync capabilities

Webhook Support: ❌ Not currently supported

2. Create Assessment (createAssessment)

Use Case: Send candidates to external assessment platforms

Key Features:

• Dynamic test/assessment selection
• Candidate invitation workflows
• Real-time status updates via webhooks
• Score and report retrieval

Webhook Support: ✅ Supported

3. Create Background Check (createBackgroundCheck)

Use Case: Request background checks from external providers

Key Features:

• Package/check type selection
• Candidate consent workflows
• Status tracking
• Report access

Webhook Support: ✅ Supported

How It Works: The Contract

The Integration Plugins Framework operates on a contract-based architecture:

┌─────────────────────────────────────────────────────────┐
│                  Integration Contract                   │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Framework Responsibilities:                            │
│  • Define required endpoints                            │
│  • Specify request payload schemas                      │
│  • Specify response schemas                             │
│  • Handle routing and lifecycle management              │
│  • Provide webhook infrastructure                       │
│                                                         │
│  Plugin Responsibilities:                               │
│  • Implement required endpoints                         │
│  • Accept payloads matching framework schemas           │
│  • Return responses matching framework schemas          │
│  • Handle communication with external systems           │
│  • Parse and process webhook payloads                   │
│                                                         │
└─────────────────────────────────────────────────────────┘

Framework → Plugin Communication

The framework sends structured payloads to plugin endpoints with:

• API version for compatibility
• User-submitted form data
• Configuration values (API keys, settings)
• Context (webhook URLs, generated UUIDs)

Plugin → Framework Communication

The plugin returns structured responses with:

• Success/failure status
• Result data (external IDs, status, messages)
• UI feedback (toasts, error messages)
• Optional: configuration updates to persist

Required Endpoints

Every plugin must implement three core endpoints to integrate with Pinpoint:

1. Meta Endpoint (Registration & Configuration)

Purpose: Register the plugin and define its capabilities

Called When:

• Initial plugin setup in Pinpoint
• Configuration changes
• Form field mapping updates

Returns:

• Plugin name and logo
• List of supported actions
• Configuration form fields (API keys, URLs, settings)
• Default field mappings
• Webhook configuration

Example:

{
  "version": "1.0.0",
  "name": "ExampleHR",
  "logoBase64": "data:image/png;base64,...",
  "actions": [
    {
      "key": "exportCandidate",
      "label": "Send to ExampleHR",
      "metaEndpoint": "/exportCandidate/meta"
    }
  ],
  "configurationFormFields": [
    {
      "key": "apiKey",
      "label": "API Key",
      "type": "string",
      "sensitive": true
    }
  ]
}

Framework                    Plugin
    │                           │
    │ POST / (meta endpoint)    │
    │──────────────────────────>│
    │                           │
    │                           │
    │ Meta Response             │
    │ (name, logo, actions,     │
    │  config fields)           │
    │<──────────────────────────│
    │                           │
    │ Register Plugin           │
    │ Cache Configuration       │

2. Action Meta Endpoint (Form Definition)

Purpose: Define the form fields that users fill out when executing an action

Called When: User clicks the action button (e.g., "Send to ExampleHR")

Responsibilities:

• Validate plugin configuration
• Fetch dynamic options from external API (e.g., available tests, locations)
• Build form field definitions
• Pre-fill fields with candidate data

Returns:

• Form fields to display
• Field validation rules
• Dynamic select options
• Submit endpoint path

Example:

{
  "actionVersion": "1.0.0",
  "key": "createAssessment",
  "formFields": [
    {
      "key": "testId",
      "label": "Select Test",
      "type": "string",
      "required": true,
      "singleSelectOptions": [
        {"label": "Cognitive Test", "value": "cognitive-001"},
        {"label": "Personality Test", "value": "personality-001"}
      ]
    },
    {
      "key": "email",
      "label": "Email",
      "type": "string",
      "required": true,
      "value": "[email protected]"
    }
  ],
  "submitEndpoint": "/createAssessment/submit"
}

Framework                    Plugin                  External System
    │                           │                           │
    │                           │                           │
    │ POST /action/meta         │                           │
    │ (with config values)      │                           │
    │──────────────────────────>│                           │
    │                           │                           │
    │                           │ GET /api/options          │
    │                           │ (e.g., available tests)   │
    │                           │──────────────────────────>│
    │                           │                           │
    │                           │ Return dynamic options    │
    │                           │<──────────────────────────│
    │                           │                           │
    │ Action Meta Response      │                           │
    │ (form fields,             │                           │
    │  select options,          │                           │
    │  pre-filled values)       │                           │
    │<──────────────────────────│                           │
    │                           │                           │
    │ Render Form               │                           │
    │ Display to User           │                           │

Dynamic form refetching

Plugins framework supports form re-rendering based on value selected by the user. Please find more information here

3. Action Submit Endpoint (Execution)

Purpose: Process the submitted form and communicate with the external system

Called When: User submits the action form

Responsibilities:

• Validate form field values
• Call external system API (or internal logic)
• Handle success and error cases
• Return structured response

Receives:

• User-submitted form field values
• Configuration values (API keys, credentials)
• Webhook URL (for assessment/background check actions)
• Generated UUIDs for tracking

Returns:

On Success:

{
  "resultVersion": "1.0.0",
  "key": "createAssessment",
  "success": true,
  "assessmentName": "Cognitive Test",
  "externalIdentifier": "ext-123",
  "status": "pending",
  "message": "Assessment successfully sent to candidate"
}

On Error:

{
  "success": false,
  "toast": {
    "error": "Failed to create assessment"
  },
  "errors": [
    {
      "key": "email",
      "error": "Email address is invalid"
    }
  ]
}

Framework                    Plugin                  External System
    │                           │                           │
    │                           │                           │
    │ POST /action/submit       │                           │
    │ (form values, config,     │                           │
    │  webhook URL, UUID)       │                           │
    │──────────────────────────>│                           │
    │                           │                           │
    │                           │ POST /api/create          │
    │                           │ (candidate data,          │
    │                           │  webhook URL)             │
    │                           │──────────────────────────>│
    │                           │                           │
    │                           │ Create Record             │
    │                           │ Return external ID        │
    │                           │<──────────────────────────│
    │                           │                           │
    │ Submit Response           │                           │
    │ (success, external ID,    │                           │
    │  status, message, errors) │                           │
    │<──────────────────────────│                           │
    │                           │                           │
    │ Create Record in Pinpoint │                           │
    │ Show Success Message      │                           │
    │                           │                           │
    │                           │                           │
    │                           │                           │ Send Email/Invite to Candidate
    │                           │                           │───────────────────────────────>

Optional Endpoint: Webhook Process Endpoint

For actions that support webhooks (createAssessment and createBackgroundCheck), plugins should implement:

4. Webhook Process Endpoint

Purpose: Parse webhook payloads from external systems and return structured updates

Called When:

1. External system sends webhook to Pinpoint
2. Framework receives webhook and schedules background job
3. Background job calls plugin's webhook endpoint

Receives:

• Raw webhook body from external system
• Original webhook headers
• Configuration values

Returns:

• List of records to update
• New status values
• Scores/results (for assessments)
• External links (reports, detailed results)
• Notification preferences

Example Flow:

External System                Framework               Plugin
      │                           │                      │
      │ POST /webhooks/xyz        │                      │
      │──────────────────────────>│                      │
      │                           │                      │
      │ 200 OK                    │                      │
      │<──────────────────────────│                      │
      │                           │                      │
      │                           │ POST /webhook/process│
      │                           │─────────────────────>│
      │                           │                      │
      │                           │ Parse & Structure    │
      │                           │<─────────────────────│
      │                           │                      │
      │                    Update Records                │
      │                    Send Notifications            │

What Happens:

1. Framework calls plugin's action meta endpoint
2. Plugin fetches dynamic options from external system (e.g., test catalog)
3. Plugin returns form field definitions
4. Framework renders the form with Pinpoint UI components

Getting Started

To build an integration with the Pinpoint Integration Plugins Framework:

1. Read important information for vendors and contact [email protected]

2. Choose Your Integration Type

   • Export Candidate (HRIS)
   • Create Assessment
   • Create Background Check

3. Review Action-Specific Documentation

   • Assessment Plugin Documentation
   • Export Candidate Documentation (comming soon)
   • Background Check Documentation (comming soon)

4. Implement Required Endpoints

   • Meta endpoint (registration)
   • Action meta endpoint (form definition)
   • Action submit endpoint (execution)
   • Webhook endpoint (if applicable)

5. Test Your Integration

   • Reach out to [email protected] with the URL of your plugin service (meta endpoint)
   • Integrations team will register the plugin in your sandbox environment (if you don't have the sandbox account ask the for it via the email)
   • Validate plugin functionality in Pinpoint

Key Concepts

Schema Validation

All requests and responses are validated against defined schemas. This ensures:

• Type safety
• Required field validation
• Enum value validation
• Structure consistency

Field Mapping

The framework supports flexible field mapping:

• Static Mappings: Fixed values (e.g., "Department: Engineering")
• Template Variables: Dynamic values from Pinpoint (e.g., {{candidate_email}})
• User-Editable: Users can modify mappings before submission