Developer access

Vesso’s Public API v1 is available in beta for enabled workspaces. Teams can read and write CRM records, update tasks, send product events into contact timelines, and configure signed outbound webhooks to deliver workspace activity to their endpoints.

Public API beta status

API keys and webhooks are currently available for enabled workspaces while the v1 beta stabilizes. Endpoint contracts may change during the beta period. Subscribe to the changelog or contact support@vesso.ai if you need notification before production integration changes.

Authentication

Send API keys as Bearer tokens. Keys are workspace-scoped, include explicit scopes, and should be rotated any time they are exposed.

bash

curl -H "Authorization: Bearer $VESSO_API_KEY" \
  https://api.vesso.ai/v1/me

A successful GET /v1/me response returns the workspace ID, key ID, scopes, and environment for the key.

Core endpoints

Read data

→GET /v1/accounts
→GET /v1/contacts
→GET /v1/opportunities
→GET /v1/tasks

Write data

→POST /v1/contacts and PATCH /v1/contacts/{id}
→POST /v1/opportunities and PATCH /v1/opportunities/{id}
→POST /v1/tasks and PATCH /v1/tasks/{id}

List endpoints use cursor pagination. Write endpoints enforce allowlists so computed or system-managed fields, such as scores and derived analytics, cannot be set from external clients. Account creation is not yet available through the beta API.

Product events

Use POST /v1/events to send customer or product activity into Vesso. Events are matched to contacts by email. Include an idempotency_key to prevent duplicate timeline entries and duplicate webhook deliveries during retries.

bash

curl -X POST https://api.vesso.ai/v1/events \
  -H "Authorization: Bearer $VESSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "buyer@example.com",
    "event_name": "trial_started",
    "idempotency_key": "trial-started-123",
    "properties": { "plan": "growth" }
  }'

Outbound webhooks

Enabled workspaces can subscribe HTTPS endpoints to Vesso events. Deliveries are signed with X-Vesso-Signature using the format t=<timestamp>,v1=<hmac>. Always verify both the timestamp freshness and HMAC before trusting the payload.

javascript

import crypto from 'node:crypto';

function verifyVessoSignature({ rawBody, signatureHeader, secret }) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((part) => part.split('='))
  );
  const timestamp = Number(parts.t);
  const signature = parts.v1;

  if (!timestamp || !signature) return false;

  const ageSeconds = Math.abs(Date.now() / 1000 - timestamp);
  if (ageSeconds > 300) return false;

  const signedPayload = timestamp + '.' + rawBody;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected, 'hex')
    );
  } catch {
    return false;
  }
}

Vesso retries failed deliveries and records delivery status so teams can inspect failures and recover receiver outages.

Production guidance

✓Keep API keys server-side. Do not embed keys in browser snippets, public pages, or customer-facing scripts.
✓Rate limits are applied per API key during beta. Contact support if a production integration needs higher throughput.
✓Use idempotency keys for event ingestion and external retry logic.
✓Verify webhook signatures with the raw request body before parsing or acting on a payload.

PreviousPermissions NextSecurity