engineer

Engineer Quickstart

Verify a workspace, activate it, score a transaction, ingest a signed event, and submit the outcome.

Reviewed 2026-06-21Product 1.1

Run this flow from a backend service or controlled staging environment. Never place refresh tokens or webhook secrets in browser or mobile application code.

Prerequisites

A company administrator who can verify the workspace and activate a plan.
Permission events:assess for assessments and feedback:submit for feedback.
The developer_tools feature and developer_tools:manage permission to rotate the ingestion secret.

1. Set the API base URL

bash

export VERTEXY_API_BASE_URL="https://api.getvertexy.com/api"

2. Register and verify the administrator

bash

curl -X POST "$VERTEXY_API_BASE_URL/auth/register-company-admin" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Northstar Outfitters",
    "companySlug": "northstar-outfitters",
    "email": "risk-admin@northstar.example",
    "password": "Sup3rSecurePass!",
    "acceptedPrivacyPolicy": true,
    "acceptedTerms": true
  }'

The 201 Created response confirms that email verification is required:

json

{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "userId": "11f8bc0b-3fd8-4a2d-b52d-42ec7bce6e9a",
  "verificationRequired": true,
  "verificationEmail": "risk-admin@northstar.example",
  "verificationEmailSent": true,
  "managementToken": "temporary_signup_management_token"
}

Open the link delivered by email before signing in. Treat managementToken as sensitive; it only supports resending verification or correcting the signup email.

bash

curl -X POST "$VERTEXY_API_BASE_URL/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "email": "risk-admin@northstar.example",
    "password": "Sup3rSecurePass!"
  }'

The 201 Created response contains access and refresh tokens plus effective permissions and subscription state:

json

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "subscriptionStatus": "none",
  "planCode": null,
  "planFeatures": [],
  "permissions": ["events:assess", "feedback:submit"],
  "departmentId": null,
  "departmentName": null,
  "accessRoleId": null,
  "accessRoleName": null
}

Store the refresh token only in a secure server-side session. Sign in to the dashboard and complete Onboarding → Choose a plan. Protected endpoints return 402 Payment Required until the subscription becomes active.

4. Create the event-ingestion secret

Open Dashboard → Developer Settings and rotate the webhook secret, or call:

bash

curl -X POST "$VERTEXY_API_BASE_URL/auth/webhook-secret/regenerate" \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN"

Store the returned webhookSigningSecret immediately in your server-side secret manager. Rotation invalidates the previous secret immediately.

5. Score a transaction

bash

curl -X POST "$VERTEXY_API_BASE_URL/risk-engine/assess" \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "ord_us_10492",
    "userId": "usr_8f7b2c9a4d",
    "email": "buyer@example.com",
    "ipAddress": "203.0.113.42",
    "deviceFingerprint": "dev_iphone_15_7ac9",
    "paymentMethodHash": "pmh_visa_44e9",
    "amountMinor": 12999,
    "currency": "USD"
  }'

201Risk assessment response

json

{
  "assessmentId": "c8acf6d5-8bf4-4b80-a7e5-1b33583c1c23",
  "riskScore": 34,
  "action": "allow",
  "recommendedAction": "allow",
  "policyMode": "hybrid",
  "riskLevel": "medium",
  "reasonCodes": [],
  "featureContributions": {},
  "engineVersion": "v2",
  "latencyMs": 41
}

Persist assessmentId, action, score, and reason codes with your order record.

6. Send a signed lifecycle event

javascript

import crypto from "node:crypto";

const payload = {
  companyId: process.env.VERTEXY_COMPANY_ID,
  eventSource: "checkout-service",
  externalEventId: "evt_us_payment_10492",
  idempotencyKey: "evt_us_payment_10492",
  userId: "usr_8f7b2c9a4d",
  eventType: "payment_succeeded",
  timestamp: new Date().toISOString(),
  metadata: { orderId: "ord_us_10492", channel: "web" }
};
const body = JSON.stringify(payload);
const signature = crypto.createHmac("sha256", process.env.VERTEXY_WEBHOOK_SECRET).update(body).digest("hex");
const response = await fetch(`${process.env.VERTEXY_API_BASE_URL}/events/ingest`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-event-signature": signature,
    "x-event-timestamp": String(Math.floor(Date.now() / 1000)),
    "x-event-nonce": crypto.randomUUID()
  },
  body
});
if (!response.ok) throw new Error(`VertexY ingest failed: ${response.status}`);

7. Submit the final outcome

bash

curl -X POST "$VERTEXY_API_BASE_URL/risk-engine/feedback" \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assessmentId": "c8acf6d5-8bf4-4b80-a7e5-1b33583c1c23",
    "idempotencyKey": "feedback_ord_us_10492",
    "outcome": "approved",
    "occurredAt": "2026-06-21T10:35:00.000Z"
  }'

Verify success

Assessment returns 201 and an assessmentId.
Event ingestion returns 201, status: accepted, and an assessment.
Feedback returns 201 and { "accepted": true }.
The evaluation appears in Dashboard → Event Explorer.

Next, complete the go-live checklist and review retries and idempotency.

Was this page helpful?

engineer

Engineer Quickstart

Verify a workspace, activate it, score a transaction, ingest a signed event, and submit the outcome.

Reviewed 2026-06-21Product 1.1

Run this flow from a backend service or controlled staging environment. Never place refresh tokens or webhook secrets in browser or mobile application code.

Prerequisites

A company administrator who can verify the workspace and activate a plan.
Permission events:assess for assessments and feedback:submit for feedback.
The developer_tools feature and developer_tools:manage permission to rotate the ingestion secret.

1. Set the API base URL

bash

export VERTEXY_API_BASE_URL="https://api.getvertexy.com/api"

2. Register and verify the administrator

bash

curl -X POST "$VERTEXY_API_BASE_URL/auth/register-company-admin" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Northstar Outfitters",
    "companySlug": "northstar-outfitters",
    "email": "risk-admin@northstar.example",
    "password": "Sup3rSecurePass!",
    "acceptedPrivacyPolicy": true,
    "acceptedTerms": true
  }'

The 201 Created response confirms that email verification is required:

json

{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "userId": "11f8bc0b-3fd8-4a2d-b52d-42ec7bce6e9a",
  "verificationRequired": true,
  "verificationEmail": "risk-admin@northstar.example",
  "verificationEmailSent": true,
  "managementToken": "temporary_signup_management_token"
}

Open the link delivered by email before signing in. Treat managementToken as sensitive; it only supports resending verification or correcting the signup email.

bash

curl -X POST "$VERTEXY_API_BASE_URL/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "email": "risk-admin@northstar.example",
    "password": "Sup3rSecurePass!"
  }'

The 201 Created response contains access and refresh tokens plus effective permissions and subscription state:

json

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "subscriptionStatus": "none",
  "planCode": null,
  "planFeatures": [],
  "permissions": ["events:assess", "feedback:submit"],
  "departmentId": null,
  "departmentName": null,
  "accessRoleId": null,
  "accessRoleName": null
}

4. Create the event-ingestion secret

Open Dashboard → Developer Settings and rotate the webhook secret, or call:

bash

curl -X POST "$VERTEXY_API_BASE_URL/auth/webhook-secret/regenerate" \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN"

Store the returned webhookSigningSecret immediately in your server-side secret manager. Rotation invalidates the previous secret immediately.

5. Score a transaction

bash

curl -X POST "$VERTEXY_API_BASE_URL/risk-engine/assess" \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "ord_us_10492",
    "userId": "usr_8f7b2c9a4d",
    "email": "buyer@example.com",
    "ipAddress": "203.0.113.42",
    "deviceFingerprint": "dev_iphone_15_7ac9",
    "paymentMethodHash": "pmh_visa_44e9",
    "amountMinor": 12999,
    "currency": "USD"
  }'

201Risk assessment response

json

{
  "assessmentId": "c8acf6d5-8bf4-4b80-a7e5-1b33583c1c23",
  "riskScore": 34,
  "action": "allow",
  "recommendedAction": "allow",
  "policyMode": "hybrid",
  "riskLevel": "medium",
  "reasonCodes": [],
  "featureContributions": {},
  "engineVersion": "v2",
  "latencyMs": 41
}

Persist assessmentId, action, score, and reason codes with your order record.

6. Send a signed lifecycle event

javascript

import crypto from "node:crypto";

const payload = {
  companyId: process.env.VERTEXY_COMPANY_ID,
  eventSource: "checkout-service",
  externalEventId: "evt_us_payment_10492",
  idempotencyKey: "evt_us_payment_10492",
  userId: "usr_8f7b2c9a4d",
  eventType: "payment_succeeded",
  timestamp: new Date().toISOString(),
  metadata: { orderId: "ord_us_10492", channel: "web" }
};
const body = JSON.stringify(payload);
const signature = crypto.createHmac("sha256", process.env.VERTEXY_WEBHOOK_SECRET).update(body).digest("hex");
const response = await fetch(`${process.env.VERTEXY_API_BASE_URL}/events/ingest`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-event-signature": signature,
    "x-event-timestamp": String(Math.floor(Date.now() / 1000)),
    "x-event-nonce": crypto.randomUUID()
  },
  body
});
if (!response.ok) throw new Error(`VertexY ingest failed: ${response.status}`);

7. Submit the final outcome

bash

curl -X POST "$VERTEXY_API_BASE_URL/risk-engine/feedback" \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assessmentId": "c8acf6d5-8bf4-4b80-a7e5-1b33583c1c23",
    "idempotencyKey": "feedback_ord_us_10492",
    "outcome": "approved",
    "occurredAt": "2026-06-21T10:35:00.000Z"
  }'

Verify success

Assessment returns 201 and an assessmentId.
Event ingestion returns 201, status: accepted, and an assessment.
Feedback returns 201 and { "accepted": true }.
The evaluation appears in Dashboard → Event Explorer.

Next, complete the go-live checklist and review retries and idempotency.