Open a bank account for the entity

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.

account_typestringRequired

One of"checking""savings"

nicknamestringRequired

Human-readable label for the account on the dashboard.

processorstringOptional

Banking-as-a-service partner. Default column — provisions the account synchronously via Column's REST API. Mercury / Brex / Chase / Ramp dispatch a sub-agent to drive the partner's onboarding portal (returns 202 + SubAgentSession instead of a 201 with the account details).

One of"column""mercury""brex""chase""ramp"

Default "column"

responsible_party_stakeholder_idstringOptional

Stakeholder who serves as the responsible party for KYB. Required for processor: column (Column needs the responsible-party identity to clear KYB). Defaults to the entity's incorporator_stakeholder_id when omitted. Required by Mercury / Brex / Chase / Ramp via the sub-agent flow.

authorized_signer_stakeholder_idsarray<string>Optional

Stakeholders authorized to initiate transfers from this account. Defaults to all officers if omitted.

Response Body

`application/json`

`application/problem+json`

Request

curl -X POST "https://api.mattermode.com/v1/entities/{id}/bank_accounts" \  -H "Content-Type: application/json" \  -d '{    "account_type": "checking",    "nickname": "string"  }'

const body = JSON.stringify({  "account_type": "checking",  "nickname": "string"})fetch("https://api.mattermode.com/v1/entities/{id}/bank_accounts", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

package mainimport (  "fmt"  "net/http"  "io/ioutil"  "strings")func main() {  url := "https://api.mattermode.com/v1/entities/{id}/bank_accounts"  body := strings.NewReader(`{    "account_type": "checking",    "nickname": "string"  }`)  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 = {    "account_type": "checking",    "nickname": "example"}resp = requests.post(    "https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/bank_accounts",    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("""{  "account_type": "checking",  "nickname": "string"}""");HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://api.mattermode.com/v1/entities/{id}/bank_accounts"))  .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("""{  "account_type": "checking",  "nickname": "string"}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/entities/{id}/bank_accounts", body);var responseBody = await response.Content.ReadAsStringAsync();

curl --request POST 'https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/bank_accounts' \  --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 '{  "account_type": "checking",  "nickname": "example"}'

const response = await fetch("https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/bank_accounts", {  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({    "account_type": "checking",    "nickname": "example"  }),});if (!response.ok) {  throw new Error(`Matter API ${response.status}: ${await response.text()}`);}const data = await response.json();console.log(data);

Response

application/json

{
  "object": "bank_account",
  "id": "string",
  "entity_id": "string",
  "status": "pending",
  "account_type": "checking",
  "nickname": "string",
  "balance_usd_cents": 0,
  "provider": "column",
  "account_number": "string",
  "routing_number": "string",
  "account_number_last_4": "string",
  "kyb_decision": "approved",
  "kyb_decided_at": "2019-08-24T14:15:22Z",
  "column_account_id": "string",
  "sub_agent_session_id": "string",
  "partner_bank": "column",
  "authorized_signer_stakeholder_ids": [
    "string"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "activated_at": "2019-08-24T14:15:22Z"
}

{
  "bank_account": {
    "object": "bank_account",
    "id": "string",
    "entity_id": "string",
    "status": "pending",
    "account_type": "checking",
    "nickname": "string",
    "balance_usd_cents": 0,
    "provider": "column",
    "account_number": "string",
    "routing_number": "string",
    "account_number_last_4": "string",
    "kyb_decision": "approved",
    "kyb_decided_at": "2019-08-24T14:15:22Z",
    "column_account_id": "string",
    "sub_agent_session_id": "string",
    "partner_bank": "column",
    "authorized_signer_stakeholder_ids": [
      "string"
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "activated_at": "2019-08-24T14:15:22Z"
  },
  "sub_agent_session": {
    "id": "string",
    "object": "sub_agent_session",
    "status": "pending",
    "target_resource": {
      "kind": "filing",
      "id": "string"
    },
    "agent_kind": "de_sos_filer",
    "target_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
    "started_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "outcome": {
      "confirmation_number": "string",
      "receipt_document_id": "string",
      "error_kind": "string",
      "error_detail": "string"
    },
    "actions_taken": [
      {
        "at": "2019-08-24T14:15:22Z",
        "step": "string",
        "detail": "string"
      }
    ],
    "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"
}

{
  "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://errors.mattermode.com/terms_acceptance_required",
  "terms_version": "string",
  "terms_summary": "string",
  "terms_url": "http://example.com"
}

{
  "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
}

Cascade

A single call kicks off: {"kind":"document","type":"kyb_application","timing":"immediate"} → {"kind":"document","type":"bank_account_authorisation_resolution","timing":"immediate"} → {"kind":"ledger_entry","type":"bank_account_opened","timing":"deferred","qualifier":"on_kyb_clearance"}

Open a business bank accountEnd-to-end recipe walking from KYB through funded account.Form a companyDay-0 formation packet includes the bank-account application under one Idempotency-Key.

Create a bank account.

Open a corporate bank account for the entity. Default rail is Column — Matter's banking-as-a-service partner. Column provisions the account synchronously via its REST API; the 201 response carries the active account_number, routing_number, and KYB decision in the same call.

Override processor to Mercury / Brex / Chase / Ramp to use a partner that requires web-based onboarding. Those providers dispatch a sub-agent (see initiateBankAccountOpening for the equivalent direct entry point); the response shape is 202 + SubAgentSession instead of 201 + BankAccount, and the account details land later via the bank_account.opened webhook.

For Day-0 formation, prefer createFormationPacket.include_bank_account_application — it bundles bank-account opening into the formation packet under a single Idempotency-Key. Use createBankAccount standalone when adding a second account or opening for an entity that was formed elsewhere.

Matter pre-fills the partner bank's KYB requirements from the entity's existing data — formation packet (cert of inc, EIN), registered agent, beneficial-owner Stakeholders, and tax profile — so the founder doesn't re-key information already on file. Requires beneficial-owner Stakeholders to be on file; returns 409 missing_prerequisite if any required stakeholder evidence is missing.

Errors: 400, 401, 409, 429. See errors for the RFC 7807 envelope.

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.

account_typestringRequired

One of"checking""savings"

nicknamestringRequired

Human-readable label for the account on the dashboard.

processorstringOptional

One of"column""mercury""brex""chase""ramp"

Default "column"

responsible_party_stakeholder_idstringOptional

authorized_signer_stakeholder_idsarray<string>Optional

Stakeholders authorized to initiate transfers from this account. Defaults to all officers if omitted.

Response Body

`application/json`

`application/problem+json`

Request

curl -X POST "https://api.mattermode.com/v1/entities/{id}/bank_accounts" \  -H "Content-Type: application/json" \  -d '{    "account_type": "checking",    "nickname": "string"  }'

const body = JSON.stringify({  "account_type": "checking",  "nickname": "string"})fetch("https://api.mattermode.com/v1/entities/{id}/bank_accounts", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

package mainimport (  "fmt"  "net/http"  "io/ioutil"  "strings")func main() {  url := "https://api.mattermode.com/v1/entities/{id}/bank_accounts"  body := strings.NewReader(`{    "account_type": "checking",    "nickname": "string"  }`)  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 = {    "account_type": "checking",    "nickname": "example"}resp = requests.post(    "https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/bank_accounts",    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("""{  "account_type": "checking",  "nickname": "string"}""");HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://api.mattermode.com/v1/entities/{id}/bank_accounts"))  .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("""{  "account_type": "checking",  "nickname": "string"}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/entities/{id}/bank_accounts", body);var responseBody = await response.Content.ReadAsStringAsync();

curl --request POST 'https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/bank_accounts' \  --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 '{  "account_type": "checking",  "nickname": "example"}'

const response = await fetch("https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/bank_accounts", {  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({    "account_type": "checking",    "nickname": "example"  }),});if (!response.ok) {  throw new Error(`Matter API ${response.status}: ${await response.text()}`);}const data = await response.json();console.log(data);

Response

application/json

{
  "object": "bank_account",
  "id": "string",
  "entity_id": "string",
  "status": "pending",
  "account_type": "checking",
  "nickname": "string",
  "balance_usd_cents": 0,
  "provider": "column",
  "account_number": "string",
  "routing_number": "string",
  "account_number_last_4": "string",
  "kyb_decision": "approved",
  "kyb_decided_at": "2019-08-24T14:15:22Z",
  "column_account_id": "string",
  "sub_agent_session_id": "string",
  "partner_bank": "column",
  "authorized_signer_stakeholder_ids": [
    "string"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "activated_at": "2019-08-24T14:15:22Z"
}

{
  "bank_account": {
    "object": "bank_account",
    "id": "string",
    "entity_id": "string",
    "status": "pending",
    "account_type": "checking",
    "nickname": "string",
    "balance_usd_cents": 0,
    "provider": "column",
    "account_number": "string",
    "routing_number": "string",
    "account_number_last_4": "string",
    "kyb_decision": "approved",
    "kyb_decided_at": "2019-08-24T14:15:22Z",
    "column_account_id": "string",
    "sub_agent_session_id": "string",
    "partner_bank": "column",
    "authorized_signer_stakeholder_ids": [
      "string"
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "activated_at": "2019-08-24T14:15:22Z"
  },
  "sub_agent_session": {
    "id": "string",
    "object": "sub_agent_session",
    "status": "pending",
    "target_resource": {
      "kind": "filing",
      "id": "string"
    },
    "agent_kind": "de_sos_filer",
    "target_url": "http://example.com",
    "created_at": "2019-08-24T14:15:22Z",
    "started_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "outcome": {
      "confirmation_number": "string",
      "receipt_document_id": "string",
      "error_kind": "string",
      "error_detail": "string"
    },
    "actions_taken": [
      {
        "at": "2019-08-24T14:15:22Z",
        "step": "string",
        "detail": "string"
      }
    ],
    "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"
}

{
  "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://errors.mattermode.com/terms_acceptance_required",
  "terms_version": "string",
  "terms_summary": "string",
  "terms_url": "http://example.com"
}

{
  "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
}

Cascade

Open a business bank accountEnd-to-end recipe walking from KYB through funded account.Form a companyDay-0 formation packet includes the bank-account application under one Idempotency-Key.

Create a bank account.

201application/json

202application/json

400application/problem+json

401application/problem+json

409application/problem+json

429application/problem+json

Create a bank account.

201application/json

202application/json

400application/problem+json

401application/problem+json

409application/problem+json

429application/problem+json

`application/json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`