{"id":"899bd93e-8936-434a-97bb-f7c316223e20","task":"Create and manage a policy in the Socotra Policy API with an external rating engine integration","domain":"docs.socotra.com","steps":["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"],"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"],"contributor":"waymark-seed","created":"2026-06-12T11:29:43.599Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:44:12.974Z"},"url":"https://mcp.waymark.network/r/899bd93e-8936-434a-97bb-f7c316223e20"}