Set Reserves

curl --request PUT \
  --url https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "actionId": "1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b",
  "expectedTotalCents": 10000,
  "reserveDate": "2026-06-01",
  "memo": "Initial reserve"
}
'

import requests

url = "https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId}"

payload = {
    "actionId": "1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b",
    "expectedTotalCents": 10000,
    "reserveDate": "2026-06-01",
    "memo": "Initial reserve"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    actionId: '1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b',
    expectedTotalCents: 10000,
    reserveDate: '2026-06-01',
    memo: 'Initial reserve'
  })
};

fetch('https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'actionId' => '1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b',
    'expectedTotalCents' => 10000,
    'reserveDate' => '2026-06-01',
    'memo' => 'Initial reserve'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId}"

	payload := strings.NewReader("{\n  \"actionId\": \"1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b\",\n  \"expectedTotalCents\": 10000,\n  \"reserveDate\": \"2026-06-01\",\n  \"memo\": \"Initial reserve\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId}")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"actionId\": \"1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b\",\n  \"expectedTotalCents\": 10000,\n  \"reserveDate\": \"2026-06-01\",\n  \"memo\": \"Initial reserve\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"actionId\": \"1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b\",\n  \"expectedTotalCents\": 10000,\n  \"reserveDate\": \"2026-06-01\",\n  \"memo\": \"Initial reserve\"\n}"

response = http.request(request)
puts response.read_body

{
  "journalIds": [
    "1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b"
  ],
  "eventId": "550e8400-e29b-41d4-a716-446655440200",
  "categoryId": "550e8400-e29b-41d4-a716-446655440101",
  "expectedTotalCents": 10000
}

Reserves

Set Reserves

Sets the expected total for one (event, reserved category) scope — the reserves.set action, an ABSOLUTE “set expected total to X” (never a delta): the reserve position becomes X − paid-to-date. The previous total and the delta are recorded server-side under the scope’s lock — clients never author them.

expectedTotalCents is user display cents — the magnitude a user would type; the category’s expectedDirection orients it. Read the scope’s current total with entity balances.

X itself is unconstrained. The only law a reserve scope’s amounts obey is the identity Reserves + Paid = Expected Total, and the identity holds at every sign. A set below the scope’s paid-to-date is a legal, meaningful state (200): the remaining reserve reads NEGATIVE — the books’ honest statement that more has moved than the estimate says the scope is worth, and the difference is expected to come back (or the estimate to be corrected later). The server never blocks it.

No If-Match. Reserve writes serialize on the scope’s lock instead of an invoice watermark.

Signature preconditions (422). The category must be configured, reserved, and live (UNKNOWN_ID / NOT_RESERVED_CATEGORY / DEPRECATED_CONFIG — deprecation blocks new sets, never resets); the reserve date must not be in the future (FUTURE_DATE).

Idempotency. actionId is a client-minted uuid — an identical retry replays the original outcome; reuse with a different payload is 409 ACTION_ID_REUSED. Setting the same total again with a FRESH actionId is a defined zero-row no-op (journaled, delta 0).

Required permission: company.payment:update

PUT

api

companies

{companyId}

financials

events

{eventId}

reserves

{categoryId}

Set Reserves

curl --request PUT \
  --url https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "actionId": "1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b",
  "expectedTotalCents": 10000,
  "reserveDate": "2026-06-01",
  "memo": "Initial reserve"
}
'

import requests

url = "https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId}"

payload = {
    "actionId": "1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b",
    "expectedTotalCents": 10000,
    "reserveDate": "2026-06-01",
    "memo": "Initial reserve"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    actionId: '1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b',
    expectedTotalCents: 10000,
    reserveDate: '2026-06-01',
    memo: 'Initial reserve'
  })
};

fetch('https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'actionId' => '1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b',
    'expectedTotalCents' => 10000,
    'reserveDate' => '2026-06-01',
    'memo' => 'Initial reserve'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId}"

	payload := strings.NewReader("{\n  \"actionId\": \"1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b\",\n  \"expectedTotalCents\": 10000,\n  \"reserveDate\": \"2026-06-01\",\n  \"memo\": \"Initial reserve\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId}")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"actionId\": \"1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b\",\n  \"expectedTotalCents\": 10000,\n  \"reserveDate\": \"2026-06-01\",\n  \"memo\": \"Initial reserve\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/events/{eventId}/reserves/{categoryId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"actionId\": \"1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b\",\n  \"expectedTotalCents\": 10000,\n  \"reserveDate\": \"2026-06-01\",\n  \"memo\": \"Initial reserve\"\n}"

response = http.request(request)
puts response.read_body

{
  "journalIds": [
    "1e3f5a7b-9c0d-4e2f-4a6b-5c7d8e9f0a1b"
  ],
  "eventId": "550e8400-e29b-41d4-a716-446655440200",
  "categoryId": "550e8400-e29b-41d4-a716-446655440101",
  "expectedTotalCents": 10000
}

Authorizations

Authorization

string

header

required

API key authentication. Send your raw API key as the Authorization header value with NO scheme prefix — Authorization: YOUR-API-KEY. Do NOT prefix it with Bearer or ApiKey, and do not use an X-API-Key header; those are not accepted.

Path Parameters

companyId

string<uuid>

required

Company identifier

eventId

string<uuid>

required

Event identifier — an unknown event is 404

categoryId

string<uuid>

required

A configured RESERVED transaction category — discover ids with GET /api/v1/companies/{companyId}/financials/config/categories

Body

application/json

actionId

string<uuid>

required

Client-minted idempotency key — becomes the action's journal id. An identical retry replays the original outcome; reuse with a different payload is 409 ACTION_ID_REUSED

expectedTotalCents

integer

required

The scope's new ABSOLUTE expected total, in user display cents (never a delta). Unconstrained — a value below the scope's paid-to-date is legal and leaves the remaining reserve negative

reserveDate

string<date>

required

The reserve date (ISO YYYY-MM-DD); must not be in the future

author

string

Optional display label for the source system's author (e.g. the integrator-side user). Stamped as the journal record's display attribution; the acting principal stays the External API service user, so a label can never impersonate an in-app user. Ignored on idempotent replays

Required string length: 1 - 255

memo

string

Free-text memo

Response

The scope's refreshed expected total

The response of a reserve write: the emitted journal id(s) plus the scope's NEW expected total — the number a reserves.set to the same value would be a no-op against.

journalIds

string<uuid>[]

required

Every journal id the action emitted — the actionId you supplied first, then any companion batch it composed

Minimum array length: 1

eventId

string<uuid>

required

The scope's event, echoed

categoryId

string<uuid>

required

The scope's reserved category, echoed

expectedTotalCents

integer

required

The scope's expected total AFTER the write, in user display cents (the magnitude a user would type; the category's expectedDirection orients it)

⌘I

Getting Started

User

Entities

Event Lifecycle

Policy Transactions

Financials

Rating

Notes

Tasks

Configuration Management

Company Files

Forms

Document Generation

Submission Parsing

Reference

Set Reserves

Authorizations

Path Parameters

Body

Response