Policies

The policies query returns the policies connected to your account, along with the premium each one pays, what the insurer values it at, and the fund units it currently holds. Use it to reconcile your own system against ours, or to show a broker their portfolio.

It requires the POLICY_READ permission on your API key — contact support to have it enabled.

Fetching policies​

Results are ordered by policy number and paginated with cursors. Omit pagination to get the first 50.

query Policies($pagination: PoliciesPaginationInput, $includeSubPartners: Boolean = false) {
  policies(pagination: $pagination, includeSubPartners: $includeSubPartners) {
    __typename
    ... on PoliciesConnection {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      edges {
        cursor
        node {
          id
          active
          pickedUpAt
          firstPremiumStatus
          regularPremium {
            amount
            currency
            frequency
          }
          fundValue {
            amount
            currency
            valuationDate
          }
          fundAllocation {
            valuationDate
            funds {
              isin
              units
              isLoyaltyFund
            }
          }
        }
      }
    }
    ... on UnauthorizedOperationError {
      message
    }
    ... on RateLimitedError {
      message
      retryAfterSeconds
    }
    ... on InputValidationError {
      invalidInput
      message
    }
    ... on UnexpectedError {
      message
    }
  }
}

{
  "pagination": { "first": 50 },
  "includeSubPartners": false
}

Response

{
  "data": {
    "policies": {
      "__typename": "PoliciesConnection",
      "totalCount": 128,
      "pageInfo": { "hasNextPage": true, "endCursor": "FL-1234567" },
      "edges": [
        {
          "cursor": "FL-1234567",
          "node": {
            "id": "FL-1234567",
            "active": true,
            "pickedUpAt": "2026-07-29T14:30:00.000Z",
            "firstPremiumStatus": "RECEIVED",
            "regularPremium": { "amount": 33000, "currency": "CHF", "frequency": "MONTHLY" },
            "fundValue": {
              "amount": 1234567,
              "currency": "CHF",
              "valuationDate": "2026-07-29"
            },
            "fundAllocation": {
              "valuationDate": "2026-07-29",
              "funds": [
                { "isin": "LU0552385295", "units": 142.8317, "isLoyaltyFund": false },
                { "isin": "LU0552385295", "units": 3.1104, "isLoyaltyFund": true }
              ]
            }
          }
        }
      ]
    }
  }
}

What we provide​

regularPremium is the premium the policy pays today, not the one its offer was written with — premiums are indexed, paused and rewritten over a policy's life. Amount and cadence stay separate rather than combined into a yearly or lifetime figure, so the total your side books is one you defined. It is null when no recurring premium is due: a single-premium contract, a policy that is paid up, or one that has run past its premium-paying term.

fundValue is priced from the same unit holdings fundAllocation publishes, so the units multiply out to it, and it is the same figure the policyholder sees in their app. 0 is a valuation; null means nothing has been valued yet.

fundAllocation is null when we hold no valuation for the policy — usually because there is none to hold (no premium invested yet, or a product with no investment component).

Any nullable field on a policy can also be null because we could not read it, and the response then carries an entry in its errors array naming the policy and the field. Check errors before you treat a null as an empty portfolio, as a policy that pays nothing, or as one the insurer has never valued.

The query names no person. Policy numbers, premiums and fund holdings are still personal data about the policyholder under the GDPR, and must be handled inside your data-processing agreement.

Digital policy pickup​

pickedUpAt is the recorded date and time when the policyholder confirms digital receipt of the policy. A non-null timestamp means the policy is picked up. null means no digital pickup is recorded.

App registration, inbox confirmation, a document download, and payment of the first premium are separate events. None of them alone sets pickedUpAt. This status does not change postal delivery settings or prove that a postal delivery occurred.

Existing pickup dates are available through this query without waiting for a new event. Check the response's errors array before treating null as a policy awaiting pickup.

Subscribe your existing webhook URL to POLICY_PICKED_UP for notifications of new pickups. Reconcile the policy state through policies when you receive a notification and periodically to recover missed deliveries.

Fund values and how fresh they are​

Each policy's holdings are priced daily: its fund units are multiplied by the funds' own closing prices and converted into the policy's currency. valuationDate is the day that produced amount.

Fund prices reach us once a day and unit holdings a few times a day, so valuationDate is normally the most recent business day rather than today. There is no intraday figure to ask for — requesting the field more often returns the same number until the next pricing run.

Where a policy holds loyalty units (Treuefonds), amount includes them. The insurer credits those on its own schedule, so for such a policy valuationDate can be a later day than fundAllocation.valuationDate, which names the regular holdings' day.

The read budget​

Selecting fundValue draws on a per-broker budget of 100 requests per 30 minutes — each broker you act for carries its own. One request costs one unit whatever its page size, so a window covers 5,000 policies at the default 50 a page, or 10,000 at the maximum 100. A request that omits the field costs nothing.

If that does not fit your integration, tell us what you need: the ceiling is set per partner, and raising yours does not require a release.

When the budget runs out​

A request over the budget returns RateLimitedError and no policies.

{
  "data": {
    "policies": {
      "__typename": "RateLimitedError",
      "message": "This broker has read more policy valuations than its budget allows in the current window. No policies were returned.",
      "retryAfterSeconds": 842
    }
  }
}

Wait retryAfterSeconds before you retry. A retry inside the window consumes nothing and returns this same error, so a loop that retries immediately will still be looping when the window resets — and will spend the new budget in seconds.

If you expect to approach the ceiling, pace your own calls against the window rather than relying on being refused — and tell us if your volume needs a higher one.

Your own policies or your whole tree​

With includeSubPartners left at false, as in the query above, you get only the policies of the broker in the x-partner-id header. Flip the variable to include every broker below that one in the hierarchy:

{
  "pagination": { "first": 50 },
  "includeSubPartners": true
}

That widens the result to the whole sub-tree and requires the additional POLICY_TREE_READ permission — without it the query returns UnauthorizedOperationError.

Paging through the book​

Page in one direction at a time: after with first to go forwards, before with last to go backwards. Mixing the two returns an InputValidationError with invalidInput: PAGINATION_CONFLICTING_ARGUMENTS. A page holds at most 100 policies.

The cursor is the policy number itself, so you can resume from an ID you already stored. If that policy is no longer readable — inactive policies are eventually removed — you get PAGINATION_CURSOR_NOT_FOUND rather than an empty page. Restart the walk without a cursor.

Full field-by-field reference: Schema Reference.