Background checks

Use background checks to run a vendor screening on a Payee before you pay them. You pick a package of searches, wrap it in a configuration that a requirement can point at, and order a check for one payer-payee relationship. The vendor runs the check and Wingspan tracks its status.

Read Compliance and verification first for the payer and payee rules shared by all order-style resources.

Before you start

• The payer-payee record exists, and the Payee has linked an Account. A record whose counterparty hasn't linked yet returns 422 on order.
• Scopes: background-checks.request:read and background-checks.request:write.

Endpoints

1. Pick a package

The package catalog is the packages owned by your account's org branch plus every global package. Only active packages are listed. Each package has title, description, a searches array (title, type, group), costPerCheck (amount and currency), and isActive.

curl "https://api.wingspan.app/v3/compliance/background-check-packages" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

Filters: filter[externalId][eq] or [anyOf][], and filter[accountIds][anyOf][] to narrow the org branch. On this resource externalId is the vendor's identifier for the package, not one you set.

2. Create a configuration

A configuration holds the title, instructions, and package that every check ordered through it inherits. A BackgroundCheck requirement definition passes the configuration's id as its dataSourceId. This is the only way to get one.

curl -X POST https://api.wingspan.app/v3/compliance/background-check-configurations \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "title": "Standard screening",
    "instructions": "Complete the application sent to your email.",
    "packageId": "PACKAGE_ID",
    "externalId": "bgc-standard"
  }'

The response is a BackgroundCheckConfiguration with id, title, instructions, packageId, externalId, metadata, events, and actors.

There is no list route for configurations. Keep the id from the create response. To rename externalId or change metadata, use PATCH. An empty metadata object means "unchanged", so you can't clear metadata with it. To change the package, create a new configuration and point the requirement definition at it.

3. Order a check

POST /v3/compliance/background-checks takes:

When a requirementId is sent, the package comes from the requirement's configuration and overrides any packageId a payer sent. The requirementId is checked and then discarded. The returned check does not reference it.

curl -X POST https://api.wingspan.app/v3/compliance/background-checks \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "payerPayeeId": "PAYER_PAYEE_ID", "packageId": "PACKAGE_ID", "externalId": "bg-1042" }'

// 201 Created (trimmed)
{
  "id": "BACKGROUND_CHECK_ID",
  "payerAccountId": "PAYER_ACCOUNT_ID",
  "payeeAccountId": "PAYEE_ACCOUNT_ID",
  "packageId": "PACKAGE_ID",
  "status": "New",
  "externalId": "bg-1042"
}

Ordering the same record and package twice returns the existing active check, not a duplicate. A payer who resets the requirement behind a check gets a new order.

Status

BackgroundCheck.status moves New to Pending (invitation sent), Processing (the Payee submitted the application), then Success or Failed. Only Success completes the backing requirement. A failing result is not described in detail. The payer reviews it in the vendor's report. statusReason carries a reason when there is one. Timestamps are under events: createdAt, sentAt, submittedAt, completedAt, failedAt.

Events: BackgroundCheck.Created, Sent (invitation sent), Submitted, Completed, Failed.

Who sees what

Every party to the check can read it, with different fields:

• The payer sees the vendor status detail and both hosted report URLs (viewReportUrl, manageReportUrl).
• The payee sees applicationUrl and status, and never a report URL or status detail.
• GET /v3/compliance/background-checks lists every check your org branch ordered plus every check run against you as a payee, with the same redaction. Filters: status, payeeAccountId, externalId (each with eq or anyOf), and accountIds[anyOf].

Cancel a check

POST /v3/compliance/background-checks/{backgroundCheckId}/cancel cancels a pending or in-progress order. Only the payer can call it, and it can't be undone. It returns the check.

Errors