View as Markdown
Veremark icon

Veremark ACTION

Create Background Check Request

Initiates a new background check request for a candidate. Veremark sends the candidate an email invitation to complete their part of the screening process. Returns the request GUID — save this to check status later with Get Background Check Request. Use List Criteria first to find the criteria GUID for the background check package you want to run. See the documentation
  • Action
  • Writes data
  • API key
  • SDK
  • MCP

IMPLEMENTATION

Call this tool

Connect a user's Veremark account once, then configure and run Create Background Check Request from your backend or agent.

import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "veremark-create-request",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    veremark: { authProvisionId: "apn_xxxxxxx" },
    criteriaGuid: "Criteria GUID",
    candidateFirstName: "Candidate First Name",
  },
})

console.log(result)

SCHEMA

Inputs

Pipedream supplies the connected account. Your application provides the operation-specific values below. Dynamic inputs are resolved against that user's account.

Create Background Check Request inputs
Property Type Description
criteriaGuid Criteria GUID string
The GUID of the background check criteria/package to use. Use List Criteria to discover available options and their GUIDs.
Required
candidateFirstName Candidate First Name string
The candidate's first name.
Required
candidateLastName Candidate Last Name string
The candidate's last name.
Required
candidateEmail Candidate Email string
The candidate's email address. Veremark will send the screening invitation here.
Required
candidateCountryCode Candidate Country Code string
The candidate's country code (e.g. GB, US).
Optional
candidatePhoneNumber Candidate Phone Number string
The candidate's phone number.
Optional
jobRole Job Role string
The role the candidate is applying for. Example: Software Engineer.
Required
jobExternalId Job External ID string
An external reference ID for the job, used to correlate requests with your own system.
Optional
jobClient Job Client string
The client or organisation associated with this job.
Optional
jobAdditionalInformation Job Additional Information string
Additional context for the background check. Maximum 32 characters.
Optional
webhookUrl Webhook URL string
URL to receive a notification when the request status changes.
Required
webhookMethod Webhook Method string
HTTP method Veremark will use when calling the webhook URL.
Required
sendInitialCandidateEmail Send Initial Candidate Email boolean
Whether Veremark sends the initial invitation email to the candidate. Defaults to true.
Optional
assignedUserGuid Assigned User GUID string
UUID of the Veremark user to assign this request to.
Optional
candidateResponseSalutation Candidate Response Salutation string
The candidate's salutation.
Optional
candidateResponseMiddleName Candidate Response Middle Name string
The candidate's middle name.
Optional
candidateResponseNativeLanguageName Candidate Response Name in Native Language string
The candidate's name written in their native language.
Optional
candidateResponseGender Candidate Response Gender string
The candidate's gender.
Optional
candidateResponseDateOfBirth Candidate Response Date of Birth string
The candidate's date of birth. Format: YYYY-MM-DD.
Optional
candidateResponseTownOfBirth Candidate Response Town of Birth string
The town or city where the candidate was born.
Optional
candidateResponseStateOfBirth Candidate Response State of Birth string
The state or region where the candidate was born.
Optional
candidateResponseCountryOfBirth Candidate Response Country of Birth string
2-letter ISO country code of the candidate's country of birth (e.g., GB, AU).
Optional
candidateResponseNationalityAtBirth Candidate Response Nationality at Birth string
The candidate's nationality at birth (e.g., British).
Optional
candidateResponseMostRecentEmployer Candidate Response Most Recent Employer string
The name of the candidate's most recent employer.
Optional
candidateResponseEmploymentStartDate Candidate Response Employment Start Date string
Start date of the candidate's most recent employment. Format: YYYY-MM-DD.
Optional
candidateResponseEmploymentEndDate Candidate Response Employment End Date string
End date of the candidate's most recent employment. Format: YYYY-MM-DD.
Optional
candidateResponseAddress Candidate Response Address History string
JSON array of address objects for the candidate's residence history. Each object may contain: street_address, city, state, postal_code, country, is_current_residence, period_residence_from.
Optional
candidateResponseEmploymentHistory Candidate Response Employment History string
JSON array of employment objects matching the Veremark API schema. Each object may contain: organisation_name, manager, employment_period_from, employment_period_to, candidate_job_title.
Optional
candidateResponseEducation Candidate Response Education string
JSON object representing the candidate's education history. Fields: institution_name, institution_address, grade_obtained, start_date_attended, end_date_attended, date_of_qualification.
Optional
candidateResponsePassportDetails Candidate Response Passport Details object
Passport details for the candidate. Fields: passport_number, passport_issue_country, passport_issue_date, is_current_passport.
Optional
candidateResponseNationalIdDetails Candidate Response National ID Details object
National ID details for the candidate. Fields: national_id_type, national_id_number.
Optional

REFERENCE

Tool details

Behavior hints are published with the component in the Pipedream registry and surface as MCP tool annotations, so an agent can reason about a tool before it calls it.

Registry key
veremark-create-request
Version
0.0.2
App
Veremark
Authentication
API key
Read-only
No
Destructive
No
Open world
Yes