Prospecting

Overview

Prospecting lets you run a lightweight dark-web exposure check during the sales process, before a customer commits to full monitoring.

A customer in prospect status is onboarded through the Partner API like any other customer, but with important differences:

• They receive a single exposure scan — not ongoing daily monitoring.
• Breach results are redacted: you can see which monitored emails were exposed, but not the full breach report.
• When the customer converts, call the upgrade endpoint to move them to active status and enable full monitoring.

Prospecting is available through the Partner API only.

Customer statuses

SafeWeb customers have a status field. Prospect is separate from the existing lifecycle states:

Typical prospect workflow

1. Onboard the customer with "status": "prospect".
2. SafeWeb scans the customer's monitored assets once.
3. Poll Get customer breaches or listen for webhook events to learn whether exposure was found and which emails were affected.
4. When the customer converts, call Upgrade customer to set status to active.
5. After upgrade, the customer is scanned on the normal schedule and receives full breach detail in API responses and webhooks.

Onboarding a prospect

Use the standard onboard endpoint. All existing fields (company name, assets, billing, plan, and so on) apply unchanged. Set the optional status field to "prospect":

curl -X POST https://connect.safestate.com/api/v1/integrations/customer/onboard \
  -H "Content-Type: application/json" \
  -H "SW-PARTNER-ID: your-partner-id" \
  -H "SW-API-KEY: your-api-key" \
  -d '{
    "companyName": "Acme Corporation",
    "contactEmail": "contact@acme.co",
    "customerReference": "ACME-PROSPECT-001",
    "assetsDomains": ["acme.co"],
    "alertRecipients": ["sales@yourpartner.com"],
    "price": 0,
    "billedFromDate": "2026-07-01T00:00:00.000Z",
    "currencyCode": "GBP",
    "status": "prospect"
  }'

Omitting status or setting "status": "active" creates a fully monitored customer.

Scanning behaviour

Prospect customers are designed for a single sales question: has this organisation been exposed on the dark web? They are not intended for long-term monitoring while still in prospect status.

Redacted breach data

For customers with status: "prospect", you receive a redacted breach list. Each entry identifies which monitored email was exposed, but the full breach report is withheld until the customer is upgraded to active.

What you receive

Each item in breaches includes:

What is redacted

The following fields are not returned for prospect customers, in API responses or webhook payloads:

• Breach titles
• Breach source names (breachName)
• Breach dates
• Data categories exposed in the breach
• Detailed breach descriptions
• Recommended remediation steps

See Get customer breaches for the full response for active customers and the reduced response for prospect customers.

Webhook deliveries for prospect customers follow the same redaction rules — see Outbound webhooks.

Example responses

GET /api/v1/integrations/customer/{customerId}/breaches (prospect):

{
  "success": true,
  "breachStatus": true,
  "count": 1,
  "breaches": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "emails": ["user@example.com"],
      "resolved": false
    }
  ]
}

Webhook customer.breach.found (prospect):

{
  "idempotencyToken": "8f2c1b0e-…",
  "type": "customer.breach.found",
  "data": {
    "partnerId": "22222222-2222-4222-8222-222222222222",
    "customer": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Ltd",
      "reference": "ACME-001"
    },
    "breachStatus": true,
    "count": 1,
    "breaches": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "emails": ["user@example.com"],
        "resolved": false
      }
    ]
  },
  "timestamp": 1715601234567
}

Active customers receive full breach detail in API responses and webhooks — see Get customer breaches and Outbound webhooks.

Other endpoints

Redaction applies to breach API responses and breach-related webhooks only. Other endpoints — such as Get customer assets, Get customer info, and Get threat score — return their standard responses. Because prospect customers do not receive ongoing scans, threat score and breach count typically remain unchanged until upgrade.

Upgrading to active

When a prospect converts, call the dedicated upgrade endpoint:

POST /api/v1/integrations/customer/upgrade

This transitions status from prospect to active. After a successful upgrade:

• The customer enters the normal daily scan schedule.
• Subsequent breach API responses include full breach detail.
• Webhook events for new breaches include complete breach information.

Use Reactivate customer only for customers in inactive status — not for prospects.

Related endpoints