# Sterling

> Run Sterling background checks from your workflows: add candidates, order screenings with your packages and invite candidates to consent, wait for results, save reports, attach documents and manage adverse action.

App · 23 actions. Web page: https://docs.lodol.com/docs/integrations/sterling

## Actions

### Attach document to candidate

Attach a file to a candidate, such as their resume, for searches that need one.

**Inputs**

- Candidate ID (`candidate_id`, text, required): The candidate, from 'Create candidate' or 'Find candidates'.
- File (`document`, text, required): The file to attach: PDF, TIFF, JPG, PNG, DOC or DOCX, up to 7 MB.
- Kind of document (`document_type`, text, required): What the file is. One of: `consent` (Consent form), `resume`, `drivers-license` (Driver's license), `passport`, `other`.

**Outputs**

- `document` (object): The document

**Example output**

```json
{
  "document": {
    "createdAt": "2020-11-20T19:18:16Z",
    "documentType": "consent",
    "fileName": "Consent.pdf",
    "id": "crm_11448293",
    "reportItemId": "",
    "url": "https://api.us.sterlingcheck.app/v2/screenings/1801020638/documents/crm_11448293"
  }
}
```

### Attach document to screening

Attach a file to a background check, such as a signed consent form or the driver's license Sterling asked for.

**Inputs**

- Screening ID (`screening_id`, text, required): The screening (background check), such as 1801020638, from 'Create screening' or a callback.
- File (`document`, text, required): The file to attach: PDF, TIFF, JPG, PNG, DOC or DOCX, up to 7 MB.
- Kind of document (`document_type`, text, required): What the file is. One of: `consent` (Consent form), `resume`, `drivers-license` (Driver's license), `passport`, `other`.

**Outputs**

- `document` (object): The document

**Example output**

```json
{
  "document": {
    "createdAt": "2020-11-20T19:18:16Z",
    "documentType": "consent",
    "fileName": "Consent.pdf",
    "id": "crm_11448293",
    "reportItemId": "",
    "url": "https://api.us.sterlingcheck.app/v2/screenings/1801020638/documents/crm_11448293"
  }
}
```

### Create candidate

Add a candidate: the person to run a background check on. Give what the package needs, or leave it for the candidate to fill in through an invite.

**Inputs**

- First name (`given_name`, text, required): Their legal first name.
- Last name (`family_name`, text, required): Their legal last name.
- Email (`email`, text, required): Their email address; Sterling sends invites here. It must not be used by another candidate.
- Middle name (`middle_name`, text): Their middle name. Sterling needs it, or 'Has no middle name' switched on.
- Has no middle name (`no_middle_name`, true/false): Switch on when the candidate has no legal middle name.
- Suffix (`suffix`, text): Such as Jr. or III.
- Phone (`phone`, text): With the country code, such as +15555551234.
- Date of birth (`dob`, date): Their date of birth. Many packages need it.
- Social Security number (`ssn`, text): 9 digits, as 123-45-6789. US criminal searches need it.
- Street address (`address_line`, text): Where they live now, such as 123 Main Street.
- City (`city`, text): The address's city or town.
- State or region (`state`, text): Such as WA or US-WA (for the US and Canada, the two-letter code).
- Postal code (`postal_code`, text): Zip or postal code, with no dashes.
- Country (`country`, text): The address's two-letter country code. Defaults to US.
- Driver's license number (`license_number`, text): Needed for driving record searches.
- Driver's license state (`license_state`, text): Where the license was issued, such as CA or US-CA.
- Language (`language`, text): The language for Sterling's invite and forms, such as en-US or es-US.
- Your reference (`client_reference_id`, text): Your own unique id for them, such as an applicant id. Leave empty and one is made for you.

**Outputs**

- `candidate` (object): The candidate

**Example output**

```json
{
  "candidate": {
    "address": {
      "addressLine": "123 Main Street",
      "countryCode": "US",
      "municipality": "Orlando",
      "postalCode": "12345",
      "regionCode": "US-FL"
    },
    "clientReferenceId": "999124441",
    "confirmedNoMiddleName": false,
    "dob": "XXXX-01-20",
    "driversLicense": {
      "issuingAgency": "US-CA",
      "licenseNumber": "S1234567",
      "type": "personal"
    },
    "email": "john.doe@example.com",
    "familyName": "Doe",
    "givenName": "John",
    "id": "3e4f84e3-9078-4451-a8b8-5897f4f4f4e3",
    "middleName": "Jay",
    "phone": "+14041231234",
    "primaryLanguage": "en-US",
    "screeningIds": [],
    "ssn": "XXXXX6789",
    "suffix": "Jr."
  }
}
```

### Create report link

Make a link to a background check's PDF report. It works once, within 5 minutes.

**Inputs**

- Screening ID (`screening_id`, text, required): The screening (background check), such as 1801020638, from 'Create screening' or a callback.

**Outputs**

- `pdf_url` (text): The one-time link to the PDF
- `screening_id` (text): The screening

**Example output**

```json
{
  "pdf_url": "https://api.us.sterlingcheck.app/v2/screenings/1801020638/report.pdf?token=abc",
  "screening_id": "1801020638"
}
```

### Create screening

Order a background check on a candidate with one of your packages. Sterling bills for it on Production. Optionally invite the candidate to give consent and fill in their details first.

**Inputs**

- Candidate ID (`candidate_id`, text, required): The candidate, from 'Create candidate' or 'Find candidates'.
- Package (`package_id`, text, required): The screening package: the set of searches to run.
- Work city (`employment_city`, text, required): The city or town where the candidate will work.
- Work state or region (`employment_state`, text, required): Where they will work, such as WA or US-WA.
- Work country (`employment_country`, text): The two-letter country code. Defaults to US.
- How the candidate gives their details (`invite_method`, text): With no invite, Sterling runs the check on what the candidate record already holds. With an invite, the candidate signs Sterling's consent and fills in what's missing first (required outside the US). One of: `none` (No invite: Sterling already has everything it needs), `email` (Sterling emails the candidate a form to fill in), `link` (Give me a link to the form to send the candidate myself). Default: `none`.
- Candidate form (`candidate_form_id`, text): Which Candidate Hub form the invite uses. Defaults to Consent Plus. Only when How the candidate gives their details is Sterling emails the candidate a form to fill in or Give me a link to the form to send the candidate myself.
- Page after the form (`redirect_url`, text): Where to send the candidate when they finish, such as your careers page (https://). Sterling must turn this on for your account.
- Also text the invite (`send_sms`, true/false): Text the invite to the candidate's phone too. Only with consent to texts; Sterling must turn this on for your account. Only when How the candidate gives their details is Sterling emails the candidate a form to fill in.
- Sub-account (`account_id`, text): Order under this sub-account. Leave empty for your main account.
- Bill code (`bill_code`, text): Your bill code for the order, if your account uses them.
- Job position (`job_position`, text): The position the check is for.
- Custom fields (`custom_fields`, object): Values for custom fields set up on your Sterling account, by field name, such as Job Opening ID.
- Requested by: email (`requester_email`, text): Who asked for the check; Sterling emails them when it's done. Give their first and last name too.
- Requested by: first name (`requester_first_name`, text): Their first name.
- Requested by: last name (`requester_last_name`, text): Their last name.
- Send the candidate a copy (`mail_report`, true/false): Have Sterling send the candidate a copy of the finished report.
- Updates address (`callback_url`, text): An https address Sterling posts this check's updates to. To run a workflow on every update, paste the address of a Lodol workflow that starts with the Webhook trigger.

**Outputs**

- `candidate_id` (text): The candidate's id
- `finished` (true/false): Whether Sterling has stopped working on it
- `invite_link` (text): The candidate's form link, when the invite is a link
- `report_url` (text): The report in Sterling, for your team
- `result` (text): The outcome, such as Clear or Consider; Pending until done
- `screening` (object): The whole screening
- `screening_id` (text): The screening's id
- `status` (text): Where it is, such as Pending, Complete or Review

**Example output**

```json
{
  "candidate_id": "3e4f84e3-9078-4451-a8b8-5897f4f4f4e3",
  "finished": false,
  "invite_link": "https://candidate.sterlingcheck.app/begin",
  "report_url": "https://sterlingcheck.app/interactive-summary/#/order/2FeG8v4M",
  "result": "Pending",
  "screening": {
    "accountId": "44771",
    "accountName": "Employer Test Account",
    "candidateId": "3e4f84e3-9078-4451-a8b8-5897f4f4f4e3",
    "estimatedCompletionTime": "2021-12-06T19:19:00Z",
    "id": "1801020638",
    "invite": {
      "link": "https://candidate.sterlingcheck.app/begin",
      "method": "link"
    },
    "jobPosition": "Driver",
    "links": {
      "admin": {
        "web": "https://sterlingcheck.app/interactive-summary/#/order/2FeG8v4M"
      }
    },
    "packageId": "92979",
    "packageName": "Pre-Employment Package",
    "reportItems": [
      {
        "estimatedCompletionTime": "2021-12-02T19:19:00Z",
        "id": "14499694",
        "result": "",
        "status": "pending",
        "type": "SSN Trace",
        "updatedAt": "2021-12-02T19:19:00Z"
      }
    ],
    "result": "Pending",
    "status": "Pending",
    "submittedAt": "2021-12-01T18:19:08Z",
    "updatedAt": "2021-12-06T19:19:00Z"
  },
  "screening_id": "1801020638",
  "status": "Pending"
}
```

### Download screening document

Save a file attached to a background check in Lodol.

**Inputs**

- Screening ID (`screening_id`, text, required): The screening (background check), such as 1801020638, from 'Create screening' or a callback.
- Document ID (`document_id`, text, required): The document, from 'List screening documents'.

**Outputs**

- `content_type` (text): The file's type
- `document_id` (text): The document
- `document_ref` (text): The file saved in Lodol, to attach or upload
- `filename` (text): The file's name
- `screening_id` (text): The screening
- `size_bytes` (number): The file's size in bytes

**Example output**

```json
{
  "content_type": "application/pdf",
  "document_id": "crm_11448293",
  "document_ref": "doc_01hxsterlingreport",
  "filename": "sterling-report-1801020638.pdf",
  "screening_id": "1801020638",
  "size_bytes": 48213
}
```

### Find candidates

Find a candidate by their email address or by your reference for them.

**Inputs**

- Email (`email`, text): Their email address. Give this or your reference.
- Your reference (`client_reference_id`, text): The reference you gave them. Give this or their email.

**Outputs**

- `candidates` (list): The candidates found
- `count` (number): How many were found
- `found` (true/false): Whether any were found

**Example output**

```json
{
  "candidates": [
    {
      "address": {
        "addressLine": "123 Main Street",
        "countryCode": "US",
        "municipality": "Orlando",
        "postalCode": "12345",
        "regionCode": "US-FL"
      },
      "clientReferenceId": "999124441",
      "confirmedNoMiddleName": false,
      "dob": "XXXX-01-20",
      "driversLicense": {
        "issuingAgency": "US-CA",
        "licenseNumber": "S1234567",
        "type": "personal"
      },
      "email": "john.doe@example.com",
      "familyName": "Doe",
      "givenName": "John",
      "id": "3e4f84e3-9078-4451-a8b8-5897f4f4f4e3",
      "middleName": "Jay",
      "phone": "+14041231234",
      "primaryLanguage": "en-US",
      "screeningIds": [],
      "ssn": "XXXXX6789",
      "suffix": "Jr."
    }
  ],
  "count": 1,
  "found": true
}
```

### Get candidate

Get a candidate's details and the ids of their screenings. SSN and date of birth come back partly hidden.

**Inputs**

- Candidate ID (`candidate_id`, text, required): The candidate, from 'Create candidate' or 'Find candidates'.

**Outputs**

- `candidate` (object): The candidate

**Example output**

```json
{
  "candidate": {
    "address": {
      "addressLine": "123 Main Street",
      "countryCode": "US",
      "municipality": "Orlando",
      "postalCode": "12345",
      "regionCode": "US-FL"
    },
    "clientReferenceId": "999124441",
    "confirmedNoMiddleName": false,
    "dob": "XXXX-01-20",
    "driversLicense": {
      "issuingAgency": "US-CA",
      "licenseNumber": "S1234567",
      "type": "personal"
    },
    "email": "john.doe@example.com",
    "familyName": "Doe",
    "givenName": "John",
    "id": "3e4f84e3-9078-4451-a8b8-5897f4f4f4e3",
    "middleName": "Jay",
    "phone": "+14041231234",
    "primaryLanguage": "en-US",
    "screeningIds": [],
    "ssn": "XXXXX6789",
    "suffix": "Jr."
  }
}
```

### Get package

Get one screening package: its searches, how many of each, and the candidate details it needs.

**Inputs**

- Package (`package_id`, text, required): The screening package: the set of searches to run.

**Outputs**

- `package` (object): The package

**Example output**

```json
{
  "package": {
    "active": true,
    "id": "155934",
    "products": [
      {
        "code": "SSV1",
        "description": "SSN Trace"
      },
      {
        "code": "CRFM",
        "description": "County Criminal Record"
      }
    ],
    "requiredFields": [
      "address.addressLine",
      "address.municipality",
      "address.postalCode",
      "address.regionCode",
      "dob",
      "familyName",
      "givenName",
      "ssn"
    ],
    "title": "Basic Package",
    "type": "Standard"
  }
}
```

### Get screening

Get a background check: its status, result, each search's progress and a link to the report in Sterling.

**Inputs**

- Screening ID (`screening_id`, text, required): The screening (background check), such as 1801020638, from 'Create screening' or a callback.

**Outputs**

- `candidate_id` (text): The candidate's id
- `finished` (true/false): Whether Sterling has stopped working on it
- `invite_link` (text): The candidate's form link, when the invite is a link
- `report_url` (text): The report in Sterling, for your team
- `result` (text): The outcome, such as Clear or Consider; Pending until done
- `screening` (object): The whole screening
- `screening_id` (text): The screening's id
- `status` (text): Where it is, such as Pending, Complete or Review

**Example output**

```json
{
  "candidate_id": "3e4f84e3-9078-4451-a8b8-5897f4f4f4e3",
  "finished": false,
  "invite_link": "https://candidate.sterlingcheck.app/begin",
  "report_url": "https://sterlingcheck.app/interactive-summary/#/order/2FeG8v4M",
  "result": "Pending",
  "screening": {
    "accountId": "44771",
    "accountName": "Employer Test Account",
    "candidateId": "3e4f84e3-9078-4451-a8b8-5897f4f4f4e3",
    "estimatedCompletionTime": "2021-12-06T19:19:00Z",
    "id": "1801020638",
    "invite": {
      "link": "https://candidate.sterlingcheck.app/begin",
      "method": "link"
    },
    "jobPosition": "Driver",
    "links": {
      "admin": {
        "web": "https://sterlingcheck.app/interactive-summary/#/order/2FeG8v4M"
      }
    },
    "packageId": "92979",
    "packageName": "Pre-Employment Package",
    "reportItems": [
      {
        "estimatedCompletionTime": "2021-12-02T19:19:00Z",
        "id": "14499694",
        "result": "",
        "status": "pending",
        "type": "SSN Trace",
        "updatedAt": "2021-12-02T19:19:00Z"
      }
    ],
    "result": "Pending",
    "status": "Pending",
    "submittedAt": "2021-12-01T18:19:08Z",
    "updatedAt": "2021-12-06T19:19:00Z"
  },
  "screening_id": "1801020638",
  "status": "Pending"
}
```

### Get screening report

Save a background check's report in Lodol as a PDF or web page, to email or store.

**Inputs**

- Screening ID (`screening_id`, text, required): The screening (background check), such as 1801020638, from 'Create screening' or a callback.
- Format (`report_format`, text): PDF or web page. Defaults to PDF. One of: `pdf`, `html` (Web page (HTML)). Default: `pdf`.

**Outputs**

- `content_type` (text): The file's type
- `document_ref` (text): The file saved in Lodol, to attach or upload
- `filename` (text): The file's name
- `format` (text): pdf or html
- `screening_id` (text): The screening
- `size_bytes` (number): The file's size in bytes

**Example output**

```json
{
  "content_type": "application/pdf",
  "document_ref": "doc_01hxsterlingreport",
  "filename": "sterling-report-1801020638.pdf",
  "format": "pdf",
  "screening_id": "1801020638",
  "size_bytes": 48213
}
```

### List bill codes

List the bill codes you can put on an order.

**Inputs**

- Sub-account (`account_id`, text): Only this sub-account's bill codes. Leave empty for all of them.

**Outputs**

- `bill_codes` (list): The bill codes
- `count` (number): How many there are

**Example output**

```json
{
  "bill_codes": [
    "billCode1",
    "billCode2"
  ],
  "count": 2
}
```

### List candidate documents

List the files attached to a candidate.

**Inputs**

- Candidate ID (`candidate_id`, text, required): The candidate, from 'Create candidate' or 'Find candidates'.

**Outputs**

- `count` (number): How many there are
- `documents` (list): The documents

**Example output**

```json
{
  "count": 1,
  "documents": [
    {
      "createdAt": "2020-11-20T19:18:16Z",
      "documentType": "consent",
      "fileName": "Consent.pdf",
      "id": "crm_11448293",
      "reportItemId": "",
      "url": "https://api.us.sterlingcheck.app/v2/screenings/1801020638/documents/crm_11448293"
    }
  ]
}
```

### List candidate forms

List the Candidate Hub forms (workflows) an invite can use, such as Consent Plus.

**Inputs**: None.

**Outputs**

- `count` (number): How many there are
- `workflows` (list): The forms

**Example output**

```json
{
  "count": 1,
  "workflows": [
    {
      "id": "2",
      "name": "Consent Plus"
    }
  ]
}
```

### List packages

List your screening packages, with the searches each runs and the candidate details each needs.

**Inputs**: None.

**Outputs**

- `count` (number): How many there are
- `packages` (list): The packages

**Example output**

```json
{
  "count": 1,
  "packages": [
    {
      "active": true,
      "id": "155934",
      "products": [
        {
          "code": "SSV1",
          "description": "SSN Trace"
        },
        {
          "code": "CRFM",
          "description": "County Criminal Record"
        }
      ],
      "requiredFields": [
        "address.addressLine",
        "address.municipality",
        "address.postalCode",
        "address.regionCode",
        "dob",
        "familyName",
        "givenName",
        "ssn"
      ],
      "title": "Basic Package",
      "type": "Standard"
    }
  ]
}
```

### List screening documents

List the files attached to a background check.

**Inputs**

- Screening ID (`screening_id`, text, required): The screening (background check), such as 1801020638, from 'Create screening' or a callback.

**Outputs**

- `count` (number): How many there are
- `documents` (list): The documents

**Example output**

```json
{
  "count": 1,
  "documents": [
    {
      "createdAt": "2020-11-20T19:18:16Z",
      "documentType": "consent",
      "fileName": "Consent.pdf",
      "id": "crm_11448293",
      "reportItemId": "",
      "url": "https://api.us.sterlingcheck.app/v2/screenings/1801020638/documents/crm_11448293"
    }
  ]
}
```

### List screening notes

List the notes Sterling's team made on a background check and on each of its searches, such as when they contacted the candidate.

**Inputs**

- Screening ID (`screening_id`, text, required): The screening (background check), such as 1801020638, from 'Create screening' or a callback.

**Outputs**

- `count` (number): How many notes there are
- `notes` (list): Notes on the whole check
- `report_item_notes` (list): Notes on its searches

**Example output**

```json
{
  "count": 2,
  "notes": [
    {
      "note": "Order status changed to Complete",
      "updatedAt": "2025-09-17T10:40:20Z"
    }
  ],
  "report_item_notes": [
    {
      "note": "Order status changed to Complete",
      "reportItemId": "22065126",
      "updatedAt": "2025-09-17T10:40:20Z"
    }
  ]
}
```

### List sub-accounts

List your Sterling account and its sub-accounts, with their ids.

**Inputs**: None.

**Outputs**

- `accounts` (list): The accounts
- `count` (number): How many there are

**Example output**

```json
{
  "accounts": [
    {
      "accountId": "44771",
      "accountName": "Sterling"
    }
  ],
  "count": 1
}
```

### Pause, resume or cancel adverse action

Pause, resume or cancel an adverse action process before the final notice goes out. Cancelling scores the report and needs a reason.

**Inputs**

- Screening ID (`screening_id`, text, required): The screening (background check), such as 1801020638, from 'Create screening' or a callback.
- Change (`change`, text, required): What to do with the adverse action process. One of: `pause`, `resume`, `cancel`.
- Score for the report (`score`, text): The result the report gets once cancelled. Clear or Consider, unless your account uses Sterling's scoring. Only when Change is Cancel. One of: `clear`, `consider`, `passed` (Passed (scored accounts)), `review` (Review (scored accounts)), `level1` (Level 1 (scored accounts)), `level2` (Level 2 (scored accounts)), `level3` (Level 3 (scored accounts)).
- Reason for cancelling (`comments`, text): Why the adverse action is cancelled. Only when Change is Cancel.

**Outputs**

- `change` (text): pause, resume or cancel
- `done` (true/false): True once Sterling accepted it
- `screening_id` (text): The screening

**Example output**

```json
{
  "change": "pause",
  "done": true,
  "screening_id": "1801020638"
}
```

### Resend screening update

Have Sterling post a background check's latest update to its updates address again. Only for a check ordered with an updates address.

**Inputs**

- Screening ID (`screening_id`, text, required): The screening (background check), such as 1801020638, from 'Create screening' or a callback.

**Outputs**

- `callback_url` (text): The address it was sent to
- `screening_id` (text): The screening
- `sent` (true/false): True once Sterling has sent it

**Example output**

```json
{
  "callback_url": "https://example.com/sterling-updates",
  "screening_id": "1801020638",
  "sent": true
}
```

### Start adverse action

Start the adverse action process on a finished check with a Consider, Review or Level 3 result: Sterling sends the candidate a pre-adverse action notice with their report.

**Inputs**

- Screening ID (`screening_id`, text, required): The screening (background check), such as 1801020638, from 'Create screening' or a callback.
- Signed by (`signature`, text, required): The name of the person deciding, shown on the notice.
- Reasons (`disqualification_reasons`, object, required): For each search behind the decision, its report item id (from 'Get screening') and why it disqualifies the candidate.
- Comments for your team (`order_comments`, text): Shown on the report in Sterling.
- Comments for the candidate (`candidate_comments`, text): Added to the notice the candidate gets.

**Outputs**

- `report_item` (object): The adverse action, as a search on the check
- `screening_id` (text): The screening

**Example output**

```json
{
  "report_item": {
    "estimatedCompletionTime": "2021-05-10T23:28:17Z",
    "id": "13812243",
    "result": "",
    "status": "pending",
    "type": "Managed Adverse Action",
    "updatedAt": "2021-05-05T23:28:17Z"
  },
  "screening_id": "1801020638"
}
```

### Update candidate

Change a candidate's details. Fields left empty keep what Sterling has; screenings already ordered keep the details they were ordered with.

**Inputs**

- Candidate ID (`candidate_id`, text, required): The candidate, from 'Create candidate' or 'Find candidates'.
- First name (`given_name`, text): Their legal first name. Leave empty to keep what Sterling has.
- Last name (`family_name`, text): Their legal last name. Leave empty to keep what Sterling has.
- Email (`email`, text): Their email address; Sterling sends invites here. It must not be used by another candidate. Leave empty to keep what Sterling has.
- Middle name (`middle_name`, text): Their middle name. Sterling needs it, or 'Has no middle name' switched on. Leave empty to keep what Sterling has.
- Has no middle name (`no_middle_name`, true/false): Switch on when the candidate has no legal middle name.
- Suffix (`suffix`, text): Such as Jr. or III. Leave empty to keep what Sterling has.
- Phone (`phone`, text): With the country code, such as +15555551234. Leave empty to keep what Sterling has.
- Date of birth (`dob`, date): Their date of birth. Many packages need it. Sterling never shows it back in full, so on an update give it again to keep it.
- Social Security number (`ssn`, text): 9 digits, as 123-45-6789. US criminal searches need it. Sterling never shows it back in full, so give it again to keep it.
- Street address (`address_line`, text): Where they live now, such as 123 Main Street. Leave empty to keep what Sterling has.
- City (`city`, text): The address's city or town. Leave empty to keep what Sterling has.
- State or region (`state`, text): Such as WA or US-WA (for the US and Canada, the two-letter code). Leave empty to keep what Sterling has.
- Postal code (`postal_code`, text): Zip or postal code, with no dashes. Leave empty to keep what Sterling has.
- Country (`country`, text): The address's two-letter country code. Defaults to US.
- Driver's license number (`license_number`, text): Needed for driving record searches. Leave empty to keep what Sterling has.
- Driver's license state (`license_state`, text): Where the license was issued, such as CA or US-CA. Leave empty to keep what Sterling has.
- Language (`language`, text): The language for Sterling's invite and forms, such as en-US or es-US.

**Outputs**

- `candidate` (object): The candidate

**Example output**

```json
{
  "candidate": {
    "address": {
      "addressLine": "123 Main Street",
      "countryCode": "US",
      "municipality": "Orlando",
      "postalCode": "12345",
      "regionCode": "US-FL"
    },
    "clientReferenceId": "999124441",
    "confirmedNoMiddleName": false,
    "dob": "XXXX-01-20",
    "driversLicense": {
      "issuingAgency": "US-CA",
      "licenseNumber": "S1234567",
      "type": "personal"
    },
    "email": "john.doe@example.com",
    "familyName": "Doe",
    "givenName": "John",
    "id": "3e4f84e3-9078-4451-a8b8-5897f4f4f4e3",
    "middleName": "Jay",
    "phone": "+14041231234",
    "primaryLanguage": "en-US",
    "screeningIds": [],
    "ssn": "XXXXX6789",
    "suffix": "Jr."
  }
}
```

### Wait for screening

Pause the workflow until Sterling has finished a background check (or needs someone to act on it), then give its status and result. Checks every 30 minutes.

**Inputs**

- Screening ID (`screening_id`, text, required): The screening (background check), such as 1801020638, from 'Create screening' or a callback.
- Give up after (days) (`max_wait_days`, number): Fail the step if the check isn't done this many days after it was submitted. Defaults to 14. From 1 to 60.

**Outputs**

- `candidate_id` (text): The candidate's id
- `finished` (true/false): Whether Sterling has stopped working on it
- `invite_link` (text): The candidate's form link, when the invite is a link
- `report_url` (text): The report in Sterling, for your team
- `result` (text): The outcome, such as Clear or Consider; Pending until done
- `screening` (object): The whole screening
- `screening_id` (text): The screening's id
- `status` (text): Where it is, such as Pending, Complete or Review

**Example output**

```json
{
  "candidate_id": "3e4f84e3-9078-4451-a8b8-5897f4f4f4e3",
  "finished": true,
  "invite_link": "https://candidate.sterlingcheck.app/begin",
  "report_url": "https://sterlingcheck.app/interactive-summary/#/order/2FeG8v4M",
  "result": "Clear",
  "screening": {
    "accountId": "44771",
    "accountName": "Employer Test Account",
    "candidateId": "3e4f84e3-9078-4451-a8b8-5897f4f4f4e3",
    "estimatedCompletionTime": "2021-12-06T19:19:00Z",
    "id": "1801020638",
    "invite": {
      "link": "https://candidate.sterlingcheck.app/begin",
      "method": "link"
    },
    "jobPosition": "Driver",
    "links": {
      "admin": {
        "web": "https://sterlingcheck.app/interactive-summary/#/order/2FeG8v4M"
      }
    },
    "packageId": "92979",
    "packageName": "Pre-Employment Package",
    "reportItems": [
      {
        "estimatedCompletionTime": "2021-12-02T19:19:00Z",
        "id": "14499694",
        "result": "",
        "status": "pending",
        "type": "SSN Trace",
        "updatedAt": "2021-12-02T19:19:00Z"
      }
    ],
    "result": "Pending",
    "status": "Pending",
    "submittedAt": "2021-12-01T18:19:08Z",
    "updatedAt": "2021-12-06T19:19:00Z"
  },
  "screening_id": "1801020638",
  "status": "Complete"
}
```
