Authenticate to the Socotra API by calling the login endpoint with your tenant credentials; Socotra returns a session token to include in subsequent request headers
Create a policyholder account via POST to the /policyholders endpoint with the insured's name, contact, and identifying information; retain the returned policyholder locator
Initiate a quote by POSTing to the /policies endpoint with the product name, policyholder locator, and policy start date; Socotra creates a draft policy and triggers rating
If using an external rater: configure your external rater URL and optional auth headers in the Socotra Admin UI; Socotra will POST the full policy JSON to your rater endpoint and expect a response with pricedPerilCharacteristics per the documented schema
If the external rater returns an error message in the exceptionMessage field, Socotra returns HTTP 409 to the caller — catch this and surface a meaningful error to your frontend
Issue the policy by calling the issue endpoint; retrieve the policy locator and document download URL from the response for delivery to the insured
Known gotchas
Each Socotra tenant has its own subdomain; API base URLs are tenant-specific — do not hardcode a shared base URL, and confirm your sandbox vs. production environment URLs separately
The external rater integration is synchronous; if your rater service is slow or unavailable, the Socotra policy creation call will time out — build appropriate timeouts and circuit-breaker logic into your rater service
Socotra uses a locator (UUID-like string) as the primary identifier for all objects (policyholders, policies, exposures); never use human-readable IDs or policy numbers as API keys — always use the locator returned at object creation
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp