Onboard a new customer

Header Parameters

SW-PARTNER-ID*string

Partner organization identifier

SW-API-KEY*string

API authentication key

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

companyName*string

Name of the customer company

Length1 <= length

contactEmail?|

Primary contact email address (optional). When provided, it is automatically added to assetsEmails if not already present. Customer emails require a contact email.

Formatemail

customerReference*string

Unique customer reference identifier (used for partner's internal tracking)

Length1 <= length

assetsDomains?array<>

Array of domains to monitor for security issues. Optional, but at least one of assetsDomains or assetsEmails must be provided.

assetsEmails?array<>

Array of email addresses to monitor for breaches. Optional, but at least one of assetsDomains or assetsEmails must be provided. The contactEmail is automatically added if not present.

alertRecipients*array<>

Array of email addresses that will receive security alerts. At least one is required.

Items1 <= items

price*number

Subscription price (must be greater than or equal to 0)

Formatdouble

Range0 <= value

billedFromDate*string

Billing start date in ISO 8601 format. Must be a future date.

Formatdate-time

currencyCode*string

Currency code for billing

Value in"AUD" | "GBP" | "USD" | "SEK" | "AED" | "EUR"

planId?string

Plan UUID from GET /api/v1/integrations/partner/plans. Preferred over planType.

Formatuuid

planType?string

Deprecated: use planId. Service plan tier. Defaults to safeweb-basic if planId is not provided.

Default"safeweb-basic"

Value in"safeweb-basic" | "safeweb-plus" | "safeweb-pro"

enrolType?string

Enrollment type for the customer. Defaults to opt-out if not provided.

Default"opt-out"

Value in"opt-in" | "opt-out"

sendMonthlyReport?boolean

Whether to send monthly security reports to the customer. Defaults to false.

Defaultfalse

localeCode?string

Locale code for customer communications. Defaults to en-GB.

Default"en-GB"

shouldReceiveBreachAlerts?boolean

Whether to send customer emails (welcome, breach reports, monthly reports, deactivation, etc.). Defaults to true. When false, all customer emails are suppressed; monitoring and breach scanning continue.

Defaulttrue

platformAccess?boolean

When true, creates a platform user account from contactEmail so the customer can sign in to the portal (e.g. via magic link). Requires contactEmail. Defaults to false.

Defaultfalse

status?string

Customer lifecycle status. Defaults to active for full ongoing monitoring. Set to prospect for a one-time sales exposure scan with redacted breach results.

Default"active"

Value in"active" | "prospect"

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/integrations/customer/onboard" \  -H "SW-PARTNER-ID: string" \  -H "SW-API-KEY: string" \  -H "Content-Type: application/json" \  -d '{    "companyName": "Acme Corporation",    "contactEmail": "contact@acme.co",    "customerReference": "ACME-001",    "assetsDomains": [      "acme.co",      "www.acme.co"    ],    "alertRecipients": [      "alerts@acme.co"    ],    "price": 49.99,    "billedFromDate": "2026-06-01T00:00:00.000Z",    "currencyCode": "USD",    "planType": "safeweb-basic",    "enrolType": "opt-in",    "sendMonthlyReport": true,    "localeCode": "en-GB",    "shouldReceiveBreachAlerts": true,    "status": "active"  }'

{
  "success": true,
  "message": "Customer onboarded successfully",
  "customerId": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "success": false,
  "error": "Invalid JSON in request body"
}

{
  "success": false,
  "error": "Partner ID and API key are required in headers"
}

{
  "success": false,
  "error": "Failed to onboard customer"
}

Optional: `status` field

By default, new customers are active and receive full ongoing monitoring. Set the optional status field to "prospect" for a one-time exposure scan with redacted breach results. Upgrade to active when the customer converts.

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"
  }'

Omit status (or set "status": "active") for a fully monitored customer:

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-001",
    "assetsDomains": ["acme.co"],
    "alertRecipients": ["alerts@acme.co"],
    "price": 49.99,
    "billedFromDate": "2026-07-01T00:00:00.000Z",
    "currencyCode": "GBP"
  }'

Onboard a new customer

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

500application/json

Invalid JSON body

Validation failure

No assets provided

Missing authentication headers

Invalid API key

Optional: status field

`application/json`

`application/json`

`application/json`

`application/json`

Optional: `status` field