Create Secondary Transaction
POST/v1alpha1/issuers/:issuerId/secondaryTransactions
Scope(s): readwrite_issuer_secondarytransactions
Creates a secondary transaction in draft and returns it under secondaryTransaction, including its secondaryTransactionId. Persist that id: every later call is addressed by it.
A secondary transaction in draft is not a placeholder. Creating one soft-locks every security in it, so those shares can't be exercised or sold elsewhere in Carta, and it starts the issuer's review. Create a secondary transaction only for a trade you intend to complete. It stays in draft until it settles or is canceled, and the lock is released then. "Draft" means the trade is not yet on the cap table. That only changes after you call Finalize Secondary Transaction and the issuer approves the cap-table update.
Carta takes the soft lock itself; there is no lock call for you to make and no lock resource on this API.
The transfer versus repurchase distinction is carried by rightOfFirstRefusal.outcome rather than by separate endpoints: EXERCISED_BY_COMPANY drives the repurchase path, and the other two drive the transfer path. buyerInformation is required on the transfer path and unused for a repurchase, where the issuer is the counterparty.
The response returns the full secondary transaction nested under secondaryTransaction: the fields you sent, plus Carta's secondaryTransactionId and state.
Both outcomes return 200, so branch on secondaryTransaction.state:
PENDING_SETTLEMENT: certificates only. Move the money, then call Finalize Secondary Transaction.PENDING_ISSUER_OPTION_COST_REVIEW: at least one option grant. The issuer must approve the option cost and withholding first. You'll be emailed when it's approved, or you can poll Get Secondary Transaction; then read the tax figures.
Send who decided the right of first refusal, and when, in rightOfFirstRefusal.decidedByName and rightOfFirstRefusal.decidedAt. The issuer sees both before approving.
Retrying. externalReferenceId makes this call safe to retry. If you lose the response (a timeout or dropped connection), send the same request again. When a transaction with that externalReferenceId already exists, Carta creates nothing, takes no new lock, and answers 409. When that transaction belongs to this issuer, the 409 carries an ErrorInfo detail whose reason is RESOURCE_ALREADY_EXISTS and whose metadata.secondaryTransactionId names it; read it with Get Secondary Transaction for its current state. The 409 does not compare the payloads: the id is that of the transaction the reference first created, whatever this request carried. A 409 with no secondaryTransactionId means another issuer's transaction holds the reference; choose another.
Request
Responses
- 200
- 400
- 401
- 403
- 409
- 500
- default
The secondary transaction, created in draft and returned in full under secondaryTransaction, with Carta's secondaryTransactionId and state. Both outcomes return 200: a certificates-only transaction is PENDING_SETTLEMENT, and one with at least one option grant is PENDING_ISSUER_OPTION_COST_REVIEW. The example contains option grants, so it is PENDING_ISSUER_OPTION_COST_REVIEW and no line carries a taxReference yet.
Returned if required fields are omitted or if provided fields fail validation.
Returned if a valid Authorization header has not been included with the request.
Returned when the user does not have permission to access the resource.
A transaction with this externalReferenceId already exists, so nothing was created. When it belongs to this issuer, the ErrorInfo detail's metadata.secondaryTransactionId names it.
Returned if an unexpected internal server error is encountered.
An unexpected error response.