View Categories

REST API Reference

6 min read

TrustLens exposes a REST API for integrations. This page documents every endpoint with its request and response shape. The API is implemented in includes/class-rest-api.php and registered under the trustlens/v1 namespace.

Base URL: https://yoursite.com/wp-json/trustlens/v1

Authentication #

Every endpoint requires authentication. The plugin accepts two mechanisms:

Method 1 — WordPress User Authentication #

Any authenticated WordPress user with the manage_woocommerce capability can call the API. The most common implementation is the WordPress application-password feature:

  1. WordPress → Users → Edit your user
  2. Scroll to Application Passwords
  3. Add a new password (e.g. “TrustLens integration”)
  4. Use the username and generated password in HTTP Basic Auth
curl -u username:app_password \
  https://yoursite.com/wp-json/trustlens/v1/customers

Cookie-based authentication for browser requests also works as long as the logged-in user has manage_woocommerce.

Method 2 — TrustLens API Key #

For integrations that don’t have a WordPress user, TrustLens supports a static API key. The key is stored as a SHA-256 hash in the trustlens_api_key WordPress option and compared with hash_equals() for timing-safe matching.

Send the key in the X-TrustLens-API-Key request header:

curl -H "X-TrustLens-API-Key: your_api_key_here" \
  https://yoursite.com/wp-json/trustlens/v1/customers

Configure the key in TrustLens → Settings → API.

The Eight Endpoints #

Method Path Purpose
GET /customers List customers
GET /customers/lookup Look up a customer by raw email
GET /customers/{email_hash} Get customer record by hash
POST/PUT/PATCH /customers/{email_hash} Update customer state (block, allowlist, notes)
GET /customers/{email_hash}/events List events on a customer’s timeline
POST /customers/{email_hash}/recalculate Trigger immediate score recalculation
GET /stats Store-wide aggregate statistics
GET /stats/segments Segment distribution counts

The {email_hash} parameter is the keyed HMAC-SHA256 hash of the customer’s email (64 hex characters). Use /customers/lookup?email=... if you only have the raw email.

GET /customers #

Paginated list of customers with optional filters.

Query Parameters #

Param Description
page, per_page Standard pagination
segment Filter to one of: vip, trusted, normal, caution, risk, critical
min_score, max_score Trust score range filter
is_blocked, is_allowlisted Boolean filters
orderby, order Sort field and direction

Response includes X-WP-Total and X-WP-TotalPages headers in the standard WordPress REST convention.

GET /customers/lookup #

Look up a customer by raw email address. TrustLens hashes the email server-side and returns the matching customer record.

Query Parameters #

  • email (required) — raw email address

Returns the same payload as GET /customers/{email_hash}.

GET /customers/{email_hash} #

Get the full customer record.

Response (typical) #

{
  "email_hash": "...",
  "customer_email": "...",
  "trust_score": 75,
  "segment": "trusted",
  "is_blocked": false,
  "is_allowlisted": false,
  "total_orders": 12,
  "total_order_value": 1450.00,
  "total_refunds": 1,
  "full_refunds": 0,
  "partial_refunds": 1,
  "total_refund_value": 89.00,
  "return_rate": 8.33,
  "total_disputes": 0,
  "disputes_won": 0,
  "disputes_lost": 0,
  "total_coupons_used": 2,
  "first_order_coupons": 1,
  "coupon_then_refund": 0,
  "linked_accounts": 0,
  "first_order_date": "2023-04-15 10:30:00",
  "last_order_date": "2024-03-10 14:22:00",
  "score_updated_at": "2024-03-10 14:25:00",
  "admin_notes": "..."
}

Returns 404 if the hash doesn’t match any customer.

POST/PUT/PATCH /customers/{email_hash} #

Update mutable state on a customer record. The same endpoint is used for blocking, allowlisting, and editing admin notes — there are no separate /block or /allowlist endpoints.

Updatable Fields #

  • is_blocked (boolean)
  • is_allowlisted (boolean)
  • admin_notes (string)
  • tags (array of strings)

Example: Block a Customer #

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "X-TrustLens-API-Key: ..." \
  -d '{"is_blocked": true}' \
  https://yoursite.com/wp-json/trustlens/v1/customers/{email_hash}

Example: Allowlist a Customer #

{"is_allowlisted": true}

Sending "is_allowlisted": true triggers an automatic score recalculation that locks the score at 100. Removing the allowlist (false) triggers a recalculation that restores the score based on actual signals.

The response is the updated customer record.

GET /customers/{email_hash}/events #

Returns the customer’s event timeline — order placements, refunds, coupon applications, disputes, score updates, admin actions, etc.

Query Parameters #

  • page, per_page — pagination
  • event_type — filter to a specific event type (e.g. order_placed)
  • since — ISO 8601 timestamp; return events at or after this time

Response Shape #

{
  "events": [
    {
      "id": 12345,
      "email_hash": "...",
      "event_type": "refund_issued",
      "event_data": { ... },
      "order_id": 5432,
      "created_at": "2024-03-10 14:22:00"
    },
    ...
  ]
}

event_data is a JSON-decoded object whose shape depends on the event type.

POST /customers/{email_hash}/recalculate #

Triggers an immediate, synchronous score recalculation. The recalculated score, segment, and current signal list are returned.

Response #

{
  "score": 52,
  "segment": "normal",
  "signals": [
    { "module": "returns", "score": -10, "reason": "Elevated return rate: 28%" },
    { "module": "account_age", "score": 10, "reason": "Established customer (6+ months)" }
  ]
}

This is the only endpoint that runs scoring inline rather than queueing it via Action Scheduler.

GET /stats #

Aggregate store-wide statistics.

Response (typical) #

{
  "total_scored_customers": 4823,
  "average_trust_score": 64,
  "store_return_rate": 8.4,
  "total_disputes_current_month": 12,
  "blocked_count": 47,
  "allowlisted_count": 89
}

Useful for external dashboards and integrations that want a quick health snapshot.

GET /stats/segments #

Customer count per segment.

Response #

{
  "vip": 127,
  "trusted": 892,
  "normal": 3456,
  "caution": 234,
  "risk": 89,
  "critical": 25
}

Error Format #

Errors follow the WordPress REST convention:

{
  "code": "trustlens_customer_not_found",
  "message": "Customer not found",
  "data": { "status": 404 }
}

Common error codes:

  • 401 — missing or invalid authentication
  • 403 — capability check failed
  • 404 — record not found
  • 400 — invalid request body or parameters

Pagination Headers #

List endpoints (/customers, /customers/{hash}/events) include WordPress’s standard headers:

  • X-WP-Total — total result count
  • X-WP-TotalPages — total page count given the current per_page

What This API Doesn’t Do #

To set expectations clearly:

  • No dispute endpoints. Disputes are not exposed as a standalone resource through the REST API. Dispute counts and outcomes are visible on the customer record’s stat columns. Use the WordPress admin or direct database queries for dispute-specific reads.
  • No health endpoint. No unauthenticated probe endpoint is registered.
  • No automation rule management. Automation rules are configured through the admin UI, not the REST API.
  • No webhook subscription management. Outgoing webhooks are configured per automation rule action through the admin UI.
  • No built-in rate limiting. The plugin does not enforce request-rate limits at the application layer. If you need rate limiting, apply it at the web server, CDN, or reverse-proxy layer.

Versioning #

The namespace trustlens/v1 is the current and only version. Future breaking changes would introduce v2 while keeping v1 available for backward compatibility. Non-breaking additions (new fields, new optional parameters) happen in v1 without a version bump.

Common Integration Patterns #

  • Read customer score from CRM: CRM calls GET /customers/lookup?email=... when displaying a customer record
  • Sync customer state to data warehouse: subscribe to TrustLens automation webhooks (configured per rule) and ingest events
  • Help desk integration: on ticket open, call GET /customers/lookup?email={ticket.requester} to surface trust context to the agent
  • External fraud-rule engine: consume webhook events from your rules, apply external logic, call PATCH /customers/{hash} with is_blocked: true when needed
Updated on June 4, 2026

What are your Feelings

  • Happy
  • Normal
  • Sad