Background Checks

📘

We recommend reading the Integration Plugin Overview first.

Overview

This documentation covers two components of the Integration Plugins Framework the createBackgroundCheck action workflow and the webhook processing mechanism.

Together, these enable a complete integration cycle where the platform sends candidates to external background check systems and receives status updates asynchronously.

Background Check Creation Flow

Registration

📘

To register your plugin on your sandbox account, you need to send the Meta Endpoint URL to us via email ([email protected]).

If you don't have sandbox account we will create one for you.

For now all plugins are registered by the Pinpoint Integration Team - this is both for sandbox and live (client's) accounts (as we are still in Public Beta).

Lifecycle Overview

📘

This flow shows the lifecycle for manual triggering. Background checks can also be triggered via Stage Actions (Automatic/Bulk Actions) or from Onboarding.

1. User initiates "Send to ExampleBackgroundChecks" action (where ExampleBackgroundChecks is the name of the background check provider/service defined by the plugin configuration)

   
   

   

   
   

2. Pinpoint calls Action Meta Endpoint to build the form

3. User fills and submits the form (validation and error messages apply)

   
   

   

   
   

4. Platform calls Action Submit Endpoint to process

   1. The plugin calls the external system by passing the params from the form, webhook URL and redirect URL.
   2. External system (background check provider) processes the request
      1. If the request is correct,
         1. The plugin should send a successful response with ID of the background check from the external system.
         2. Pinpoint will then store the Background Check Record with ID of the background check from the external system and request details.
         3. External system initiates the background check for the candidate (typically by contacting the candidate via email)
      2. If the external system rejects the request (validation errors, 5xx)
         1. The plugin should return an error response
         2. Pinpoint shows the errors on the form and allows the user to correct errors and submit again (go back to point 3)

5. Candidate completes the background check process

6. External system sends webhook back to Pinpoint platform (using the webhook URL provided by the plugin)

7. Pinpoint calls Webhook Process Endpoint to process (parse) the webhook payload

   1. Plugin extracts data from the webhook payload and responds with a structured payload to update the Background Check record
   2. Pinpoint updates the Background Check record and sends notifications about the completed background check (if requested by the plugin)

📘

All requests Pinpoint makes to the plugin are POST requests

This is how a newly requested Background Check will be presented in Pinpoint UI:

This is how a completed background check will be presented in Pinpoint UI:

Example implementations

We find it most effective to learn by examining examples. Please find an example working implementation to get an idea of what is involved.

Example Express.js implementation

https://github.com/InfuseGroup/pinpoint_background_check_plugin_express_example

createBackgroundCheck Action

Purpose

The createBackgroundCheck action enables users to send candidate information to an external background check provider. This creates a background check record in both the platform and the external system. It also handles the webhook response from the external system, which updates the background check record in the platform.

Initial Set Up Endpoint (Meta Endpoint)

📘

We currently don't support any authentication for the Meta Endpoint.
If you want to restrict access we recommend checking the domain (allow only from pinpointhq.com) or/and apply rate limiting.

Alternative option is by sending a authentication token as a query parameter (you would provide the token to us directly).

We plan to introduce Basic auth soon.

Endpoint: Defined by your service (e.g. / ) - POST request

Called when: You initiate the setup of your plugin service. Pinpoint calls this endpoint when it registers the plugin in the system to get the name, logo and possible actions and configurations fields. You can see it as a handshake between Pinpoint (Integration Plugins Framework) and the plugin.

Responsibilities:

• Create the integration in Pinpoint
• Fetch configuration fields
• Fetch form field data mappings

Response

Example Meta Response

{
  version: '2.0.0',
  name: 'ExampleBackgroundChecks',
  logoBase64: 'data:image/png;base64,{base64_data}',
  actions: [
    {
      actionType: 'createBackgroundCheck',
      key: 'createExampleBackgroundCheck',
      label: 'Send to ExampleBackgroundChecks',
      iconSvgBase64: 'data:image/svg+xml;base64,{base64_svg}',
      metaEndpoint: '/api/v1/partners/pinpoint/plugin/createBackgroundCheck/meta',
      mappings: [
        { key: 'firstName', label: 'First Name', value: '{{candidate_first_name}}' },
        { key: 'lastName', label: 'Last Name', value: '{{candidate_last_name}}' },
        { key: 'email', label: 'Email', value: '{{{candidate_email}}}' },
        { key: 'cvDocument', value: '{{candidate_cv}}' },
      ],
    },
  ],
  webhookProcessEndpoint: '/api/v1/partners/pinpoint/plugin/createBackgroundCheck/webhook',
  webhookAuthenticationHeader: 'X-Verify',
  configurationFormFields: [
    {
      key: 'apiKey',
      label: 'API Key',
      description: "Your API key for ExampleBackgroundChecks. The correct key is #{CORRECT_API_KEY}",
      type: 'string',
      required: true,
      sensitive: true,
      useAsHttpHeader: 'X_EXAMPLE_BACKGROUND_CHECKS_KEY',
      placeholder: 'For example: uogKYdo4Foufve82P_*Mrpm7uu-bY2AwG7ur.usf',
    },
    {
      key: 'apiBaseUrl',
      label: 'Base URL',
      description:
      'Your Base URL for ExampleBackgroundChecks. Use `http://localhost:14568` if running local server.',
      type: 'string',
      required: true,
      sensitive: false,
      useAsHttpHeader: 'X_EXAMPLE_BASE_URL',
      placeholder: 'For example: http://localhost:14568',
    },
  ],
}

Meta response schema

Action Object Schema

Configuration Form Fields Schema

Mapping Object Schema

List Endpoint Object Schema

Action Meta Endpoint

Endpoint: Defined in the meta response (at actions.[].metaEndpoint, e.g. /createBackgroundCheck/meta) - POST request

Called when: User clicks the action button in the UI (e.g. Send to ExampleBackgroundChecks)

Responsibilities:

• Validate plugin configuration
• Fetch dynamic options from external API (e.g., available background check packages)
• Build and return the form fields

Dynamic form refetching

The Plugin Framework supports form re-rendering based on the value selected by the user. Please find more information here

Request payload

Request Payload Example

{
  payloadVersion: "1.0.0",
  key: "createBackgroundCheck",
  configurationValues: [
    { key: 'apiKey', value: 'aef98an3o9ran9oesd' }
  ],
  formFields: [
    { key: 'selectedPackage', value: 'standard-background-check' },
    { key: 'firstName', value: 'Example' },
    { key: 'email', value: '[email protected]' }
  ],
}

Request Payload Schema

Response

Response Example

Return a form with all necessary fields:

{
  actionVersion: '1.0.0',
  key: 'createBackgroundCheck',
  label: 'Send to ExampleBackgroundChecks',
  description: 'Sends a candidate to the internal ExampleBackgroundChecks system',
  formFields: [
    {
      key: 'selectedPackage',
      label: 'Background Check Package',
      placeholder: 'Select package...',
      type: 'string',
      required: true,
      value: '',
      singleSelectOptions: options
    },
    {
      key: 'firstName',
      label: 'First Name',
      type: 'string',
      required: true,
      readonly: false,
    },
    {
      key: 'lastName',
      label: 'Last Name',
      type: 'string',
      required: true,
      readonly: false
    },
    {
      key: 'email',
      label: 'Email',
      type: 'string',
      required: true,
      readonly: false
    },
    {
      key: 'cvDocument',
      label: 'CV',
      type: 'file',
      required: false,
      readonly: false
    }
  ],
  submitEndpoint: '/api/v1/partners/pinpoint/plugin/createBackgroundCheck/submit'
}

Response Schema

Form Fields Schema

Select Option Object Schema

Action Submit Endpoint

Endpoint: Defined in meta response (via submitEndpoint, e.g. /createBackgroundCheck/submit) - POST request

Called when: User submits the form

Responsibilities:

• Validate configuration and field values
• Send background check creation/invite request to external system
• Return success/error feedback

Payload

The platform sends several key pieces of data in the payload that can be used to facilitate some specific flows with third parties. Key fields are:

• formFields - Form field values submitted by the user - use this to generate payload for background check creation in the background check provider
• configurationValues - Current configuration values from plugin setup (e.g. credentials)
• generatedUuid - Unique identifier for this background check instance - this is different for every request
• generatedUuidRedirectUrl - URL that leads to the Application page in Pinpoint Admin UI (to be shared with external system if needed) - this is different for every request
• webhookUrl - URL where an external system should send status updates to (status change, background check completion, etc) - this is the same for every request. If your third party requests specific webhook URLs for each record, you can build a specific URL in your provider adding the generatedUuid in the query parameters.

Example payload

{
  payloadVersion: '1.0.0',
  key: 'createBackgroundCheck',
  formFields: [
    { key: 'selectedPackage', value: 'standard-background-check' },
    { key: 'firstName', value: 'Example' },
    { key: 'email', value: '[email protected]' }
  ],
  configurationValues: [
    { key: 'cvDocument', value: 'https://example.com/cv.pdf' }
  ],
  generatedUuid: 'f81d4fae-7dec-11d0-a765-00a0c91e6bf6',
  webhookUrl: 'https://app.pinpointhq.xyz/integration_plugins/webhooks/events/1ad84ce0-0e6f-4366-b939-834d63b8faf1',
  generatedUuidRedirectUrl: 'https://app.pinpointhq.xyz/integration_plugins/background_checks/redirect/f81d4fae-7dec-11d0-a765-00a0c91e6bf6'
}

Example Successful Response

{
  resultVersion: '2.0.0',
  key: 'createBackgroundCheck',
  success: true,
  backgroundCheckName: 'Standard Background Check',
  status: 'pending',
  externalIdentifier: 'external-uuid-456',
  externalRecordUrl: 'https://api.example.com/api/external-uuid-456',
  message: {
    title: 'Background check successfully initiated',
    text: 'The background check has been initiated and the candidate will receive an email with instructions.',
    status: 'success'
  }
}

Example Error Response

{
  resultVersion: '2.0.0',
  key: 'createBackgroundCheck',
  success: false,
  toast: {
    error: 'Failed to send background check request to the candidate'
  },
  errors: {
    email: 'Email is invalid',
    firstName: 'First name is required'
  }
}

Request Payload Schema

When the user submits the form, Pinpoint sends a POST request to your submit endpoint with the following payload structure:

Form Field Value Object

Configuration Value Object

Response Schema

Your endpoint must return a response following this schema:

Success Response

Error Response

If validation fails or the external system rejects the request, return:

Message Object Schema

Toast Object Schema

Field Error Object Schema

Persist Object Schema

The persist array allows storing values back to the plugin configuration. These values become available in subsequent API calls through configurationValues in the payload. It is a way to update a plugin configuration field(s) based on the response of an external system.

External Link Object Schema

Webhook Processing

Purpose

Webhooks enable external background check systems to push status updates back to the platform asynchronously. This eliminates the need for polling and provides real-time updates.

The flow looks like this:

1. External system sends a POST request to the webhookUrl (which was sent in the payload to the submit endpoint and plugin sent it to the external system).
2. Plugins Framework receives the webhook, finds the plugin instance based on the ID in the webhookUrl responds with 200 OK and schedules the background job to process the webhook payload.
3. The framework's background job does the following:
   1. Sends a webhook request (with the original payload from the external system) to the plugin's webhookProcessEndpoint (defined in main meta response).
   2. Plugin processes the webhook payload and returns a structured response, which the framework uses to update the background check record in the platform.
   3. The framework updates the background check record in the platform with the parameters returned by the plugin and sends notifications to Pinpoint users (if requested).

Webhook Configuration

Define the webhook process endpoint in the meta response via webhookProcessEndpoint field.

Webhook Process Endpoint

Endpoint: Defined in meta response (webhookProcessEndpoint) (e.g., /webhook/process) - POST request

Called when: External system POSTs to the platform's webhook URL

Responsibilities:

• Parse webhook payload
• Extract background check updates
• Return structured update instructions

Payload

Example request payload

{
  "body": "{\"status\":\"completed\", \"id\":\"external-uuid-123\", \"checkName\":\"Standard Background Check\"}",
  "headers": {
    "Content-Type": "application/json"
  },
  "configurationValues": [
    {
      "key": "apiKey",
      "value": "apwu498roa9wejrfahow4u"
    }
  ]
}

Request Payload Schema

When an external system sends a webhook to Pinpoint, the platform forwards the request to your webhook process endpoint with this payload:

💡

The body field contains the raw webhook payload as a string. You'll need to parse it (e.g., JSON.parse(payload['body'])) to extract the data from your external background check system.

Response

Example successful response

{
  success: true,
  updateBackgroundChecks: [
    {
      externalIdentifier: 'external-uuid-456',
      status: 'completed',
      complete: true,
      result: "clear",
      resultUrl: 'https://example.com/reports/...',
      resultData: [
        {
          key: 'criminal_check_result',
          label: 'Criminal Check Result',
          value: 'No records found'
        },
        {
          key: 'identity_check_result',
          label: 'Identity Check Result',
          value: 'Verified'
        }
      ],
      shouldNotify: true,
      externalLinks: [
        {
          key: 'report',
          label: 'See Candidate in ExampleBackgroundChecks',
          url: 'https://example.com/candidates/external-uuid-456'
        }
      ]
    }
  ]
}

Response Schema

Your webhook process endpoint must return a response following this schema:

Update Background Check Object Schema

Each object in the updateBackgroundChecks array should follow this structure:

📘

Why this is an Array? Although webhooks typically update a single background check, the array structure allows for batch updates in future implementations and provides consistency with other update patterns.

Status Values

The status field in the update object accepts the following values:

External Link Object Schema

Result Data Object Schema

Example of the webhook process logic

def self.webhook_process(payload:, headers: nil)
  api_base_url = headers&.dig(API_BASE_URL_HEADER)
  parsed_body = JSON.parse(payload['body'])

  # Extract background check data
  external_guid = parsed_body['id']
  status = ALLOWED_STATUSES.include?(parsed_body['status']) ? parsed_body['status'] : 'pending'
  result = parsed_body['result']
  report_path = parsed_body['report_path']
  report_url = "#{api_base_url}/#{report_path}"

  # Build background check update
  background_check_update = {
    externalIdentifier: external_guid,  # Matches externalIdentifier from submit
    result: result,
    status: status,
    complete: true,
    shouldNotify: true,  # Trigger platform notifications
    resultUrl: report_url,
    externalLinks: [
      {
        key: 'candidate_url',
        label: 'Candidate Profile',
        url: "https://example.com/candidate/#{external_guid}"
      }
    ]
  }

  # Return array of updates (can update multiple background checks)
  {
    resultVersion: '1.0.0',
    success: true,
    updateBackgroundChecks: [background_check_update]
  }
end

Complete Integration Flow Example

Note: This is a simplified example of the complete flow (payloads are not complete).

1. User Sends Candidate to Background Check

Platform → Plugin (Action Meta Endpoint)

POST /createBackgroundCheck/meta

Plugin → Platform

{
  formFields: [
    { key: 'selectedPackage', type: 'string', singleSelectOptions: [...] },
    { key: 'firstName', type: 'string', value: 'John' },
    { key: 'email', type: 'string', value: '[email protected]' }
  ],
  submitEndpoint: '/createBackgroundCheck/submit'
}

2. User Submits Form

Platform → Plugin (Submit Endpoint)

POST /createBackgroundCheck/submit
{
  formFields: [
    { key: 'selectedPackage', value: 'standard-background-check' },
    { key: 'firstName', value: 'Example' },
    { key: 'email', value: '[email protected]' }
  ],
  generatedUuid: 'f81d4fae-7dec-11d0-a765-00a0c91e6bf6',
  webhookUrl: 'https://app.pinpointhq.xyz/integration_plugins/webhooks/events/1ad84ce0-0e6f-4366-b939-834d63b8faf1',
  generatedUuidRedirectUrl: 'https://app.pinpointhq.xyz/integration_plugins/background_checks/redirect/f81d4fae-7dec-11d0-a765-00a0c91e6bf6'
}

3. Plugin Creates Background Check

Plugin → External Background Check System

POST https://api.example.com/api/background-checks
{
  package: 'standard-background-check',
  email: '[email protected]',
  webhook_url: 'https://app.pinpointhq.xyz/integration_plugins/webhooks/events/1ad84ce0-0e6f-4366-b939-834d63b8faf1?uuid=f81d4fae-7dec-11d0-a765-00a0c91e6bf6',
  platform_url: 'https://app.pinpointhq.xyz/integration_plugins/background_checks/redirect/f81d4fae-7dec-11d0-a765-00a0c91e6bf6',
  uuid: 'f81d4fae-7dec-11d0-a765-00a0c91e6bf6'
}

External System → Plugin

{
  id: 'external-uuid-456',
  status: 'pending',
  description: 'Standard Background Check'
}

If the plugin in implemented as part of the external system codebases, there might be an internal code call instead of HTTP.

4. Plugin Returns Success (or Error) Response

Plugin → Platform

{
  resultVersion: '2.0.0',
  key: 'createBackgroundCheck',
  success: true,
  backgroundCheckName: 'Standard Background Check',
  status: 'pending',
  externalIdentifier: 'external-uuid-456',
  externalRecordUrl: 'https://api.example.com/api/external-uuid-456',
  message: {
    title: 'Background check successfully initiated',
    text: 'The background check has been initiated...',
    status: 'success'
  }
}

5. Candidate Completes Background Check

External System → Platform (Webhook)

POST https://app.pinpointhq.xyz/integration_plugins/webhooks/events/1ad84ce0-0e6f-4366-b939-834d63b8faf1
{
  id: 'external-uuid-456',
  status: 'completed',
  result: 'clear',
  report_path: 'reports/external-uuid-456'
}

6. Platform Processes Webhook

Pinpoint passes back the payload it receives at the webhook endpoint to the provider to carry out any custom logic and return a result to complete the background check update

Platform → Plugin (Webhook Process)

POST /webhook
{
  body: '{"id":"external-uuid-456","status":"completed",...}'
}

Plugin → Platform

{
  success: true,
  updateBackgroundChecks: [
    {
      externalIdentifier: 'external-uuid-456',
      status: 'completed',
      complete: true,
      result: 'clear',
      resultUrl: 'https://api.example.com/reports/...',
      shouldNotify: true,
    }
  ]
}