# Create Background Check Request — Veremark

> 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…

- Key: `veremark-create-request`
- Type: Action (Write)
- Version: 0.0.2
- App: Veremark (`veremark`) — https://pipedream.com/apps/veremark.md
- This page (HTML): https://pipedream.com/apps/veremark/actions/create-request
- Hints: open-world
- Source: https://github.com/PipedreamHQ/pipedream/blob/master/components/veremark/actions/create-request/create-request.mjs

## Description

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](https://api.veremark.com/external/v1/docs/#tag/request/operation/createRequest)

## Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `criteriaGuid` | `string` | Yes | The GUID of the background check criteria/package to use. Use List Criteria to discover available options and their GUIDs. |
| `candidateFirstName` | `string` | Yes | The candidate's first name. |
| `candidateLastName` | `string` | Yes | The candidate's last name. |
| `candidateEmail` | `string` | Yes | The candidate's email address. Veremark will send the screening invitation here. |
| `candidateCountryCode` | `string` | No | The candidate's country code (e.g. GB, US). |
| `candidatePhoneNumber` | `string` | No | The candidate's phone number. |
| `jobRole` | `string` | Yes | The role the candidate is applying for. Example: Software Engineer. |
| `jobExternalId` | `string` | No | An external reference ID for the job, used to correlate requests with your own system. |
| `jobClient` | `string` | No | The client or organisation associated with this job. |
| `jobAdditionalInformation` | `string` | No | Additional context for the background check. Maximum 32 characters. |
| `webhookUrl` | `string` | Yes | URL to receive a notification when the request status changes. |
| `webhookMethod` | `string` | Yes | HTTP method Veremark will use when calling the webhook URL. |
| `sendInitialCandidateEmail` | `boolean` | No | Whether Veremark sends the initial invitation email to the candidate. Defaults to true. |
| `assignedUserGuid` | `string` | No | UUID of the Veremark user to assign this request to. |
| `candidateResponseSalutation` | `string` | No | The candidate's salutation. |
| `candidateResponseMiddleName` | `string` | No | The candidate's middle name. |
| `candidateResponseNativeLanguageName` | `string` | No | The candidate's name written in their native language. |
| `candidateResponseGender` | `string` | No | The candidate's gender. |
| `candidateResponseDateOfBirth` | `string` | No | The candidate's date of birth. Format: YYYY-MM-DD. |
| `candidateResponseTownOfBirth` | `string` | No | The town or city where the candidate was born. |
| `candidateResponseStateOfBirth` | `string` | No | The state or region where the candidate was born. |
| `candidateResponseCountryOfBirth` | `string` | No | 2-letter ISO country code of the candidate's country of birth (e.g., GB, AU). |
| `candidateResponseNationalityAtBirth` | `string` | No | The candidate's nationality at birth (e.g., British). |
| `candidateResponseMostRecentEmployer` | `string` | No | The name of the candidate's most recent employer. |
| `candidateResponseEmploymentStartDate` | `string` | No | Start date of the candidate's most recent employment. Format: YYYY-MM-DD. |
| `candidateResponseEmploymentEndDate` | `string` | No | End date of the candidate's most recent employment. Format: YYYY-MM-DD. |
| `candidateResponseAddress` | `string` | No | 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. |
| `candidateResponseEmploymentHistory` | `string` | No | 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. |
| `candidateResponseEducation` | `string` | No | JSON object representing the candidate's education history. Fields: institution_name, institution_address, grade_obtained, start_date_attended, end_date_attended, date_of_qualification. |
| `candidateResponsePassportDetails` | `object` | No | Passport details for the candidate. Fields: passport_number, passport_issue_country, passport_issue_date, is_current_passport. |
| `candidateResponseNationalIdDetails` | `object` | No | National ID details for the candidate. Fields: national_id_type, national_id_number. |

## Run it

**MCP**

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
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 accessToken = await pd.rawAccessToken

const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": process.env.PIPEDREAM_PROJECT_ID!,
        "x-pd-environment": "production",
        "x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
        "x-pd-app-slug": "veremark",
      },
    },
  },
)

const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)

const { tools } = await mcp.listTools()

// listTools() hands your model this tool's input schema, so it can
// fill the arguments itself:
const result = await mcp.callTool({
  name: "veremark-create-request",
  arguments: {
    criteriaGuid: "Criteria GUID",
    candidateFirstName: "Candidate First Name",
  },
})
```

**TypeScript**

```ts
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)
```

**cURL**

```bash
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: production" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "{external_user_id}",
    "id": "veremark-create-request",
    "configured_props": {
      "veremark": { "authProvisionId": "apn_xxxxxxx" },
      "criteriaGuid": "Criteria GUID",
      "candidateFirstName": "Candidate First Name"
    }
  }'
```

---

- App: https://pipedream.com/apps/veremark.md · All apps: https://pipedream.com/apps