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://staging.ridgearc.network/api`	`ran_test_…`	Synthetic integration records. Confirm provider test modes and reset windows during onboarding.
Production	`https://ridgearc.network/api`	`ran_live_…`	Real customers. Access is limited by partner type; see Access & compliance.

The production integration target is ridgearc.network. Development and certification use staging.ridgearc.network. Keep credentials and base URLs separate. Coordinate account activation during onboarding.

Read the production workflow and financing integration design for the complete customer-to-installation journey.

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://staging.ridgearc.network/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://staging.ridgearc.network/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.