Core concepts

A handful of conventions apply across every endpoint. Learn them once and the rest of the API reads naturally.

Clients and the id parameter

In Masttro, a client is a family, entity group or individual whose wealth you manage. Almost every endpoint takes a client id in the path, for example /Holdings/24.

• Get valid ids from GET /Clients. Use the numeric id field, not the alphanumeric clientID.
• If you ask for a client your user cannot access, the API returns 400 with "The user does not have access to this client or the client does not exist."
• id=0 means "all clients you can access" on most endpoints. Large families can produce large responses, so prefer a specific client where you can. MCP tools do not accept id=0: every tool call must name a specific client (see the tool catalog).

Tenants and the tenantId parameter

A tenant is a Masttro environment, such as a family office, with its own set of clients. Most API users belong to a single tenant and can ignore this section. If your user has access to more than one, every request runs against your user's main tenant unless you say otherwise.

• List the tenants you can access with GET /Tenants.
• Add the tenantId query parameter to any other GET endpoint to query that tenant, for example /Holdings/31?yearMonth=202509&tenantId=MORANO. The match is case-insensitive.
• Client ids belong to a tenant. Call /Clients with the same tenantId to find them.
• A tenant your user cannot access returns 400 with "The user does not have access to this tenant or the tenant does not exist."

MCP tools take the same optional tenantId argument, and get_tenants lists the tenants.

Dates and periods

Dates are passed as integers, not ISO strings.

yearMonth anchors the request to a month-end. Holdings are positions as of that month-end. Period-based endpoints look back from it using the period parameter:

Responses echo the effective range: initialDate is the start of the period and date is the date you selected.

Reporting currency

The ccy parameter sets the reporting currency for monetary values, using a 3-letter currency code such as USD, EUR or MXN (case-insensitive). It defaults to USD, except on Grouped performance where it is required.

Many responses carry both views of a value:

• Fields ending in LocalCCY, or prefixed local, are in the instrument's own currency, named in localCCY.
• Fields ending in RepCCY, and unqualified values such as marketValue, are in the reporting currency you requested.

Nodes and the Global Wealth Map

Masttro models ownership as a tree called the Global Wealth Map (GWM): people and entities at the top, then holding companies, trusts and investment vehicles, then bank and brokerage accounts. Each element is a node.

• Node ids are strings in the form {nodeType}_{id}, for example "3_1842".
• parentNodeId on each row links it to its parent, so you can rebuild the tree.
• Holdings, Transactions and the Transaction log accept a nodeId filter. Grouped performance accepts investmentVehicleNodeId.
• Get the full tree, with ownership percentages and valuations, from GET /GWM/{id}.

Holdings, Transactions, Performance and Data feed updates also accept an investmentVehicle filter. When omitted, all investment vehicles are included.

Response conventions

Lists of flat records

Data endpoints return a JSON array of flat objects, one per position, transaction, lot or node. Field names are camelCase and match the reference tables exactly. Monetary and ratio fields are JSON numbers. Most other fields, including dates and quantities, are strings.

Nulls

Optional fields can be null when the value does not apply, for example accountNumber on a directly held real-estate asset. Document AI endpoints omit null fields entirely.

Empty results

Timeouts

Most calls return in seconds. Requests over many clients (id=0), long periods or many historical months can take longer. Set an HTTP timeout of at least 2 to 5 minutes for data endpoints, and avoid running several heavy requests in parallel. Your requests are processed one at a time anyway (see Rate limits).