Celestial Divide API

Build a dependable estate integration

Connect your systems to Celestial Divide through a predictable JSON API.

Make a first request Full OpenAPI docs

Send a standard JSON request

Pass the key in the X-API-Key request header, and declare JSON explicitly.

Method GET, POST, PUT, PATCH, or DELETE

Authentication X-API-Key: your_api_key

Response format Accept: application/json

Request bodies Content-Type: application/json

HTTP request Organization members

GET /api/v1/organization?limit=10&offset=0 HTTP/1.1
Host: celestialdivide.com
X-API-Key: your_api_key
Accept: application/json

Keys are organization-scoped.

The credential determines the organization. Estate resources outside that organization are not available to the key.

List organization members

These examples list organization members and deserialize the JSON response.

interface OrganizationMember {
  id: number;
  email: string;
  first_name: string;
  last_name: string;
  phone_number: string;
  timezone: string;
  role: "admin" | "member";
  role_display: string;
}

interface PagedOrganizationMembers {
  items: OrganizationMember[];
  count: number;
}

class CelestialApi {
  constructor(private readonly apiKey: string) {}

  async listOrganizationMembers(): Promise<PagedOrganizationMembers> {
    const response = await fetch(
      "https://celestialdivide.com/api/v1/organization?limit=10&offset=0",
      {
        headers: {
          "X-API-Key": this.apiKey,
          "Accept": "application/json",
        },
      },
    );

    if (!response.ok) {
      throw new Error(`Request failed: ${response.status}`);
    }

    return (await response.json()) as PagedOrganizationMembers;
  }
}

const api = new CelestialApi(process.env.CELESTIAL_API_KEY!);
const { items: members } = await api.listOrganizationMembers();
console.log(members);

import os
from typing import Literal

import requests
from pydantic import BaseModel


class OrganizationMember(BaseModel):
    id: int
    email: str
    first_name: str
    last_name: str
    phone_number: str
    timezone: str
    role: Literal["admin", "member"]
    role_display: str


class PagedOrganizationMembers(BaseModel):
    items: list[OrganizationMember]
    count: int


response = requests.get(
    "https://celestialdivide.com/api/v1/organization?limit=10&offset=0",
    headers={
        "X-API-Key": os.environ["CELESTIAL_API_KEY"],
        "Accept": "application/json",
    },
    timeout=30,
)
response.raise_for_status()
members = PagedOrganizationMembers.model_validate(response.json())
print(members.items)

Treat status codes as recovery instructions

401

Authenticate again

The key is missing, invalid, revoked, or expired. Confirm the header and rotate the credential if needed.

409

Refresh state before retrying

The operation conflicts with lifecycle state, uniqueness rules, or a concurrent change. Read the detail and refetch the resource.

422

Correct the request

Schema or business validation failed. A detail list identifies fields; a detail string describes a broader rule.

500

Retry with restraint

An unexpected failure occurred. Use capped exponential backoff for safe requests and contact support if it persists.

Validation detail422

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Business rule detail409 / 422

{
  "detail": "The submitted value violates an asset rule."
}

Unexpected server error500

{
  "detail": "Internal Server Error"
}

Send machine values, display readable labels

These references are generated from current application choices and asset types. Use the machine value in payloads.

Bidding round statuses 3 values

Machine value	Readable label
`active`	Active
`completed`	Completed
`locked`	Locked

Debt types 10 values

Machine value	Readable label
`MORTGAGE`	Mortgage
`LIEN`	Lien
`AUTOMOBILE`	Automobile
`PERSONAL`	Personal
`BUSINESS`	Business
`LINE_OF_CREDIT`	Line of Credit
`STUDENT_LOAN`	Student Loan
`CREDIT_CARD`	Credit Card
`DEBT_CONSOLIDATION`	Debt Consolidation
`OTHER`	Other

Financial asset account types 20 values

Machine value	Readable label
`TRAD_IRA`	Traditional IRA
`ROLLOVER_IRA_TRAD`	Rollover IRA (pre-tax)
`401K_TRAD`	401(k) (Traditional)
`403B_TRAD`	403(b)
`457B_TRAD`	457(b)
`457F_TRAD`	457(f)
`TSP_TRAD`	Thrift Savings Plan (TSP)
`PROFIT_SHARING_PLAN`	Profit-Sharing Plan
`MONEY_PURCHASE_PENSION`	Money Purchase Pension Plan
`DEFINED_BENEFIT_PLAN`	Defined Benefit Plan
`SEP_IRA`	SEP IRA
`SIMPLE_IRA`	SIMPLE IRA
`SOLO_401K_TRAD`	Solo 401(k) / Individual 401(k) (pre-tax portion)
`KEOGH_PLAN`	Keogh Plan
`NONQUAL_DEF_COMP_409A`	Nonqualified Deferred Compensation Plan (409A)
`ROTH_IRA`	Roth IRA
`ROTH_401K`	Roth 401(k)
`ROTH_403B`	Roth 403(b)
`ROTH_457B`	Roth 457(b)
`TSP_ROTH`	Roth Thrift Savings Plan (Roth TSP)

Filing statuses 4 values

Machine value	Readable label
`single`	Single
`married_jointly`	Married Filing Jointly
`head_of_household`	Head of Household
`married_separately`	Married Filing Separately

Taxable income changes 5 values

Machine value	Readable label
`1`	Decrease significantly
`2`	Decrease modestly
`3`	No change
`4`	Increase modestly
`5`	Increase significantly

Property types 7 values

Machine value	Readable label
`SFH`	Single Family Home
`CONDO`	Condominium
`TOWNHOUSE`	Townhouse
`MULTI`	Multi-Family
`LAND`	Vacant Land
`COMMERCIAL`	Commercial Property
`OTHER`	Other

Pronouns 3 values

Machine value	Readable label
`she`	she / her
`he`	he / him
`they`	they / them

Estate roles 3 values

Machine value	Readable label
`BENEFICIARY`	Beneficiary
`PR`	Personal Representative
`PROFESSIONAL`	Professional

Organization roles 2 values

Machine value	Readable label
`admin`	Admin
`member`	Member

Estate phases 4 values

Machine value	Readable label
`ESTATE_SETUP`	Intake
`BIDDING_OPEN`	Bids
`BIDDING_FINALISED`	Allocation & results
`ADMINISTRATION`	Administration

Lien types 4 values

Machine value	Readable label
`HELOC`	HELOC
`SECOND_MORTGAGE`	Second Mortgage
`TAX_LIEN`	Tax Lien
`OTHER`	Other

Asset types 8 types

Machine name	Readable name	Divisible	Non-divisible
`collectibles_antiques`	Collectibles & Antiques	Yes	Yes
`jewelry_precious_metals`	Jewelry & Precious Metals	Yes	Yes
`marketable_security`	Marketable Security	Yes	Yes
`other`	Other	Yes	Yes
`traditional_ira`	Pre-Tax Retirement Accounts	Yes	No
`real_estate`	Real Estate	No	Yes
`roth_ira`	Roth Accounts	Yes	No
`vehicles`	Vehicles	No	Yes

Available operations

Descriptions are generated from the live API contract. Open the full docs for schemas, parameters, and interactive request details.

Browse generated endpoints 53 operations

GET /api/v1/assets/types

List Asset Types

List supported asset types.

POST /api/v1/organization/invitations

Create Organization Invitation

Create an organization invitation and schedule its delivery.

409: The invitee email already belongs to an organization member or has a
pending invitation.

422: The requested inviter is not an administrator of this organization, or
invitation values fail domain validation.

GET /api/v1/organization/invitations

List Organization Invitations

List organization invitations, optionally filtered by lifecycle status.

GET /api/v1/organization/invitations/{invitation_id}

Get Organization Invitation

Get an organization invitation by ID.

DELETE /api/v1/organization/invitations/{invitation_id}

Cancel Organization Invitation

Cancel a pending organization invitation, attribute it to canceled_by, and return it.

This endpoint preserves the invitation as canceled; it does not hard-delete it.

409: The invitation was already accepted or canceled; only pending invitations
can be canceled.

422: The requested canceled_by user is missing from this organization, belongs
only to another organization, or is not an organization administrator.

GET /api/v1/organization

List Members

List members in the organization.

GET /api/v1/organization/{user_id}

Get Member Detail

Get details of an organization member by user ID.

PUT /api/v1/organization/{user_id}

Update Member Role

Update an organization member's role by user ID.

409: Returned when demoting the target member from admin to member would leave the
organization without any admins. This includes concurrent demotion attempts where
another request removes the only other remaining admin first.

POST /api/v1/estates

Create Estate

Create an estate in the organization.

Slug must be in the following format if provided: `estate-slug`
(lowercase, alphanumeric, hyphens only).
If not provided, it will be generated from the name.

409: Indicates that the request conflicts with existing estate state.
This can happen when an explicit slug is already taken, or when a concurrent
insert causes the database to reject the generated or explicit slug. If using
a generated slug, retrying the request will likely return 201. If the endpoint
continues throwing 409, you can contact support to investigate further.

422: Can be returned for schema validation failures, and can also
be returned when the name is blank after trimming whitespace or an explicit
slug is reserved for an application route.

NOTE: All admins of the organization at the time of estate creation will be assigned as admins
to the estate by default, you will need to manually remove them via API or the application to
remove them from the estate.

GET /api/v1/estates

List Estates

List estates in the organization.

GET /api/v1/estates/{estate_slug}

Get Estate Detail

Get details of an estate by its slug.

PATCH /api/v1/estates/{estate_slug}

Update Estate

Update an estate's name and/or slug by its current slug.

Slug must be in the following format if provided: `estate-slug`
(lowercase, alphanumeric, hyphens only).

409: The Estate is formally closed and read-only.

409: The requested slug is already used, or a concurrent update causes the
database to reject it.

422: Returned for schema validation failures, and can also
be returned when a provided name is blank after trimming whitespace, a provided
slug is blank or null, or a provided slug is reserved for an application route.

DELETE /api/v1/estates/{estate_slug}

Delete Estate

Delete an estate by its slug.

409: The Estate is formally closed and must be reopened before deletion.

POST /api/v1/estates/{estate_slug}/close

Close Estate

Formally close an Estate.

409: The Estate is already closed.

409: An allocation is currently running; closure must wait for it to finish.

POST /api/v1/estates/{estate_slug}/reopen

Reopen Estate

Formally reopen an Estate.

409: The Estate is not closed.

409: The organization's shared open-case allowance is full.

409: The Estate's organization or demo classification changes concurrently
while reopening is underway.

GET /api/v1/{estate_slug}/rounds

List Bidding Rounds

List bidding rounds for an estate.

GET /api/v1/{estate_slug}/rounds/active

Get Active Bidding Round

Get the active bidding round for an estate.

GET /api/v1/{estate_slug}/rounds/{round_no}

Get Bidding Round Detail

Get a bidding round by its public round number.

GET /api/v1/{estate_slug}/users

List Estate Users

List users for an estate by estate slug.

NOTE: This does not include organization members that will have access via the organization
to this estate, only explicit members of the estate will be shown here.

GET /api/v1/{estate_slug}/users/{user_id}

Get Estate User Detail

Get details for an estate user by estate slug and user ID.

NOTE: This does not include organization members that will have access via the organization
to this estate, only explicit members of the estate will be shown here.

PATCH /api/v1/{estate_slug}/users/{user_id}

Update Estate User

Partially update an estate user by estate slug and user ID.

NOTE: Supplied roles atomically replace direct estate roles. Adding BENEFICIARY
normally creates a missing Beneficiary. If a pending invitation for the user's
email already references a Beneficiary, no duplicate is created. Removing
BENEFICIARY deletes the Beneficiary.

409: The requested email address is already in use.

409: The update would remove the estate's last Personal Representative role. This
ensures that there is always at least one PR acting as an estate admin.

409: The update changes roles for an estate that is no longer in the estate setup
phase.

409: The Estate is formally closed and read-only.

422: payload fails validation, including invalid email
format, blank email values, invalid IANA timezone identifiers, or unsupported
estate role codes.

DELETE /api/v1/{estate_slug}/users/{user_id}

Remove Estate User

Remove a user from an estate by estate slug and user ID.

409: The estate is no longer in the estate setup phase, as members can only be
removed during that phase.

409: The removal would remove the estate's last Personal Representative. This
ensures that there is always at least one PR acting as an estate admin.

409: The Estate is formally closed and read-only.

NOTE: Clears all direct estate roles and membership. If the BENEFICIARY role
existed, deletes the Beneficiary; preserves the user account and access to
other estates.

POST /api/v1/{estate_slug}/invitations

Send Invitation

Create and send an invitation for an estate by estate slug.

409: A pending invitation already exists for the invitee email address.

409: The requested beneficiary is already linked to a user account.

409: The requested beneficiary already has a pending invitation.

409: The requested invitee email address is already attached to a beneficiary
in this estate.

409: The Estate is formally closed and read-only.

422: Returned for schema validation failures, and can also be returned when
invited_by is not a member of the estate or organization, beneficiary is
provided without the BENEFICIARY role, or beneficiary does not belong to
this estate.

GET /api/v1/{estate_slug}/invitations

List Invitations

List invitations for an estate by estate slug.

GET /api/v1/{estate_slug}/invitations/{invitation_id}

Get Invitation Detail

Get details for an estate invitation by estate slug and invitation ID.

DELETE /api/v1/{estate_slug}/invitations/{invitation_id}

Revoke Invitation

Revoke a pending invitation for an estate by estate slug and invitation ID.

NOTE: Only pending invitations can be revoked. An accepted invitation or an
unknown invitation_id returns 404.

409: The Estate is formally closed and read-only.

GET /api/v1/{estate_slug}/assets

List Assets

List assets in an estate.

GET /api/v1/{estate_slug}/assets/{asset_id}

Get Asset Detail

Get details for one asset in an estate.

DELETE /api/v1/{estate_slug}/assets/{asset_id}

Delete Asset

Delete an asset from an estate while the estate is in setup.

PATCH /api/v1/{estate_slug}/assets/{asset_id}

Update Asset

Partially update a generic or financial asset in an estate.

409: The estate is no longer in the Estate Setup phase, as assets can only
be updated during setup.

409: A concurrent write or database constraint rejects the save. Retrying may
succeed if the conflict was transient.

422: Returned for schema validation failures, and can also be returned when
a provided name is blank after trimming whitespace, updated_by_id does
not reference an estate or organization user, the resulting
expected_sale_value is greater than market_value, the requested
divisible value is incompatible with the asset type, account_type is
provided for a non-financial asset, account_type is explicitly null or
incompatible for a financial asset, original valuation amount/date are
not both provided or both omitted, or original_market_value_date is later
than market_value_date.

POST /api/v1/{estate_slug}/assets/real_estate

Create Real Estate Asset

Create a real estate asset in an estate.

409: The estate is no longer in the Estate Setup phase, as assets can only
be created during setup.

409: A concurrent write or database constraint rejects the save. Retrying may
succeed if the conflict was transient.

422: Returned for schema validation failures, and can also be returned when
the asset name is blank after trimming whitespace, expected_sale_value is
greater than market_value, created_by_id does not reference an estate or
organization user, original valuation amount/date are not both provided
or both omitted, or original_market_value_date is later than
market_value_date.

PATCH /api/v1/{estate_slug}/assets/real_estate/{asset_id}

Update Real Estate Asset

Partially update a real estate asset in an estate.

409: The estate is no longer in the Estate Setup phase, as assets can only
be updated during setup.

409: A concurrent write or database constraint rejects the save. Retrying may
succeed if the conflict was transient.

422: Returned for schema validation failures, and can also be returned when
a provided name is blank after trimming whitespace, updated_by_id does
not reference an estate or organization user, the resulting
expected_sale_value is greater than market_value, original valuation
amount/date are not both provided or both omitted, or
original_market_value_date is later than market_value_date.

POST /api/v1/{estate_slug}/assets/{asset_type}

Create Asset

Create a generic or financial asset in an estate.

409: The estate is no longer in the Estate Setup phase, as assets can only
be created during setup.

409: A concurrent write or database constraint rejects the save. Retrying may
succeed if the conflict was transient.

422: Returned for schema validation failures, and can also be returned when
the asset name is blank after trimming whitespace, expected_sale_value is
greater than market_value, created_by_id does not reference an estate or
organization user, the requested divisible value is incompatible with
the asset type, account_type is provided for a non-financial asset,
account_type is missing or incompatible for a financial asset, original
valuation amount/date are not both provided or both omitted, or
original_market_value_date is later than market_value_date.

POST /api/v1/{estate_slug}/beneficiaries

Create Admin Beneficiary

Create a beneficiary and associated non-login user.

NOTE: Atomically creates a user, estate membership, Beneficiary, and BENEFICIARY role.

409: The estate is no longer in the Estate Setup phase.

409: The generated internal email or requested username is already in use, or
a concurrent write or database constraint rejects beneficiary creation.

422: Returned for schema validation failures, and can also be returned when
created_by_id does not reference an estate or organization user, nested
user names are blank after trimming whitespace, beneficiary choices are
invalid, total_income is negative, split_percentage is outside zero to
one hundred, or model validation rejects the user or beneficiary.

GET /api/v1/{estate_slug}/beneficiaries

List Beneficiaries

List beneficiaries in an estate.

POST /api/v1/{estate_slug}/beneficiaries/{user_id}

Create Beneficiary

Add beneficiary details to an accessible existing user.

NOTE: Atomically creates the Beneficiary and adds the BENEFICIARY role,
preserving other estate roles and creating estate membership if needed.

409: The estate is no longer in the Estate Setup phase.

409: The user is already a beneficiary, has a pending linked beneficiary
invitation, or a concurrent write or database constraint rejects role
assignment or beneficiary creation.

422: Returned for schema validation failures, and can also be returned when
created_by_id does not reference an estate or organization user,
beneficiary choices are invalid, total_income is negative,
split_percentage is outside zero to one hundred, or model validation
rejects the beneficiary.

GET /api/v1/{estate_slug}/beneficiaries/{user_id}

Get Beneficiary Detail

Get a beneficiary in an estate by user ID.

PATCH /api/v1/{estate_slug}/beneficiaries/{user_id}

Update Beneficiary

Partially update a beneficiary in an estate.

409: The estate is no longer in the Estate Setup phase.

422: updated_by_id does not reference an estate or organization user, or the
submitted split percentage has more precision than the beneficiary model
can store.

DELETE /api/v1/{estate_slug}/beneficiaries/{user_id}

Delete Beneficiary

Delete a beneficiary from an estate.

NOTE: Atomically deletes the Beneficiary and removes the BENEFICIARY role,
preserves other direct roles and the user account, and deletes estate
membership if no direct estate roles remain.

409: The estate is no longer in the Estate Setup phase, as beneficiaries can
only be deleted during setup.

POST /api/v1/{estate_slug}/cash

Create Cash

Create cash for an estate's active bidding round.

409: The estate is not in the Estate Setup or Bidding Open phase.

409: The estate has no active bidding round.

409: A concurrent write or database constraint rejects the save.

422: The beneficiary is outside the estate.

422: created_by_id does not reference an estate or organization user.

GET /api/v1/{estate_slug}/cash

List Cash

List cash for an estate bidding round.

When no bidding round is provided, cash is returned for the active round,
or the latest round when none is active.

422: The requested bidding round does not exist for the estate.

GET /api/v1/{estate_slug}/cash/{cash_id}

Get Cash Detail

Get one cash record in an estate.

PATCH /api/v1/{estate_slug}/cash/{cash_id}

Update Cash

Partially update cash in an estate.

409: The estate is not in the Estate Setup or Bidding Open phase

409: The cash does not belong to an active bidding round.

409: A concurrent write or database constraint rejects the save.

422: updated_by_id does not reference an estate or organization user,

422: The merged cash values violate account type, contribution, or withholding rules.

DELETE /api/v1/{estate_slug}/cash/{cash_id}

Delete Cash

Delete cash from an estate.

409: The estate is formally closed or has no active bidding round.

409: A concurrent write or database constraint rejects the delete.

POST /api/v1/{estate_slug}/liabilities/mortgage

Create Mortgage

Create a mortgage in an estate.

409: The estate is no longer in the Estate Setup phase, the property already
has a mortgage, or a concurrent write or database constraint rejects the save.

422: The name is blank after trimming, created_by_id does not reference an
estate or organization user, or mortgage model rules reject the values.

POST /api/v1/{estate_slug}/liabilities/lien

Create Lien

Create a property lien in an estate.

409: The estate is no longer in the Estate Setup phase, or a concurrent write
or database constraint rejects the save.

422: The name is blank after trimming, created_by_id does not reference an
estate or organization user, lien_type is unsupported, or lien model rules
reject the values.

GET /api/v1/{estate_slug}/liabilities/{liability_id}

Get Liability Detail

Return one liability in an estate.

PATCH /api/v1/{estate_slug}/liabilities/{liability_id}

Update Liability

Partially update a generic liability in an estate.

409: The estate is no longer in the Estate Setup phase, or a concurrent write
or database constraint rejects the save.

422: updated_by_id does not reference an estate or organization user, or the
merged liability values violate generic liability model rules.

DELETE /api/v1/{estate_slug}/liabilities/{liability_id}

Delete Liability

Delete any liability/debt from an estate.

409: The estate is no longer in the Estate Setup phase.

POST /api/v1/{estate_slug}/liabilities/{debt_type}

Create Liability

Create a generic liability in an estate.

409: The estate is no longer in the Estate Setup phase, or a concurrent write
or database constraint rejects the save.

422: The debt type is not generic, the name is blank after trimming,
created_by_id does not reference an estate or organization user, or debt
model rules reject the values.

GET /api/v1/{estate_slug}/liabilities

List Liabilities

List liabilities in an estate.

PATCH /api/v1/{estate_slug}/liabilities/mortgage/{liability_id}

Update Mortgage

Partially update a mortgage in an estate.

409: The estate is no longer in the Estate Setup phase, the replacement
property already has a mortgage, or a concurrent write or database
constraint rejects the save.

422: updated_by_id does not reference an estate or organization user, the
merged balance and monthly payment are not both zero or both positive,
or the merged mortgage values violate mortgage model rules.

PATCH /api/v1/{estate_slug}/liabilities/lien/{liability_id}

Update Lien

Partially update a property lien in an estate.

409: The estate is no longer in the Estate Setup phase, or a concurrent write
or database constraint rejects the save.

422: updated_by_id does not reference an estate or organization user,
lien_type is unsupported, or the merged lien values violate property lien
model rules.

Need request and response schemas? Review the full OpenAPI documentation.

Tell us what your integration needs

We welcome feature requests, including ordering and filtering options that reduce extra client work. Straightforward requests can often be assessed quickly; complex requests involving workflow rules or new write behavior need additional design and validation.

Share the endpoint, desired result, example payload, and the workflow it enables with our team.