Start here

Getting started

Everything a partner needs to go from zero to a verified production integration. Read this page first; the rest is reference.

Hosts

Environment	Base URL	Keys	Data
Sandbox	`https://vesta-staging.hbjeffery.workers.dev/api`	`ran_test_…`	Synthetic companies, customers and jobs. Reset without notice. Outbound email and SMS are stubbed.
Production	Issued at onboarding	`ran_live_…`	Real customers. Access is limited by partner type; see Access & compliance.

The sandbox host name still carries the platform's pre-rename infrastructure name. It will move to a ridgearcnetwork.com host with a redirect and 90 days of notice; do not hard-code the host in more than one place.

The three surfaces

Surface	Path prefix	Who	Auth
Inbound API	`/api/inbound`	Lead sources, booking vendors, contractors pulling jobs inside one company	General or contractor key (owner: the company)
Installer API v1	`/api/partner/v1`	Installation companies working jobs for one or more companies	Installer-company key
Webhooks	Your HTTPS endpoint	Anyone with a subscription	HMAC-SHA256 signature you verify

Your first call

After you sign in and a sandbox key is issued, send it in the x-api-key header. The key is <keyId>.<secret>; send the whole string.

# Create a lead (general key)
curl -X POST https://vesta-staging.hbjeffery.workers.dev/api/inbound/leads \
  -H "x-api-key: $RAN_KEY" \
  -H "content-type: application/json" \
  -d '{"fullName":"Pat Example","email":"[email protected]","phone":"801-555-0100",
       "address":"123 Ridge Ave, Salt Lake City, UT 84101","smsConsent":true}'

# 201 created
{"status":"created","leadId":"lead_…"}

# List jobs (installer-company key)
curl https://vesta-staging.hbjeffery.workers.dev/api/partner/v1/jobs?limit=50 \
  -H "x-api-key: $RAN_KEY"

Integration checklist

Store the key in a secret manager. Never in source, logs or client-side code. Secrets start with ran_test_ or ran_live_ so scanners can catch leaks.
Send an Idempotency-Key on every write that has one. Retry safely on network errors and 5xx; do not retry 4xx except 429 with backoff.
Verify every webhook signature before parsing the body, reject deliveries older than five minutes, and de-duplicate on x-ridge-arc-delivery-id.
Return 2xx to a webhook only after you have durably accepted it. Anything else is retried with exponential backoff and eventually dead-lettered where you can see it.
Read the x-ridge-arc-api-version header and log it; changes are announced on the changelog.
Keep your integration inside the data boundary for your partner type. Fields you are not entitled to are simply absent; do not try to infer them.

Certification before production

Production keys are issued after a short review, usually one call. We look for:

A test webhook (install.test or a subscription test delivery) verified with your code, including a rejected forged signature.
A replayed write with the same Idempotency-Key returning the original result, and a changed body returning 409.
A rate-limit (429) handled with backoff rather than a tight retry loop.
Secret rotation exercised in sandbox: the pending secret verified, then activated, with both versions accepted during the overlap.
Written confirmation of who at your company holds the key and how it is stored, and a security contact for incident notices.
The partner agreement and, where you receive personal data, the data processing terms, signed. See API terms.

Support

Email [email protected] with your key prefix (the first 14 characters, never the full key), the request id from the x-request-id response header, and timestamps in UTC. Security issues: put SECURITY in the subject line and we respond the same day.