v2

latestOpenAPI 3.1.12026-08-0785394779.1 KB

Policy Amendment Intents

Create a new policy amendment intent

Initiates a policy amendment (e.g. adding/removing dependents). The intent coordinates the amendment workflow including dependents sub-intent management, quote generation, employee confirmation, and provider processing.

post/policies/{policy_id}/policy_amendment_intents

Path parameters

policy_idstring required

Example:p_3b1333d87d9d4fd6ad83ba7f6b0e951a

Headers

X-Platform-Idstring

The target platform id. Required only when calling with a dashboard (WorkOS AuthKit) access token instead of a platform API key — the token carries no platform claim, so the caller must say which platform it means. Ignored for platform API key / embed session token callers.

Request body

Example request

{
  "amendment_reason": {
    "qualifying_life_event": {
      "event_date": "2024-12-01"
    }
  }
}

Response

idstring required

Unique identifier for the policy amendment intent. Prefixed with pai_.

objectstring

Object type identifier.

policy_idstring required

The policy ID for which the amendment is requested. Prefixed with p_.

Example response

{
  "id": "pai_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "policy_id": "p_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "amendment_reason": {
    "qualifying_life_event": {
      "event_date": "2024-12-01"
    }
  },
  "required_action": {
    "due_by": "2024-12-01",
    "associated_persons": {
      "dependents": {
        "dependents_management_intent_id": "dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a"
      }
    }
  },
  "pending_confirmation": {
    "due_by": "2024-12-01",
    "quote": {
      "monthly": {
        "employee_contribution": {
          "net": 123.45,
          "tax": 123.45,
          "gross": 123.45
        },
        "employer_contribution": {
          "net": 123.45,
          "tax": 123.45,
          "gross": 123.45
        },
        "total": {
          "net": 123.45,
          "tax": 123.45,
          "gross": 123.45
        }
      },
      "term": {
        "employee_contribution": {
          "net": 123.45,
          "tax": 123.45,
          "gross": 123.45
        },
        "employer_contribution": {
          "net": 123.45,
          "tax": 123.45,
          "gross": 123.45
        },
        "total": {
          "net": 123.45,
          "tax": 123.45,
          "gross": 123.45
        }
      }
    },
    "associated_persons": {
      "dependents": {
        "dependents_management_intent_id": "dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a"
      }
    }
  }
}