# Check report status

## Report status values

| Status | Description |
|  --- | --- |
| `pending` | The report is in progress. Screenings are still running. |
| `suspended` | The report is on hold — the candidate needs to provide additional information. |
| `paused` | The report is awaiting a Review Action decision to continue or skip the remaining screenings. |
| `complete` | Report processing has finished — at least one screening completed. The overall result is `clear` or `consider`. |
| `canceled` | All screenings in the report were canceled. |
| `dispute` | The candidate has disputed one or more results. |


## Option 1: Poll the Reports endpoint

Retrieve the current status of a report at any time by calling the Reports endpoint.

cURL
```bash
curl -u YOUR_API_KEY: \
  https://api.checkr-staging.com/v1/reports/REPORT_ID
```

Python
```python
import requests

response = requests.get(
    'https://api.checkr-staging.com/v1/reports/REPORT_ID',
    auth=('YOUR_API_KEY', '')
)
report = response.json()
print(report['status'])  # pending, complete, suspended, etc.
print(report['result'])  # clear or consider
```

JavaScript
```javascript
const response = await fetch('https://api.checkr-staging.com/v1/reports/REPORT_ID', {
  headers: {
    'Authorization': 'Basic ' + btoa('YOUR_API_KEY:'),
  },
});
const report = await response.json();
console.log(report.status); // pending, complete, suspended, etc.
console.log(report.result); // clear or consider
```

Go
```go
package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://api.checkr-staging.com/v1/reports/REPORT_ID", nil)
  req.SetBasicAuth("YOUR_API_KEY", "")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  body, _ := io.ReadAll(resp.Body)
  fmt.Println(string(body)) // Contains status and result fields
}
```

Java
```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Main {
  public static void main(String[] args) throws Exception {
    String credentials = Base64.getEncoder().encodeToString("YOUR_API_KEY:".getBytes());

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.checkr-staging.com/v1/reports/REPORT_ID"))
      .header("Authorization", "Basic " + credentials)
      .GET()
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
      .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body()); // Contains status and result fields
  }
}
```

Ruby
```ruby
require 'net/http'
require 'json'

uri = URI('https://api.checkr-staging.com/v1/reports/REPORT_ID')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request.basic_auth('YOUR_API_KEY', '')

response = http.request(request)
report = JSON.parse(response.body)
puts report['status'] # pending, complete, suspended, etc.
puts report['result'] # clear or consider
```

The response includes the `status` field along with individual screening statuses.

Polling is straightforward but not recommended for production applications. Use webhooks instead.

## Option 2: Use webhooks (recommended)

Configure a webhook endpoint to receive real-time status updates. Checkr sends a POST request to your endpoint whenever a report or screening status changes.

**Key webhook events:**

| Event | Description |
|  --- | --- |
| `report.updated` | The report changed while processing — sent as individual screenings within the report complete. |
| `report.suspended` | The report has been suspended. |
| `report.completed` | The report has finished processing. |


To set up webhooks, go to **Dashboard → Developer → Webhooks** and add your endpoint URL.

## Option 3: Query with Customer MCP

Use [Checkr's Customer MCP](/mcp/customer/introduction) to query report status using Claude or another AI assistant.

Example queries:

- "What's the status of the report for John Smith?"
- "Which reports are still pending?"
- "Show me all reports with a 'consider' status this week."


Customer MCP is particularly useful for ad hoc lookups during development or support investigations.

## Further reading

Checkr API docs
Full Reports API reference.

Customer MCP
AI-powered querying for Checkr data.