Skip to main content

Initiate helpdesk identity verification from an external integration​

External-integration twin of PostHelpdeskVerifyInitiate. A push notification is sent to the target user's sensor (without the code); the operator reads the returned code aloud and the user types it into their app.

A 404 means the subject has no active sensor — the integration should offer the email-OTP family as a fallback rather than treating it as a dead end.

Header Parameters
  • SlashID-OrgID string required

    The organization ID

    Example: af5fbd30-7ce7-4548-8b30-4cd59cb2aba1
Request Body required
  • target_email email required

    Email address of the user to verify identity to

  • connection_id string required

    The external identity connection ID. Configuration on the integration side (a ServiceNow system property set at install), not something the agent picks per call.

  • operator object required
  • email email required

    The human operating the integration (e.g. the ServiceNow agent). MUST be derived server-side by the integration (ServiceNow: gs.getUser().getEmail()), never supplied by its own client. Resolved to a SlashID console person holding a verifier role; 403 if it does not resolve or lacks the role.

  • assertion string required

    Possible values: [integration_asserted, idp_verified]

    How the operator identity was established. integration_asserted — the calling integration vouches for it under its own API credential; idp_verified — proven to SlashID directly. Recorded on every attempt so that a later move to per-agent authentication does not change what historical audit rows meant. Only integration_asserted is accepted today.

  • external_metadata object
  • source string required

    Possible values: [servicenow]

  • instance string

    ServiceNow instance name.

  • table string
  • record_id string

    sys_id of the Call or Incident. Frequently absent — verification commonly starts at call intake, on a record that has not been saved yet and therefore has no sys_id.

  • display_id string

    Human-facing record number, e.g. INC0012345.

Responses

Verification initiated successfully

Schema
  • meta object
  • pagination object
  • limit integer
  • offset integer
  • total_count int64
  • cursor_pagination object

    Cursors are opaque. Follow the tokens the server returns; never construct, parse or modify one.

  • limit integer
  • next_cursor string

    Opaque token addressing the next page. Absent on the last page.

  • prev_cursor string

    Opaque token addressing the previous page. Absent on the first page.

  • last_cursor string

    Opaque token addressing the final page directly, so a client can jump to the end without a total count.

  • total_count int64

    Total number of matching items. Returned on the FIRST page only; clients cache it for the remainder of the walk.

  • errors object[]
  • httpcode integer
  • message string
  • result object
  • session_id string

    Unique helpdesk verification session identifier

  • verification_code string

    Possible values: Value must match regular expression ^\d{6}$

    The 6-digit code to read to the caller over voice

  • target_email string

    Email of the target user

  • expires_at date-time

    When this verification session expires

  • turn_order string

    Possible values: [sensor_first, admin_first]

    Which party proves their identity first, resolved from the connection's settings. sensor_first — the caller reads their code first, and the integration should collect it before displaying verification_code. admin_first — the operator reads verification_code aloud first, then collects the caller's.

    Required rather than optional on purpose: an absent field invites a client to default to sensor_first, which is silently the wrong flow for an admin_first org.