Certificate Holder Flow

This guide covers creating a certificate holder and attaching it to a risk profile with the clause types it serves. Follow the steps in order.

Create a certificate holder

Use the Certificate Holders endpoints to create the holder. Only title is required. name, types (the clause types it supports), and metadata are optional. Keep the returned id for the next steps.

Select a risk profile

Use the Risk Profiles endpoints to list your risk profiles and pick the one to attach the holder to. Keep its id.

Attach the certificate holder to the risk profile

Patch the selected risk profile with the holder and the clause types it serves:

{
  "certificateHolders": [
    {
      "id": "<certificate-holder-id>",
      "types": ["mortgagee", "additionalInsured"],
      "defaultForTypes": ["mortgagee"]
    }
  ]
}

types are the clause types the holder supports. Setting them here also redefines the holder’s own supported set.
defaultForTypes must be a subset of types. These are the clause types the holder is the default for on this risk profile.

The update is additive. Certificate holders already on the risk profile are kept, and re-sending a holder overrides its defaultForTypes. To detach a holder, send removeCertificateHolders with its id. A request must carry at least one of certificateHolders or removeCertificateHolders, and the same holder cannot be added and removed in the same request.

Verify the attachment

Retrieve the risk profile with the Risk Profiles endpoints. The holder appears in certificateHolders, and its clause types appear in certificateHolderClauseTypes.

Available clause types: mortgagee, additionalInsured, lossPayee, lendersLossPayable, jointLossPayee. Browse all endpoints, parameters and example responses in the API Reference.

Case Creation Flow