Sovela for developers
Connect your practice-management system, case tracker or reporting to Sovela. Your systems can read your organization's own data and be told when it changes.
Your organization's data, never a family's. The API reaches what your organization's admins see in the Sovela console: which families work with your professionals (names and dates), seats, referral codes and their counts, and outcomes across all your client families together (never fewer than five). It never reaches a family's messages, documents, money or records, whatever access your professionals have been given.
Quick start
- In the Sovela console, open your organization and make an API key with the scopes you need. Copy it: it's shown once.
- Send it as a bearer token to your region's server:
curl https://api.covalentfamilies.com/v1/orgs/$ORG_ID/clients \
-H "Authorization: Bearer $SOVELA_API_KEY"Your organization's id is in the console's address bar on its page, and in every webhook as organization.id.
Regions
Sovela keeps each country's data in that country. Use the server for the region your organization is in; the key says which (aln_us_… or aln_ca_…), and a key sent to the other region is refused.
| Region | Server |
|---|---|
| United States | https://api.covalentfamilies.com |
| Canada | https://api.covalentfamilies.ca |
API keys
- Made in the console by your organization's owners (or anyone given a role that may manage keys), with a second sign-in factor. Up to 25 keys at a time; each can have an expiry.
- A key acts for the person who made it and can never do more than they can now. If they leave your organization or lose a permission, their keys stop working for it at once, so make long-lived keys from an account that will stay.
- Read-only. Keys reach only the reads listed below; nothing a key does can change data.
- Shown once, stored as a fingerprint. Sovela can't show a key again. If one is lost or leaked, revoke it in the console (it stops at once) and make another.
- Every use is in your organization's activity log, with the key.
Scopes
A key carries scopes, and each scope opens the reads below. You can give a key only scopes you hold yourself.
| Scope | Opens |
|---|---|
org.analytics.read | GET /v1/orgs/{orgId}/outcomesDe-identified outcomes across the firm's client families over 90 days (never below 5 families) |
org.billing.manage | GET /v1/orgs/{orgId}/seatsThe organization's seats for client families: how many, how many in use, and what pays for them |
org.clients.read | GET /v1/orgs/{orgId}/clientsWhich families gave the firm's professionals access, and since when (names and dates only) GET /v1/orgs/{orgId}/seats/familiesWhich client families have a seat, and which could have one (names only) |
org.members.read | GET /v1/orgs/{orgId}/membersMembers and their roles |
org.read | GET /v1/orgs/{orgId}An organization |
org.referrals.manage | GET /v1/orgs/{orgId}/referral-codesThe organization's referral codes and their counts GET /v1/orgs/{orgId}/referral-earningsThe organization's share of what families it referred have paid, by month (sums only) |
org.roles.read | GET /v1/orgs/{orgId}/rolesSystem org roles and this organization's own |
Limits
Each key can make up to 120 requests a minute. Over that, Sovela answers 429 with error: "rate_limited"; wait until the minute is up. If you need more, use webhooks to learn what changed instead of asking repeatedly.
Errors
Errors are JSON with an error code and usually a message you can show or log.
| Status | error | Meaning |
|---|---|---|
| 401 | unauthenticated | No key was sent. |
| 401 | invalid_api_key | Not valid, revoked, expired, or for the other region. message says which. |
| 403 | insufficient_scope | The key doesn't carry the scope this read needs. |
| 403 | forbidden | The key is for another organization, or the person who made it can no longer do this. |
| 403 | api_key_not_accepted | This endpoint isn't part of the organization API. |
| 404 | not_found | Not found. |
| 429 | rate_limited | Too many requests this minute. |
Versioning
Sovela's own apps can't all update at once, so the API makes them, and you, one promise: a response may gain fields, but never loses or changes one. Ignore fields you don't recognize, and your integration keeps working. Webhook events follow the same rule, and new event types are only sent to webhooks that subscribe to them.
The OpenAPI document (version 1.0.0) is generated from Sovela's code, so it always matches what the servers do. You can generate a client from it.