Developers

API Documentation

Send orders from WooCommerce, BigCommerce, or any platform to sonarID for automatic VIP detection and enrichment. One endpoint, one API key.

Quick start

Get up and running in minutes

01Create a sonarID account at sonarid.com/signup
02Go to Settings → Integrations and generate an API key
03Send a POST request to /api/v1/orders with customer data
04VIP detection runs automatically — check your dashboard or Slack for alerts

WooCommerce setup guide →

Example request

curl -X POST \
  https://sonarid.com/api/v1/orders \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "+15551234567",
    "address": {
      "city": "Atherton",
      "state": "CA",
      "zipcode": "94027",
      "country": "US"
    },
    "order": {
      "id": "wc_1042",
      "number": "1042",
      "total": "150.00",
      "currency": "USD"
    }
  }'

Authentication

API key authentication

All API requests require an API key. Generate one from your sonarID dashboard under Settings → Integrations → API Access.

Include your key in the request using either method:

Option 1: Authorization header (recommended)

Authorization: Bearer sk_live_your_key

Option 2: x-api-key header

x-api-key: sk_live_your_key

API keys begin with sk_live_. Keep your key secret — it grants full access to submit orders to your account. You can revoke and regenerate your key at any time.

Endpoints

POST/api/v1/ordersSubmit an order for VIP enrichment

Request body

Field	Type	Required	Description
email	string	Yes	Customer email address
firstName	string	Yes	Customer first name
lastName	string	Yes	Customer last name
phone	string	No	Customer phone number (E.164 format preferred)
address	object	No	Customer address (see below)
address.city	string	No	City
address.state	string	No	State or province code
address.zipcode	string	No	Postal / zip code (used for affluent area detection)
address.country	string	No	Country code (e.g. US, CA, GB)
order	object	No	Order details (see below)
order.id	string	No	Your platform order ID (used for deduplication)
order.number	string	No	Display order number
order.total	string	No	Order total as decimal string (e.g. "150.00")
order.currency	string	No	ISO 4217 currency code (default: USD)

Success response

200 OK

{
  "success": true,
  "customerId": "a1b2c3d4-...",
  "orderId": "e5f6g7h8-...",
  "enrichmentStatus": "queued"
}

Field	Description
success	Always `true` on success
customerId	UUID of the customer record in sonarID
orderId	UUID of the order record (only if order data was provided)
enrichmentStatus	`queued` (new customer, enrichment started), `retry` (previously failed, retrying), or `existing` (already enriched)

Error responses

401 Unauthorized

{ "error": "Unauthorized", "message": "Invalid or missing API key" }

API key is missing, invalid, or revoked.

400 Bad Request

{ "error": "Bad Request", "message": "Missing required fields: email, firstName, lastName" }

Required fields are missing or email is invalid/disposable.

500 Internal Server Error

{ "error": "Internal Server Error", "message": "Failed to process order" }

Unexpected server error. The order was not processed — safe to retry.

Behavior

How the API processes orders

Customer deduplication

Customers are matched by email per store. If the same email submits multiple orders, the existing customer record is reused. No duplicate profiles are created.

Order deduplication

If you include an order.id, sonarID deduplicates on that ID. Sending the same order twice returns the existing record instead of creating a duplicate.

Enrichment pipeline

New customers are automatically queued for enrichment. sonarID checks social profiles, public records, and identity databases. Results typically arrive within 2–5 seconds.

Failed enrichment retry

If a customer previously failed enrichment (e.g. due to a temporary provider outage), submitting a new order for them automatically retries enrichment.

VIP alerts

If enrichment detects a VIP (score above your configured threshold), Slack and email alerts fire automatically — same as Shopify orders.

Billing

Each new customer enrichment costs $0.03. Repeat orders for the same customer do not incur additional enrichment charges. Usage appears in your dashboard under Settings → Billing.

Platform guides

Guide