{ "openapi": "3.1.0", "info": { "title": "Sovela organization API", "version": "1.0.0", "description": "Read your organization's own data (its client roster by name and date, seats, referral codes and counts, de-identified outcomes) and receive its events by webhook. Never a family's records. Responses may gain fields over time but never lose or change them. Generated from Sovela's code." }, "servers": [ { "url": "https://api.covalentfamilies.com", "description": "United States: organizations whose data is held in the US" }, { "url": "https://api.covalentfamilies.ca", "description": "Canada: organizations whose data is held in Canada" } ], "tags": [ { "name": "orgs", "description": "Your organization" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An organization API key (aln__…), made by the organization's admins in the Sovela console. Send it to its region's server." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "FirmOutcomes": { "type": "object", "properties": { "windowDays": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "families": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "minimumFamilies": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "shown": { "type": "boolean" }, "calmMessages": { "type": [ "object", "null" ], "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "of": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "percent": { "type": [ "number", "null" ] } }, "required": [ "count", "of", "percent" ] }, "exchangesOnTime": { "type": [ "object", "null" ], "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "of": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "percent": { "type": [ "number", "null" ] } }, "required": [ "count", "of", "percent" ] }, "expensesAnsweredIn14Days": { "type": [ "object", "null" ], "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "of": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "percent": { "type": [ "number", "null" ] } }, "required": [ "count", "of", "percent" ] } }, "required": [ "windowDays", "families", "minimumFamilies", "shown", "calmMessages", "exchangesOnTime", "expensesAnsweredIn14Days" ] }, "FirmRoster": { "type": "object", "properties": { "clients": { "type": "array", "items": { "type": "object", "properties": { "grantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "enum": [ "attorney", "neutral" ] }, "professional": { "type": "string" }, "family": { "type": "string" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "status": { "type": "string", "enum": [ "active", "ended" ] } }, "required": [ "grantId", "kind", "professional", "family", "since", "endsAt", "status" ] } }, "seats": { "type": "object", "properties": { "members": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "professionalsWithClients": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "activeFamilies": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "members", "professionalsWithClients", "activeFamilies" ] } }, "required": [ "clients", "seats" ] }, "SeatCounts": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paid": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "invoiced": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pricePerSeat": { "type": [ "object", "null" ], "properties": { "currency": { "type": "string" }, "cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "currency", "cents" ] }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "renewsAt": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "status", "quantity", "renewsAt", "cancelAtPeriodEnd" ] } } }, "required": [ "total", "used", "paid", "invoiced", "pricePerSeat", "subscriptions" ] } } }, "paths": { "/v1/orgs/{orgId}": { "get": { "operationId": "getOrg", "summary": "An organization", "description": "Needs a key with the `org.read` scope, made by someone who still holds that permission in the organization.", "tags": [ "orgs" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": "string" }, "kind": { "type": "string", "enum": [ "direct", "law_firm", "mediation", "legal_aid", "court", "nonprofit", "other" ] }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "name", "slug", "kind", "status", "createdAt" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key (error: unauthenticated), or a key that isn't valid, revoked or expired, or another region's key (error: invalid_api_key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope (insufficient_scope), is for another organization, or its maker can no longer do this (forbidden)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the key's requests a minute (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orgs/{orgId}/clients": { "get": { "operationId": "getFirmRoster", "summary": "Which families gave the firm's professionals access, and since when (names and dates only)", "description": "Needs a key with the `org.clients.read` scope, made by someone who still holds that permission in the organization.", "tags": [ "orgs" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmRoster" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key (error: unauthenticated), or a key that isn't valid, revoked or expired, or another region's key (error: invalid_api_key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope (insufficient_scope), is for another organization, or its maker can no longer do this (forbidden)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the key's requests a minute (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orgs/{orgId}/members": { "get": { "operationId": "listMembers", "summary": "Members and their roles", "description": "Needs a key with the `org.members.read` scope, made by someone who still holds that permission in the organization.", "tags": [ "orgs" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "key", "name" ] } } }, "required": [ "userId", "name", "email", "title", "status", "roles" ] } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key (error: unauthenticated), or a key that isn't valid, revoked or expired, or another region's key (error: invalid_api_key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope (insufficient_scope), is for another organization, or its maker can no longer do this (forbidden)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the key's requests a minute (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orgs/{orgId}/outcomes": { "get": { "operationId": "getFirmOutcomes", "summary": "De-identified outcomes across the firm's client families over 90 days (never below 5 families)", "description": "Needs a key with the `org.analytics.read` scope, made by someone who still holds that permission in the organization.", "tags": [ "orgs" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmOutcomes" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key (error: unauthenticated), or a key that isn't valid, revoked or expired, or another region's key (error: invalid_api_key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope (insufficient_scope), is for another organization, or its maker can no longer do this (forbidden)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the key's requests a minute (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orgs/{orgId}/referral-codes": { "get": { "operationId": "listOrgReferralCodes", "summary": "The organization's referral codes and their counts", "description": "Needs a key with the `org.referrals.manage` scope, made by someone who still holds that permission in the organization.", "tags": [ "orgs" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "code": { "type": "string" }, "link": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "counts": { "type": "object", "properties": { "signedUp": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "qualified": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notCounted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "signedUp", "qualified", "notCounted" ] } }, "required": [ "id", "code", "link", "label", "active", "counts" ] } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key (error: unauthenticated), or a key that isn't valid, revoked or expired, or another region's key (error: invalid_api_key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope (insufficient_scope), is for another organization, or its maker can no longer do this (forbidden)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the key's requests a minute (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orgs/{orgId}/referral-earnings": { "get": { "operationId": "getOrgReferralEarnings", "summary": "The organization's share of what families it referred have paid, by month (sums only)", "description": "Needs a key with the `org.referrals.manage` scope, made by someone who still holds that permission in the organization.", "tags": [ "orgs" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "currency": { "type": "string" }, "invoices": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "shareCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "month", "currency", "invoices", "shareCents" ] } } }, "required": [ "months" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key (error: unauthenticated), or a key that isn't valid, revoked or expired, or another region's key (error: invalid_api_key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope (insufficient_scope), is for another organization, or its maker can no longer do this (forbidden)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the key's requests a minute (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orgs/{orgId}/roles": { "get": { "operationId": "listRoles", "summary": "System org roles and this organization's own", "description": "Needs a key with the `org.roles.read` scope, made by someone who still holds that permission in the organization.", "tags": [ "orgs" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "isSystem": { "type": "boolean" }, "permissions": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "key", "name", "description", "isSystem", "permissions" ] } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key (error: unauthenticated), or a key that isn't valid, revoked or expired, or another region's key (error: invalid_api_key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope (insufficient_scope), is for another organization, or its maker can no longer do this (forbidden)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the key's requests a minute (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orgs/{orgId}/seats": { "get": { "operationId": "getOrgSeats", "summary": "The organization's seats for client families: how many, how many in use, and what pays for them", "description": "Needs a key with the `org.billing.manage` scope, made by someone who still holds that permission in the organization.", "tags": [ "orgs" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatCounts" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key (error: unauthenticated), or a key that isn't valid, revoked or expired, or another region's key (error: invalid_api_key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope (insufficient_scope), is for another organization, or its maker can no longer do this (forbidden)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the key's requests a minute (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orgs/{orgId}/seats/families": { "get": { "operationId": "getOrgSeatFamilies", "summary": "Which client families have a seat, and which could have one (names only)", "description": "Needs a key with the `org.clients.read` scope, made by someone who still holds that permission in the organization.", "tags": [ "orgs" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "seats": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "grantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "family": { "type": "string" }, "professional": { "type": "string" }, "kind": { "type": "string" }, "givenAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "grantId", "family", "professional", "kind", "givenAt" ] } }, "eligible": { "type": "array", "items": { "type": "object", "properties": { "grantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "family": { "type": "string" }, "professional": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "grantId", "family", "professional", "kind" ] } }, "ended": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "family": { "type": "string" }, "endedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "reason": { "type": "string" } }, "required": [ "id", "family", "endedAt", "reason" ] } } }, "required": [ "seats", "eligible", "ended" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key (error: unauthenticated), or a key that isn't valid, revoked or expired, or another region's key (error: invalid_api_key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope (insufficient_scope), is for another organization, or its maker can no longer do this (forbidden)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the key's requests a minute (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "client.started": { "post": { "operationId": "event_client_started", "summary": "A family started working with the organization: one of its professionals was given access, under the organization.", "description": "Sent to each webhook subscribed to this event, signed in the Sovela-Signature header. Answer 2xx within 10 seconds; anything else is retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The event's id: the same on every retry, so a repeat can be ignored" }, "type": { "type": "string", "const": "client.started" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ] }, "data": { "type": "object", "properties": { "grantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The consent grant, as in the clients roster" }, "kind": { "type": "string", "enum": [ "attorney", "neutral" ] } }, "required": [ "grantId", "kind" ] } }, "required": [ "id", "type", "createdAt", "organization", "data" ] } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer in 10 seconds, is retried." } } } }, "client.ended": { "post": { "operationId": "event_client_ended", "summary": "A family stopped working with the organization: access ended, or the professional moved the work out of it.", "description": "Sent to each webhook subscribed to this event, signed in the Sovela-Signature header. Answer 2xx within 10 seconds; anything else is retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The event's id: the same on every retry, so a repeat can be ignored" }, "type": { "type": "string", "const": "client.ended" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ] }, "data": { "type": "object", "properties": { "grantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "enum": [ "attorney", "neutral" ] }, "reason": { "type": "string", "enum": [ "ended", "moved" ] } }, "required": [ "grantId", "kind", "reason" ] } }, "required": [ "id", "type", "createdAt", "organization", "data" ] } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer in 10 seconds, is retried." } } } }, "seat.given": { "post": { "operationId": "event_seat_given", "summary": "The organization gave a client family a seat.", "description": "Sent to each webhook subscribed to this event, signed in the Sovela-Signature header. Answer 2xx within 10 seconds; anything else is retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The event's id: the same on every retry, so a repeat can be ignored" }, "type": { "type": "string", "const": "seat.given" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ] }, "data": { "type": "object", "properties": { "seatId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "grantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "seatId", "grantId" ] } }, "required": [ "id", "type", "createdAt", "organization", "data" ] } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer in 10 seconds, is retried." } } } }, "seat.ended": { "post": { "operationId": "event_seat_ended", "summary": "A seat ended, and why.", "description": "Sent to each webhook subscribed to this event, signed in the Sovela-Signature header. Answer 2xx within 10 seconds; anything else is retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The event's id: the same on every retry, so a repeat can be ignored" }, "type": { "type": "string", "const": "seat.ended" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ] }, "data": { "type": "object", "properties": { "seatId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "grantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "reason": { "type": "string", "enum": [ "released", "grant_ended", "seats_reduced" ], "description": "released: the organization ended it; grant_ended: the family ended access; seats_reduced: fewer seats" } }, "required": [ "seatId", "grantId", "reason" ] } }, "required": [ "id", "type", "createdAt", "organization", "data" ] } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer in 10 seconds, is retried." } } } }, "referral.signed_up": { "post": { "operationId": "event_referral_signed_up", "summary": "Someone signed up with one of the organization's referral codes. Never who.", "description": "Sent to each webhook subscribed to this event, signed in the Sovela-Signature header. Answer 2xx within 10 seconds; anything else is retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The event's id: the same on every retry, so a repeat can be ignored" }, "type": { "type": "string", "const": "referral.signed_up" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ] }, "data": { "type": "object", "properties": { "codeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "codeId" ] } }, "required": [ "id", "type", "createdAt", "organization", "data" ] } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer in 10 seconds, is retried." } } } }, "referral.qualified": { "post": { "operationId": "event_referral_qualified", "summary": "A referral through one of the organization's codes qualified for a reward. Never who.", "description": "Sent to each webhook subscribed to this event, signed in the Sovela-Signature header. Answer 2xx within 10 seconds; anything else is retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The event's id: the same on every retry, so a repeat can be ignored" }, "type": { "type": "string", "const": "referral.qualified" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ] }, "data": { "type": "object", "properties": { "codeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "codeId" ] } }, "required": [ "id", "type", "createdAt", "organization", "data" ] } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer in 10 seconds, is retried." } } } }, "ping": { "post": { "operationId": "event_ping", "summary": "A test, sent from the console's Test button.", "description": "Sent to each webhook subscribed to this event, signed in the Sovela-Signature header. Answer 2xx within 10 seconds; anything else is retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The event's id: the same on every retry, so a repeat can be ignored" }, "type": { "type": "string", "const": "ping" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ] }, "data": { "type": "object", "properties": { "webhookId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "webhookId" ] } }, "required": [ "id", "type", "createdAt", "organization", "data" ] } } } }, "responses": { "2XX": { "description": "Received. Anything else, or no answer in 10 seconds, is retried." } } } } } }