API reference

Sign in or create an account, complete your merchant profile and manage your key in the API keys area. This reference is public; account credentials remain behind sign-in.

Send API requests from your server with Authorization: Bearer YOUR_API_KEY and Content-Type: application/json. Never embed a real key in browser code, mobile bundles, URLs or support messages.

Production base URL: https://api.vruza.ai/api/v1
Staging base URL:    https://staging-api.vruza.ai/api/v1
Authorization: Bearer YOUR_API_KEY

Use the key belonging to the target environment. Examples below use placeholder credentials and the production base URL; replace both as appropriate.

curl https://api.vruza.ai/api/v1/risk-check \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "phone": "+14155552671",
    "order_value": 4500,
    "payment_method": "COD"
  }'

• phone: required, with + and country code. Pakistani +92 numbers must contain exactly ten digits after the country code.
• order_value: required positive number.
• payment_method: required, either COD or prepaid, with this exact casing.
• delivery_address: optional. Omit customer data your integration does not need.

Use snake_case field names. A successful response includes success, a data object and request metadata. The following is an illustrative excerpt, not a full response:

{
  "success": true,
  "data": {
    "customer_id": "CUSTOMER_ID",
    "risk_score": 500,
    "risk_level": "medium",
    "recommendation": "approve_with_verification",
    "confidence": 0.5,
    "flags": ["new_customer"]
  }
}

The full data object also contains factors, history and recommendations. Higher scores mean more trust. Confidence is not a delivery probability. A risk check does not place a Shopify fulfillment hold. Read the score guide.

POST /api/v1/orders/update reports or corrects an outcome using the customer_id returned by your risk check and a stable order_id from your platform. Use the same merchant key. A prior generic order at your merchant also authorizes the reference; Shopify-only evidence does not.

{
  "customer_id": "af33c595-0c30-45fb-a25a-5c2796f96c66",
  "order_id": "STORE-ORDER-12345",
  "order_value": 4500,
  "payment_method": "COD",
  "status": "delivered"
}

Status accepts delivered, rejected, cancelled or returned. Repeated identical outcomes are idempotent. Corrections update the existing contribution without counting another order. Use create_only to preserve an existing outcome when delayed automation arrives. Customer and payment method cannot be reassigned. Only report delivered when delivery and payment are confirmed.

Hash-based reports are no longer supported. Supplying phone_hash, a malformed or missing customer_id, or an unknown field returns 400. Unknown and unauthorized customer IDs return the same 404 response. Do not compute or distribute lookup hashes.

POST /api/v1/customers/orders/update remains available for phone-based reports with phone, order_value, payment_method and status (pending, delivered, rejected or returned). It creates a new record on every successful call, so do not blindly retry it. Use the UUID endpoint above for idempotent reporting. Shopify merchants should use the in-app outcome controls described in the Shopify guide.

GET /api/v1/customers/:id accepts the customer_id returned from a risk check. Authenticate with your merchant key. The response includes the current score, statistics and recent orders for the requesting merchant.

Shared statistics and current reputation can differ from the saved score on an earlier order. Display only the information needed for your merchant's review.

The deployed API rate limit is 100 requests per 60 seconds per API key. A request limit is different from the free plan's lack of a monthly check quota.

• 400: invalid request fields. Check the names, types and phone format.
• 401: missing or invalid Bearer key. Check the target environment.
• 403: inactive merchant account.
• 404: customer record not found.
• 409: an order outcome conflicts with an existing record.
• 429: request rate exceeded. Back off before retrying.
• 500: server failure. Keep any request ID for support; avoid retrying a non-idempotent outcome submission without checking its result.
• 501: unavailable feature. Batch risk checks and phone/ID verification are not currently available.

Error response shapes vary by endpoint, so check the HTTP status before reading data. Never treat an API failure as evidence that a customer is high risk.