> For the complete documentation index, see [llms.txt](https://synthesys-2.gitbook.io/synthesys-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://synthesys-2.gitbook.io/synthesys-docs/network-overview/api-reference/introduction.md). # Introduction \ Introduction ------------ ⚠️ Work in progress. Endpoints and payloads may change as the API evolves — reach out to before building against this in production. The **Synthesys Network API** is the programmable surface for tokenized fund operations. It exposes a small, deliberate set of endpoints for registering investors, reading share-class and NAV data, and placing subscription orders. The API is designed to sit between **fund administrators** — who publish authoritative valuations and provision the share-class graph — and **distributors**, who onboard end-investors and place orders on their behalf. This documentation is the canonical reference for the API. Every request body and response payload documented here is stable; integrations written against this reference will continue to work as the platform evolves. Where new fields are added, they will be additive — your application should ignore unknown fields gracefully rather than assert on them. ### Who this is for The API is consumed by two personas: * **Distributors** call the investor and order endpoints from their own backend to onboard end-investors, surface live share-class and NAV data inside their app or portal, and place subscription orders on their investors' behalf. * **Internal tooling** uses the same endpoints for reconciliation, monitoring, and analytics. If you are building an end-investor mobile or web app, you should call the API from your own backend rather than directly from the browser. This keeps credentials, audit attribution, and rate-limit accounting on the server side where they belong. ### Base URL ``` https://https://network-staging.api.synthesys.co/api/v1 ``` All paths in this reference are relative to the base URL. Throughout this documentation we'll use `$BASE` as a shell shorthand: bash ```bash export BASE=https://https://network-staging.api.synthesys.co/api/v1 ``` ### How writes and reads relate The API separates write paths from read paths by convention. Writes (investor registration, order placement, order push) live under their respective resource paths and are responsible for stamping audit fields and maintaining derived state. Reads are served from cached HTTP endpoints under `/funds/...` and `/orders/...`. Two practical implications: 1. **All writes are append-aware.** Order writes maintain a full `statusHistory` automatically. Your application never needs to manage that itself. 2. **Reads see writes immediately.** A successful write is visible to the corresponding read endpoint on the next request — there is no eventual-consistency window to design around. ### Response envelope Every response — success and error — uses the same JSON envelope: json ```json { "isError": false, "errorMsg": "NA", "data": { } } ``` | Field | Type | Notes | | ---------- | --------------- | --------------------------------------------------------------------------------- | | `isError` | boolean | `false` on success, `true` on error | | `errorMsg` | string | The literal value `"NA"` on success, or a human-readable error message on failure | | `data` | object \| array | The successful payload, or an empty object on error | This shape is consistent across every endpoint. Your application can use a single helper that unwraps `data` on success and raises on `isError === true`, then call that for every request — there are no per-endpoint envelope variations. #### A minimal helper **Node.js (no dependencies, native `fetch`):** javascript ```javascript const BASE = process.env.SYNTHESYS_BASE; // e.g. https://network-...run.app/api/v1 async function call(method, path, body) { const res = await fetch(`${BASE}${path}`, { method, headers: { 'Content-Type': 'application/json' }, body: body ? JSON.stringify(body) : undefined, }); const json = await res.json(); if (json.isError) { throw new Error(`Synthesys API error (${res.status}): ${json.errorMsg}`); } return json.data; } // Example const investor = await call('POST', '/investor/register', { distributorId: 'DT000001', externalInvestorId: 'client-investor-1', email: 'alice@example.com', }); console.log(investor.investorId); // IN000001 ``` **Python (`requests`):** python ```python import os import requests BASE = os.environ["SYNTHESYS_BASE"] # e.g. https://network-...run.app/api/v1 def call(method, path, body=None): r = requests.request(method, f"{BASE}{path}", json=body, timeout=10) payload = r.json() if payload["isError"]: raise RuntimeError(f"Synthesys API error ({r.status_code}): {payload['errorMsg']}") return payload["data"] # Example investor = call("POST", "/investor/register", { "distributorId": "DT000001", "externalInvestorId": "client-investor-1", "email": "alice@example.com", }) print(investor["investorId"]) # IN000001 ``` **curl:** bash ```bash curl -sX POST $BASE/investor/register \ -H 'Content-Type: application/json' \ -d '{ "distributorId":"DT000001", "externalInvestorId":"client-investor-1", "email":"alice@example.com" }' | jq . ``` ### ID conventions Every entity surfaced by the API is identified by a **6-digit zero-padded ID** with a 2-letter prefix. The prefix is part of the identifier and must be supplied verbatim where the API expects it. | Prefix | Entity | Example | | ------ | ----------- | ---------- | | `IS` | Issuer | `IS000001` | | `FN` | Fund | `FN000001` | | `SC` | Share class | `SC000001` | | `DT` | Distributor | `DT000001` | | `IN` | Investor | `IN000001` | | `TK` | Token | `TK000001` | | `OR` | Order | `OR000001` | Identifiers are allocated by the server at creation time. Your application should treat the returned ID as opaque and never try to predict or generate IDs locally. ### Timestamps Every timestamp the API accepts or returns is **epoch milliseconds in UTC**. This applies uniformly: `publishedAt` on a NAV record, `createdAt` and `updatedAt` on every record, and the date-range filters on NAV history. Converting on your side is a one-line operation in any language: javascript ```javascript // JS const now = Date.now(); // → 1761807929692 new Date(1761807929692).toISOString();// → "2025-10-30T08:25:29.692Z" ``` python ```python # Python import time, datetime now = int(time.time() * 1000) # → 1761807929692 datetime.datetime.fromtimestamp(1761807929692/1000, datetime.UTC) # → datetime(...) ``` #### Audit fields All writes auto-stamp four fields onto the resulting record: * `createdAt` — set on first write, never updated. * `updatedAt` — refreshed on every write that touches the record. * `createdBy` — set on first write, sourced from the optional `x-actor` header (or `"Network"` for system writes). * `updatedBy` — refreshed on every write that touches the record, same source as `createdBy`. To attribute writes to a real actor — useful in shared environments — set the `x-actor` header on every write:bashcurl -sX POST $BASE/orders/subscribe \\-H 'Content-Type: application/json' \\-H 'x-actor: ' \\-d '{...}' #### Quick reference | Area | Endpoints | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Entities | *(reference only — entities are provisioned by the Synthesys team)* | | Investors | `POST /investor/register` | | Share classes | `GET /funds/shareclass/all`, `GET /funds/shareclass/:shareClassId` | | NAV | `GET /funds/shareclass/nav/live`, `GET /funds/shareclass/nav/history` | | Orders | `POST /orders/subscribe`, `GET /orders/:orderId`, `POST /orders/subscriptions/push/:orderId`, `POST /orders/subscriptions/cancel/:orderId`, `GET /orders/subscriptions/distributor/:distributorId`, `GET /orders/subscriptions/investor/:investorId` | #### Getting started A typical first integration walks the same path: 1. Onboard your organisation — reach out to the Synthesys team at [**developer@synthesys.co**](mailto:developer@synthesys.co) to get your distributor record, share-class access, and environment hostname provisioned. See **Entities** for the model your integration will operate against. 2. Read **Authentication** to pick up the `x-actor` convention. 3. Read **Errors** so your application unwraps the envelope correctly and you have a plan for retries. 4. Use **Investors** to register a test investor under your distributor. 5. Use **Share classes** and **NAV** to read the share class and its live NAV. 6. Use **Orders** to place a subscription, inspect the priced order, then push it through to the supply-side platform. That's the entire happy path. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://synthesys-2.gitbook.io/synthesys-docs/network-overview/api-reference/introduction.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.