Separate a stakeholder

Last updated Jun 14, 2026

Query Parameters

dry_runbooleanOptional

If true, simulate the mutation and return the would-be resource, any cascaded resources, and a fee estimate — without side effects. Available on every mutation.

Default false

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

effective_datestring<date>Required

Effective date of the separation.

Format date

separation_kindstringRequired

Categorisation of the separation event. Drives downstream cap-table mechanics and the cofounder-departure cascade. voluntary_pre_cliff typically forfeits or repurchases the unvested tranche at par. voluntary_post_cliff repurchases unvested at FMV; vested stays with the departing stakeholder absent ROFR. involuntary follows the founder agreement (often forfeiture + ROFR on vested). mutual is whatever the parties agree and the board authorises. Track A deferred this enum to Wave 3; defined here.

One of"voluntary_pre_cliff""voluntary_post_cliff""involuntary""mutual"

reasonstringOptional

Free-form reason recorded on the stakeholder for audit.

acquihire_corporate_transaction_idstringOptional

Set when the separation is bundled into an acquihire close. Causes the resulting status to be separated_to_acquirer instead of separating, with the acquirer offer-letter chain referenced via transition_record metadata.

metadataobjectOptional

Flat string-to-string map. Up to 50 keys. Keys: max 40 chars, charset [A-Za-z0-9_\\-.]. Values: max 500 chars. Keys prefixed matter_ are reserved for platform use. Metadata is retrievable but not filterable via query params.

Response Body

`application/json`

`application/problem+json`

Request

curl -X POST "https://api.mattermode.com/v1/stakeholders/{id}/separate" \  -H "Content-Type: application/json" \  -d '{    "effective_date": "2026-04-15",    "separation_kind": "voluntary_pre_cliff",    "reason": "negotiated_pre_cliff_exit",    "acquihire_corporate_transaction_id": null  }'

const body = JSON.stringify({  "effective_date": "2026-04-15",  "separation_kind": "voluntary_pre_cliff",  "reason": "negotiated_pre_cliff_exit",  "acquihire_corporate_transaction_id": null})fetch("https://api.mattermode.com/v1/stakeholders/{id}/separate", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

package mainimport (  "fmt"  "net/http"  "io/ioutil"  "strings")func main() {  url := "https://api.mattermode.com/v1/stakeholders/{id}/separate"  body := strings.NewReader(`{    "effective_date": "2026-04-15",    "separation_kind": "voluntary_pre_cliff",    "reason": "negotiated_pre_cliff_exit",    "acquihire_corporate_transaction_id": null  }`)  req, _ := http.NewRequest("POST", url, body)  req.Header.Add("Content-Type", "application/json")  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := ioutil.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}

import requestsheaders = {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",}payload = {    "effective_date": "2026-04-15",    "separation_kind": "voluntary_pre_cliff",    "reason": "negotiated_pre_cliff_exit",    "acquihire_corporate_transaction_id": null}resp = requests.post(    "https://api.mattermode.com/v1/stakeholders/stk_HrG6kLm9/separate",    headers=headers,    json=payload,)resp.raise_for_status()print(resp.json())

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.net.http.HttpRequest.BodyPublishers;var body = BodyPublishers.ofString("""{  "effective_date": "2026-04-15",  "separation_kind": "voluntary_pre_cliff",  "reason": "negotiated_pre_cliff_exit",  "acquihire_corporate_transaction_id": null}""");HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://api.mattermode.com/v1/stakeholders/{id}/separate"))  .header("Content-Type", "application/json")  .POST(body)  .build();try {  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());  System.out.println("Status code: " + response.statusCode());  System.out.println("Response body: " + response.body());} catch (Exception e) {  e.printStackTrace();}

using System;using System.Net.Http;using System.Text;var body = new StringContent("""{  "effective_date": "2026-04-15",  "separation_kind": "voluntary_pre_cliff",  "reason": "negotiated_pre_cliff_exit",  "acquihire_corporate_transaction_id": null}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/stakeholders/{id}/separate", body);var responseBody = await response.Content.ReadAsStringAsync();

curl --request POST 'https://api.mattermode.com/v1/stakeholders/stk_HrG6kLm9/separate' \  --header 'Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc' \  --header 'Matter-Version: 2026-06-10' \  --header 'Idempotency-Key: ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b' \  --header 'Content-Type: application/json' \  --data '{  "effective_date": "2026-04-15",  "separation_kind": "voluntary_pre_cliff",  "reason": "negotiated_pre_cliff_exit",  "acquihire_corporate_transaction_id": null}'

const response = await fetch("https://api.mattermode.com/v1/stakeholders/stk_HrG6kLm9/separate", {  method: "POST",  headers: {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",    "Content-Type": "application/json",  },  body: JSON.stringify({    "effective_date": "2026-04-15",    "separation_kind": "voluntary_pre_cliff",    "reason": "negotiated_pre_cliff_exit",    "acquihire_corporate_transaction_id": null  }),});if (!response.ok) {  throw new Error(`Matter API ${response.status}: ${await response.text()}`);}const data = await response.json();console.log(data);

Response

application/json

{
  "id": "string",
  "object": "stakeholder",
  "entity_id": "string",
  "kind": "natural_person",
  "name": "string",
  "contact": {
    "email": "user@example.com",
    "phone": "string",
    "address": {
      "line1": "string",
      "line2": "string",
      "city": "string",
      "county": "string",
      "region": "string",
      "postal_code": "string",
      "country": "US"
    }
  },
  "tax_id": "string",
  "residency": "st",
  "date_of_birth": "2019-08-24",
  "residential_address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "county": "string",
    "region": "string",
    "postal_code": "string",
    "country": "US"
  },
  "identification": {
    "type": "passport",
    "number": "string",
    "jurisdiction": "US-DE",
    "image_document_id": "string",
    "collected_at": 0
  },
  "boi_eligibility": "ready",
  "boi_missing_fields": [
    "date_of_birth"
  ],
  "beneficial_owner_percentage": 0,
  "voting_percentage": 0,
  "cap_table_percentage": 0,
  "boi_filing_status": "not_required",
  "experience_level": "novice",
  "accredited_investor_status": "unknown",
  "five_percent_holder": false,
  "ip_assignment_scope": "full",
  "consideration_for_initial_shares": null,
  "signed_artifacts": [
    {
      "document_id": "string",
      "type": "string",
      "executed_at": 0,
      "role": "string"
    }
  ],
  "status": "active",
  "roles": [
    {
      "type": "founder",
      "title": "string",
      "start_date": "2019-08-24",
      "end_date": "2019-08-24",
      "resolution_id": "string"
    }
  ],
  "residence_state": "string",
  "marital_status": "single",
  "spouse_id": "string",
  "spouse_name": "string",
  "spouse_tax_id_token": "string",
  "separated_at": "2019-08-24T14:15:22Z",
  "separation_kind": null,
  "separation_reason": "string",
  "transitioned_to_acquirer_id": "string",
  "community_property_state_at_grant": true,
  "metadata": {
    "customer_id": "cus_7Hpx9WxY",
    "portfolio_tag": "y-combinator-w26"
  },
  "created": 0,
  "updated": 0,
  "livemode": true
}

{
  "type": "https://mattermode.com/docs/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "Request body could not be parsed as JSON.",
  "doc_url": "https://mattermode.com/docs/guides/errors#invalid_request",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/authentication_required",
  "title": "Authentication required",
  "status": 401,
  "code": "authentication_required",
  "detail": "No bearer token was supplied. Pass `Authorization: Bearer sk_live_...` on every request.",
  "doc_url": "https://mattermode.com/docs/guides/errors#authentication_required",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No entity with id `ent_Nq3KcAbc` is visible to this token.",
  "doc_url": "https://mattermode.com/docs/guides/errors#not_found",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/invalid_state_transition",
  "title": "Invalid state transition",
  "status": 409,
  "detail": "Entity ent_Nq3KcAbc is in state `dissolved` and cannot be dissolved again.",
  "instance": "/requests/req_Qw9xYz8A",
  "code": "invalid_state_transition",
  "param": "founders[0].equity",
  "doc_url": "https://mattermode.com/docs/guides/errors#invalid_state_transition",
  "request_id": "req_Qw9xYz8A",
  "retry_after": 30,
  "authorized_by": {
    "human_principal_id": "usr_4Kj2m8pQ",
    "agent_id": "agt_Nq3KcAbc"
  }
}

{
  "type": "https://mattermode.com/docs/errors/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limit_exceeded",
  "detail": "Request rate exceeded for this key. Retry after `retry_after` seconds or honor the `Retry-After` header.",
  "doc_url": "https://mattermode.com/docs/guides/errors#rate_limit_exceeded",
  "request_id": "req_Qw9xYz8A",
  "retry_after": 30
}

Separate stakeholder.

Flip Stakeholder.status from active to separating (or directly to separated_to_acquirer when the separation is bundled into an acquihire via acquihire_corporate_transaction_id). The stakeholder remains queryable on the cap table during the separating phase while the downstream cascade — share repurchase, separation agreement, terminal documents — runs.

The separation_kind enum captures the categorisation of the departure and drives downstream acceleration and repurchase mechanics. Defined here on the request body schema (Track A deferred the enum to Wave 3).

Returns 202 Accepted with the updated Stakeholder. Idempotent via Idempotency-Key. Used directly as Phase 1 of the cofounder-departure cookbook and as the per-employee primitive that `POST /v1/corporate_transactions/{id}/transition_employees` invokes per row in an acquihire.

Last updated Jun 14, 2026

Query Parameters

dry_runbooleanOptional

If true, simulate the mutation and return the would-be resource, any cascaded resources, and a fee estimate — without side effects. Available on every mutation.

Default false

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

effective_datestring<date>Required

Effective date of the separation.

Format date

separation_kindstringRequired

One of"voluntary_pre_cliff""voluntary_post_cliff""involuntary""mutual"

reasonstringOptional

Free-form reason recorded on the stakeholder for audit.

acquihire_corporate_transaction_idstringOptional

metadataobjectOptional

Response Body

`application/json`

`application/problem+json`

Request

curl -X POST "https://api.mattermode.com/v1/stakeholders/{id}/separate" \  -H "Content-Type: application/json" \  -d '{    "effective_date": "2026-04-15",    "separation_kind": "voluntary_pre_cliff",    "reason": "negotiated_pre_cliff_exit",    "acquihire_corporate_transaction_id": null  }'

const body = JSON.stringify({  "effective_date": "2026-04-15",  "separation_kind": "voluntary_pre_cliff",  "reason": "negotiated_pre_cliff_exit",  "acquihire_corporate_transaction_id": null})fetch("https://api.mattermode.com/v1/stakeholders/{id}/separate", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

package mainimport (  "fmt"  "net/http"  "io/ioutil"  "strings")func main() {  url := "https://api.mattermode.com/v1/stakeholders/{id}/separate"  body := strings.NewReader(`{    "effective_date": "2026-04-15",    "separation_kind": "voluntary_pre_cliff",    "reason": "negotiated_pre_cliff_exit",    "acquihire_corporate_transaction_id": null  }`)  req, _ := http.NewRequest("POST", url, body)  req.Header.Add("Content-Type", "application/json")  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := ioutil.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}

import requestsheaders = {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",}payload = {    "effective_date": "2026-04-15",    "separation_kind": "voluntary_pre_cliff",    "reason": "negotiated_pre_cliff_exit",    "acquihire_corporate_transaction_id": null}resp = requests.post(    "https://api.mattermode.com/v1/stakeholders/stk_HrG6kLm9/separate",    headers=headers,    json=payload,)resp.raise_for_status()print(resp.json())

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.net.http.HttpRequest.BodyPublishers;var body = BodyPublishers.ofString("""{  "effective_date": "2026-04-15",  "separation_kind": "voluntary_pre_cliff",  "reason": "negotiated_pre_cliff_exit",  "acquihire_corporate_transaction_id": null}""");HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://api.mattermode.com/v1/stakeholders/{id}/separate"))  .header("Content-Type", "application/json")  .POST(body)  .build();try {  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());  System.out.println("Status code: " + response.statusCode());  System.out.println("Response body: " + response.body());} catch (Exception e) {  e.printStackTrace();}

using System;using System.Net.Http;using System.Text;var body = new StringContent("""{  "effective_date": "2026-04-15",  "separation_kind": "voluntary_pre_cliff",  "reason": "negotiated_pre_cliff_exit",  "acquihire_corporate_transaction_id": null}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/stakeholders/{id}/separate", body);var responseBody = await response.Content.ReadAsStringAsync();

curl --request POST 'https://api.mattermode.com/v1/stakeholders/stk_HrG6kLm9/separate' \  --header 'Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc' \  --header 'Matter-Version: 2026-06-10' \  --header 'Idempotency-Key: ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b' \  --header 'Content-Type: application/json' \  --data '{  "effective_date": "2026-04-15",  "separation_kind": "voluntary_pre_cliff",  "reason": "negotiated_pre_cliff_exit",  "acquihire_corporate_transaction_id": null}'

const response = await fetch("https://api.mattermode.com/v1/stakeholders/stk_HrG6kLm9/separate", {  method: "POST",  headers: {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",    "Content-Type": "application/json",  },  body: JSON.stringify({    "effective_date": "2026-04-15",    "separation_kind": "voluntary_pre_cliff",    "reason": "negotiated_pre_cliff_exit",    "acquihire_corporate_transaction_id": null  }),});if (!response.ok) {  throw new Error(`Matter API ${response.status}: ${await response.text()}`);}const data = await response.json();console.log(data);

Response

application/json

{
  "id": "string",
  "object": "stakeholder",
  "entity_id": "string",
  "kind": "natural_person",
  "name": "string",
  "contact": {
    "email": "user@example.com",
    "phone": "string",
    "address": {
      "line1": "string",
      "line2": "string",
      "city": "string",
      "county": "string",
      "region": "string",
      "postal_code": "string",
      "country": "US"
    }
  },
  "tax_id": "string",
  "residency": "st",
  "date_of_birth": "2019-08-24",
  "residential_address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "county": "string",
    "region": "string",
    "postal_code": "string",
    "country": "US"
  },
  "identification": {
    "type": "passport",
    "number": "string",
    "jurisdiction": "US-DE",
    "image_document_id": "string",
    "collected_at": 0
  },
  "boi_eligibility": "ready",
  "boi_missing_fields": [
    "date_of_birth"
  ],
  "beneficial_owner_percentage": 0,
  "voting_percentage": 0,
  "cap_table_percentage": 0,
  "boi_filing_status": "not_required",
  "experience_level": "novice",
  "accredited_investor_status": "unknown",
  "five_percent_holder": false,
  "ip_assignment_scope": "full",
  "consideration_for_initial_shares": null,
  "signed_artifacts": [
    {
      "document_id": "string",
      "type": "string",
      "executed_at": 0,
      "role": "string"
    }
  ],
  "status": "active",
  "roles": [
    {
      "type": "founder",
      "title": "string",
      "start_date": "2019-08-24",
      "end_date": "2019-08-24",
      "resolution_id": "string"
    }
  ],
  "residence_state": "string",
  "marital_status": "single",
  "spouse_id": "string",
  "spouse_name": "string",
  "spouse_tax_id_token": "string",
  "separated_at": "2019-08-24T14:15:22Z",
  "separation_kind": null,
  "separation_reason": "string",
  "transitioned_to_acquirer_id": "string",
  "community_property_state_at_grant": true,
  "metadata": {
    "customer_id": "cus_7Hpx9WxY",
    "portfolio_tag": "y-combinator-w26"
  },
  "created": 0,
  "updated": 0,
  "livemode": true
}

{
  "type": "https://mattermode.com/docs/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "Request body could not be parsed as JSON.",
  "doc_url": "https://mattermode.com/docs/guides/errors#invalid_request",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/authentication_required",
  "title": "Authentication required",
  "status": 401,
  "code": "authentication_required",
  "detail": "No bearer token was supplied. Pass `Authorization: Bearer sk_live_...` on every request.",
  "doc_url": "https://mattermode.com/docs/guides/errors#authentication_required",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No entity with id `ent_Nq3KcAbc` is visible to this token.",
  "doc_url": "https://mattermode.com/docs/guides/errors#not_found",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/invalid_state_transition",
  "title": "Invalid state transition",
  "status": 409,
  "detail": "Entity ent_Nq3KcAbc is in state `dissolved` and cannot be dissolved again.",
  "instance": "/requests/req_Qw9xYz8A",
  "code": "invalid_state_transition",
  "param": "founders[0].equity",
  "doc_url": "https://mattermode.com/docs/guides/errors#invalid_state_transition",
  "request_id": "req_Qw9xYz8A",
  "retry_after": 30,
  "authorized_by": {
    "human_principal_id": "usr_4Kj2m8pQ",
    "agent_id": "agt_Nq3KcAbc"
  }
}

{
  "type": "https://mattermode.com/docs/errors/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limit_exceeded",
  "detail": "Request rate exceeded for this key. Retry after `retry_after` seconds or honor the `Retry-After` header.",
  "doc_url": "https://mattermode.com/docs/guides/errors#rate_limit_exceeded",
  "request_id": "req_Qw9xYz8A",
  "retry_after": 30
}

Separate stakeholder.

Query Parameters

Request Body

Response Body

202application/json

400application/problem+json

401application/problem+json

404application/problem+json

409application/problem+json

429application/problem+json

Separate stakeholder.

Query Parameters

Request Body

Response Body

202application/json

400application/problem+json

401application/problem+json

404application/problem+json

409application/problem+json

429application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`