Serverless functions

A serverless function is code you write and SalesOS runs — no server to host. Use one where a custom action would need an endpoint of your own: score a lead, call a partner API when a deal closes, clean data nightly, or answer a webhook-style request from another system.

Functions are part of the Enterprise plan. Manage them under Settings → Developer → Functions, or with /v1/functions (org owners and admins).

A first function

export default async function handler(
  input: { email?: string },
  context: { trigger: string; invocationId: string },
) {
  const key = await secrets.get('CLEARBIT_KEY');
  const res = await fetch(`https://person.clearbit.com/v2/people/find?email=${input.email}`, {
    headers: { Authorization: `Bearer ${key}` },
  });
  if (!res.ok) throw new Error(`Enrichment failed: ${res.status}`);
  const person = await res.json();
  log.info('enriched', input.email);
  return { title: person.employment?.title ?? null };
}

Export a default async (input, context) handler (or set module.exports). What it returns must be JSON; it becomes the invocation's output.

# Create it (version 1 is compiled and deployed)
curl -X POST https://api.salesos.org/v1/functions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "apiName": "enrich_person", "name": "Enrich person", "language": "typescript",
        "source": "export default async (input) => ({ echo: input })",
        "allowedHosts": ["person.clearbit.com"], "scopes": ["READ_LEADS", "WRITE_LEADS"] }'

What the code can use

There are no imports and no Node.js APIs — no require, process, fs, timers or environment. The only capabilities are these globals:

salesos.*

const lead = await salesos.leads.get(input.leadId);
await salesos.leads.update(lead.id, { rating: 'HOT', customFields: { segment: 'enterprise' } });
const open = await salesos.opportunities.list({ isClosed: false, limit: 50 });
const project = await salesos.records('custom:project').create({ title: 'Kickoff' });
const res = await salesos.graphql('{ accounts(limit: 5) { nodes { id name } } }');

leads, contacts, accounts, opportunities, tasks and records('<object>') (including quote for reads and custom:<apiName>) offer get, list (returns { nodes, pageInfo: { page, limit, total, totalPages, hasMore } }), create, update and delete; graphql(query, variables) runs any GraphQL query or mutation. Every call goes through the same services as the REST API:

• It acts as the run-as member (the function's creator), in your organization only, with that member's visibility, sharing, Profile and field-level security. An admin's admin visibility is dropped unless you turn on Keep admin visibility.
• It holds only the scopes you declare (READ_LEADS, WRITE_LEADS, …); nothing is granted by default.
• Writes run validation rules, before-save hooks, workflows, webhooks and the audit trail. Errors carry the REST codes (VALIDATION_RULE_FAILED, …) in error.code.

Triggers

HTTP invocation

curl -X POST https://api.salesos.org/v1/functions/enrich_person/invoke \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c…" \
  -d '{ "input": { "email": "[email protected]" } }'

{ "invocationId": "fni_…", "status": "SUCCEEDED", "ok": true,
  "output": { "title": "CTO" }, "error": null, "durationMs": 412, "version": 3 }

• API keys and OAuth tokens need the INVOKE_FUNCTIONS scope, and act as their owner, who — like a session caller — must be an org owner or admin.
• The function must have its HTTP endpoint turned on (403 FUNCTION_HTTP_DISABLED).
• A function's own errors are a 200 with ok: false and error.code (FUNCTION_ERROR, FUNCTION_INACTIVE, NO_ACTIVE_VERSION, TIMEOUT, CPU_LIMIT, MEMORY_LIMIT, HOST_CALL_LIMIT, RESULT_TOO_LARGE, …). 429 means the sandbox is busy (FUNCTIONS_BUSY, FUNCTION_CONCURRENCY_LIMIT) — retry later.
• Outbound fetch calls carry X-SalesOS-Function-Depth. A function calling functions (through this endpoint) is stopped at depth 3 with 508 FUNCTION_RECURSION_LIMIT.

Versions and deploys

Every save creates an immutable version (compiled immediately; syntax errors and imports are rejected with FUNCTION_COMPILE_FAILED). Deploying makes a version the one that runs; roll back re-deploys the version before it.

From the CLI

Keep functions in a metadata project and work locally:

salesos functions init score_lead                 # src/functions/score_lead/{function.json,index.ts}
salesos functions deploy score_lead --check-only  # compile + validate, nothing written
salesos functions deploy score_lead --activate
salesos functions invoke score_lead --input @sample.json
salesos functions logs score_lead --follow

function.json holds the settings (triggers, limits, allow-list, scopes) and secret names; values are set per org with salesos functions secrets <apiName> set NAME. A new function runs as the member who deploys it.

Limits

Invocations are kept for 14 days.

Security model

What SalesOS guarantees about where your code runs:

• Isolated from SalesOS and from other tenants. Each invocation starts in a fresh, empty sandbox outside the API server. It has no file system, no environment, no database connection and no credentials — only the globals listed above. Nothing persists between invocations.
• No network except what you allow. Code has no direct network access. fetch is performed by SalesOS on the function's behalf, only to hosts on its allow-list (or under a named credential's base URL), and never to private, internal or reserved addresses.
• Data crosses as JSON only. Your code never holds a reference to a SalesOS object; every salesos.* call is checked as the run-as member with the function's declared scopes.
• Limits are enforced, not advisory. A run that exceeds its time, CPU, memory, output or host-call limit is stopped and reported with the matching status (TIMEOUT, MEMORY_LIMIT, …).