Screener Details Attachment Format

Overview

The screener details attachment provides a standardized JSON format for displaying identity screening results in the Envoy dashboard. When a visitor fails an identity screening check, you can attach rich screening data that admins can review directly in the dashboard interface.

This format enables you to display:

The input data used for screening (name, date of birth, etc.)
Matched records from screening providers
Photos and additional identifying information
Case details, charges, and other relevant data

How It Works

When your plugin processes an identity screening check and determines a visitor should be denied, you can attach screener details to the response. These details are displayed in a modal in the Envoy dashboard, allowing admins to review the screening results and make informed decisions.

The screener details attachment is sent as a JSON object with a specific structure that Envoy's dashboard knows how to render.

Basic Structure

The screener details object contains two main sections:

{
  "input": {
    "fields": []
  },
  "matches": []
}

Input Fields

The input.fields array contains the data that was used to perform the screening. These fields are displayed to admins so they can compare what was searched against what was found.

Each input field has three properties:

Property	Type	Description
`name`	string	The field label (e.g., "Name", "Date of Birth")
`value`	string	The actual value that was searched (e.g., "SMITH, Wayne P.")
`type`	string	Currently only `"text"` is supported

Example:

{
  "input": {
    "fields": [
      {
        "name": "Name",
        "value": "SMITH, Wayne P.",
        "type": "text"
      },
      {
        "name": "Date of Birth",
        "value": "1980-01-15",
        "type": "text"
      },
      {
        "name": "Address",
        "value": "123 Main St, San Francisco, CA",
        "type": "text"
      }
    ]
  }
}

Matches

The matches array contains the actual screening results from your identity screening provider. Each match represents a potential record that was found for the person being screened.

Each match object contains:

Property	Type	Default	Required	Description
`headers`	object		Yes	Column labels for displaying the match data
`fields`	array		Yes	The actual match data fields
`visible-fields-count`	number	6	No	Number of fields to show initially (rest hidden behind "show more")

Example:

{
  "matches": [
    {
      "headers": {
        "name": "Tags",
        "value": "Content"
      },
      "visible-fields-count": 5,
      "fields": [
        {
          "name": "ID",
          "value": "DBP000063",
          "type": "text"
        },
        {
          "name": "Name",
          "value": "SMITH, Wayne P.",
          "type": "text"
        },
        {
          "name": "Datasource",
          "value": "Criminal Records Database",
          "type": "text"
        }
      ]
    }
  ]
}

Match Headers

The headers object defines the column labels when displaying match information:

{
  "name": "Tags",
  "value": "Content"
}

This creates a two-column display where the first column shows field names ("Tags") and the second column shows field values ("Content"). You can customize these labels to match your screening provider's terminology.

Match Fields

Each field in the fields array represents a piece of information about the matched record:

Property	Type	Description
`name`	string	Field label (e.g., "Name", "Photo", "Case Number")
`value`	string	Field value or image URL
`type`	string	Either `"text"` or `"image"`

Field Types:

text: Standard text content that will be displayed as-is
image: A static image URL that will be rendered as an image in the dashboard

Note: Image URLs must be static and publicly accessible. Dynamic or expiring image URLs are not currently supported.

Controlling Visible Fields

Use the visible-fields-count property to control how many fields are initially visible. If a match has more fields than this count, the remaining fields will be hidden behind a "show more" button in the dashboard UI.

{
  "visible-fields-count": 3,
  "fields": [
    { "name": "ID", "value": "DBP000063", "type": "text" },
    { "name": "Name", "value": "SMITH, Wayne P.", "type": "text" },
    { "name": "DOB", "value": "1980-01-15", "type": "text" },
    { "name": "Address", "value": "123 Main St", "type": "text" },
    { "name": "Case Details", "value": "...", "type": "text" }
  ]
}

In this example, only the first 3 fields (ID, Name, DOB) would be initially visible.

Complete Example

Here's a complete screener details object showing a criminal record match:

{
  "input": {
    "fields": [
      {
        "name": "Full Name",
        "value": "SMITH, Wayne P.",
        "type": "text"
      },
      {
        "name": "Date of Birth",
        "value": "1980-01-15",
        "type": "text"
      },
      {
        "name": "Max Record Age",
        "value": "30y",
        "type": "text"
      }
    ]
  },
  "matches": [
    {
      "headers": {
        "name": "Field",
        "value": "Details"
      },
      "visible-fields-count": 6,
      "fields": [
        {
          "name": "Datasource",
          "value": "California Criminal Records",
          "type": "text"
        },
        {
          "name": "Name",
          "value": "SMITH, Wayne Peter",
          "type": "text"
        },
        {
          "name": "Aliases",
          "value": "Wayne Smith, W. Smith",
          "type": "text"
        },
        {
          "name": "Date of Birth",
          "value": "1980-01-15",
          "type": "text"
        },
        {
          "name": "Photo",
          "value": "https://example.com/photos/booking-12345.jpg",
          "type": "image"
        },
        {
          "name": "Addresses",
          "value": "123 Main St, San Francisco, CA 94102",
          "type": "text"
        },
        {
          "name": "Case 1 - Case Number",
          "value": "CR-2015-00123",
          "type": "text"
        },
        {
          "name": "Case 1 - Court Name",
          "value": "San Francisco Superior Court",
          "type": "text"
        },
        {
          "name": "Case 1 - File Date",
          "value": "2015-03-10",
          "type": "text"
        },
        {
          "name": "Case 1 - Charge 1 - Description",
          "value": "Petty Theft",
          "type": "text"
        },
        {
          "name": "Case 1 - Charge 1 - Type",
          "value": "Misdemeanor",
          "type": "text"
        },
        {
          "name": "Case 1 - Charge 1 - Dispositions",
          "value": "Guilty; Probation",
          "type": "text"
        }
      ]
    }
  ]
}

Attaching to Plugin Response

To attach screener details to your plugin response, include them when sending a failed response:

const screenerDetails = {
  label: "Screener Details",
  value: {
    input: {
      fields: [
        { name: "Full Name", value: "John Doe", type: "text" },
        { name: "Date of Birth", value: "1990-05-15", type: "text" }
      ]
    },
    matches: [
      {
        headers: { name: "Field", value: "Details" },
        fields: [
          { name: "Name", value: "John Doe", type: "text" },
          { name: "Record Found", value: "Yes", type: "text" }
        ]
      }
    ]
  },
  type: "json"
};

// Send failed response with screener details
return res.sendFailed(
  'Did not pass initial identity screen.',
  debugInfo,
  screenerDetails
);

Best Practices

Organizing Match Fields

When you have multiple cases or charges, use a consistent naming pattern to group related fields:

{
  "fields": [
    { "name": "Case 1 - Case Number", "value": "...", "type": "text" },
    { "name": "Case 1 - Charge 1 - Description", "value": "...", "type": "text" },
    { "name": "Case 1 - Charge 2 - Description", "value": "...", "type": "text" },
    { "name": "Case 2 - Case Number", "value": "...", "type": "text" },
    { "name": "Case 2 - Charge 1 - Description", "value": "...", "type": "text" }
  ]
}

Setting Visible Fields Count

For matches with many fields (e.g., multiple cases and charges), set visible-fields-count to show the most important information first:

Show identifying information (name, DOB, photo) initially
Hide detailed case information behind "show more"
Typically, 5-8 fields is a good default for initial visibility

Handling Missing Data

If a field has no value, you can either:

Omit the field entirely (recommended for optional data)
Use placeholder text like "N/A" or "Unknown" (for required fields)

{
  "fields": [
    { "name": "Name", "value": "John Doe", "type": "text" },
    { "name": "Photo", "value": "No Photo Available", "type": "text" }
  ]
}

Error Handling

Always wrap the screener details building logic in try-catch blocks to ensure that errors in formatting don't prevent the screening check from completing:

try {
  screenerDetails.value.input.fields = buildInputFields(data);
} catch (error) {
  logger.error('Error building screener input fields', error);
  // Continue with empty or default fields
}

Current Limitations

Input field types: Only "text" type is currently supported for input fields
Image URLs: Only static, publicly accessible image URLs are supported. Dynamic or expiring URLs that require authentication are not supported (planned for future release)
Field types: Only "text" and "image" types are available. Additional types like links, documents, or structured data may be added in future releases

Questions?

If you have questions about implementing screener details in your plugin, reach out to the Envoy developer support team or check the Envoy Developer Hub for additional resources.