The valueverde Partner API

You bring the customer. We hold the cooperative catalogue, the order book, and the money movement. This API is the seam between the two.

A partner integration does three things:

1. Shows its users the cooperatives they can invest in.
2. Registers each of those users with us once, as a managed investor.
3. Places share-purchase orders on their behalf, and follows what happens next.

Everything else — pricing, settlement, share certificates, the cooperative relationship — happens on our side. You never compute an amount, and there is no field anywhere in this API that lets you set one.

The whole flow, once

This is the entire integration. Every arrow is one HTTP call, and nothing else is required to go from credentials to a settled holding.

Two things in that picture are worth pausing on.

The order does not settle in the request. POST …/share-purchases returns 201 with the order submitted. Approval and settlement happen afterwards, on our side, over days. Your UI has to be able to say "in progress", and your backend has to have somewhere to put the news when it arrives — a webhook endpoint, or a poller.

The investor is created once and reused. POST /v1/investors is keyed on your own customer reference and is idempotent on it. You are not creating a session or a cart; you are registering a person with us, permanently.

Where to start

If you want to…	Read
Have something working in 20 minutes	Quickstart — copy-pasteable, end to end
Understand the investing flow properly	The investing flow — states, gates, and what each call needs
Know what a token is and how long it lasts	Authentication
Receive order updates instead of polling	Webhooks
Handle failures well	Errors
Look up an exact field	API reference

Before you begin

You need a client_id and client_secret issued by valueverde Partner Support. Email partners@valueverde.de to request them, and say which of the two integration shapes you need:

• Catalogue only — you display cooperatives and hand users off to us. Scopes: cooperatives:read, projects:read.
• Full investing — you also register investors and place orders. Adds: investors:read, investors:write, applications:read, applications:write, portfolio:read.

The API speaks OAuth2 client_credentials over HTTPS. There is no API-key fallback and no end-user login: your backend authenticates as itself and acts on behalf of investors it has registered. Every partner endpoint lives under /v1.

Base URLs

Environment	Base URL	Use it for
Production	https://api.valueverde.de	Live traffic. Real orders, real money, real cooperatives.
Staging	https://api.staging.valueverde.de	Building and testing. Same contract, same shapes, no money moves.

Both serve the full /v1 contract. Build against staging, then change the host — nothing else about a request differs between the two.

Credentials are per-environment: a staging client_id will not authenticate against production, and vice versa.

Conventions

These hold everywhere, so they are stated once here rather than repeated on every endpoint.

• JSON is snake_case, in both directions.
• Money is a decimal string, never a JSON number — "100.00", with a separate *_currency field (ISO-4217). Parse it into a decimal type. A JSON number would reach most clients as an IEEE-754 double, which is both inexact and lossy about scale (100.00 comes back as 100). Percentages, distances and tonnages are ordinary numbers; only amounts of money are strings.
• Timestamps are ISO-8601 with an offset. Dates that are calendar days (birth_date) are plain yyyy-MM-dd.
• IDs are UUIDs, and the name of an id is the same everywhere it appears: an investor is investor_id, an order is share_purchase_id.
• Lists are paged envelopes, never bare arrays: items plus page, size, total_items, total_pages, has_next, has_previous. page is 1-based.
• Errors are RFC 9457 problem documents with a stable machine-readable code and a trace_id to quote at us.
• Unknown request fields are rejected, not ignored. A typo is a 400, not a silent misbooking.