Place a share purchase for a managed investor
POST/v1/investors/:investorId/share-purchases
Drafts and submits a subscription order in one step, returning 201 with the SUBMITTED order. Commercial terms are computed from the cooperative's current pricing and frozen server-side — the request carries no price fields. Requires a complete investor profile (409 INVESTOR_PROFILE_INCOMPLETE otherwise). 404 if the investor is not owned by the calling partner. Only cooperative_id, share_count, sepa_mandate.signed_at and statute_consent_given_at are required: applicant_type follows the investor's company affiliation, sepa_mandate.debtor_iban defaults to the profile IBAN, and sepa_mandate.reference is issued server-side when omitted — each may still be sent explicitly to override. Terms and privacy consent are taken from the investor's profile and are no longer accepted here. Supply an optional Idempotency-Key header to make a retried create safe: a repeat with the same body replays the original order, a repeat with a changed body is rejected (409). Note that because applicant_type may be derived, editing the investor's company affiliation between two retries makes them different orders and so a 409. A key is honoured for 24 hours; after that it is forgotten, and reusing it places a NEW order rather than replaying the original.
Request
Responses
- 201
- 400
- 401
- 403
- 404
- 409
- 422
- 429
Order drafted and submitted. Commercial terms are frozen server-side.
Response Headers
Requests permitted per minute for the authenticated API client.
Requests still available in the current window. The bucket refills continuously, so this rises as you go rather than resetting on a boundary.
Seconds until the budget is back to its full limit. Not the wait for the next single request — that is Retry-After on a 429.
Malformed request — e.g. an unknown sort, dividend_type, or affiliation token.
Missing or invalid access token.
Token lacks a scope this endpoint requires. The body carries code: INSUFFICIENT_SCOPE and a required_scopes array naming what is missing; the response also carries WWW-Authenticate: Bearer error="insufficient_scope", scope="…". A 403 with code: FORBIDDEN is a different failure and adding scopes will not fix it.
Not found — the resource does not exist, or does not belong to the calling partner. Acting on an investor another partner owns also returns 404 (no cross-tenant existence oracle).
Conflict — the order’s current state forbids this transition (e.g. already settled), the investor’s profile is incomplete or unattested, or an Idempotency-Key was replayed with a different body.
Validation failed. The errors map carries per-field detail.
Rate limit exceeded — 600 requests a minute per API client. Unlike every other 4xx here, the request itself is fine: sleep for the Retry-After seconds given and resend it unchanged. See https://docs.valueverde.de/docs/rate-limits.
Response Headers
Requests permitted per minute for the authenticated API client.
Requests still available in the current window. The bucket refills continuously, so this rises as you go rather than resetting on a boundary.
Seconds until the budget is back to its full limit. Not the wait for the next single request — that is Retry-After on a 429.
Seconds to wait before resending. Always at least 1.