--- title: Create subledger slug: apis/accounts/subledgers-apis/create-a-subledger description: Create a subledger for a master account via POST /core/v1/dda/subaccounts, specifying customer ID, title, and beneficiary details. icon: {"apiMethod":"POST"} docTags: createdAt: 2025-05-07T05:59:41.846Z --- ## Relevant webhooks For this endpoint be sure you have [registered](docId\:BN5XtgkJogBe-CtwomCbS) for these webhooks: - [Core.SubAccount.Opened](docId\:eAs8aFqW7M97baeZUC8Sr) - [Core.SubAccount.Closed](docId\:eAs8aFqW7M97baeZUC8Sr) ## API reference Creates a subledger for the specified Master Account. :::hint{type="warning"} If you are using the [International Payments remittance](docId:2OOlsywMLwZlqaGtssPcd) feature, you must create a subledger for the account holder with a value of **Personal** for the `classification` attribute. ::: :::ApiMethodV2 ```json { "name": "Endpoint: /core/v1/dda/subaccounts", "method": "POST", "url": " https://sandbox.crbcos.com/core/v1/dda/subaccounts", "description": "", "tab": "examples", "examples": { "languages": [ { "id": "P9idftSfTSKm5GwLRp3lQ", "language": "curl", "code": "curl --location 'https://sandbox.crbcos.com/core/v1/dda/subaccounts' \\\n--header 'Idempotency-key: 3392de17-6e92-4999-b943-cad5f19b1629' \\\n--data '{\n \"masterAccountNumber\": \"2819503463\",\n \"title\": \"Jerry Penn\",\n \"customerId\": \"53c34cf0-4cd2-4768-937b-b30000dffdca\",\n \"classification\": \"Personal\",\n \"beneficiary\": {\n \"firstName\": \"Jerry\" ,\n \"lastName\": \"Penn\",\n \"streetAddress1\": \"12 Main St\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postalCode\": \"10001\",\n \"countryCode\": \"US\"\n }\n}\n\n'", "customLabel": "" }, { "id": "7l7yAI28Rhh_qfcfgcLP4", "language": "nodejs", "code": "var https = require('follow-redirects').https;\nvar fs = require('fs');\n\nvar options = {\n 'method': 'POST',\n 'hostname': 'sandbox.crbcos.com',\n 'path': '/core/v1/dda/subaccounts',\n 'headers': {\n 'Idempotency-key': '3392de17-6e92-4999-b943-cad5f19b1629'\n },\n 'maxRedirects': 20\n};\n\nvar req = https.request(options, function (res) {\n var chunks = [];\n\n res.on(\"data\", function (chunk) {\n chunks.push(chunk);\n });\n\n res.on(\"end\", function (chunk) {\n var body = Buffer.concat(chunks);\n console.log(body.toString());\n });\n\n res.on(\"error\", function (error) {\n console.error(error);\n });\n});\n\nvar postData = \"{\\r\\n \\\"masterAccountNumber\\\": \\\"2819503463\\\",\\r\\n \\\"title\\\": \\\"Jerry Penn\\\",\\r\\n \\\"customerId\\\": \\\"53c34cf0-4cd2-4768-937b-b30000dffdca\\\",\\r\\n \\\"beneficiary\\\": {\\r\\n \\\"firstName\\\": \\\"Jerry\\\" ,\\r\\n \\\"lastName\\\": \\\"Penn\\\",\\r\\n \\\"streetAddress1\\\": \\\"12 Main St\\\",\\r\\n \\\"city\\\": \\\"New York\\\",\\r\\n \\\"state\\\": \\\"NY\\\",\\r\\n \\\"postalCode\\\": \\\"10001\\\",\\r\\n \\\"countryCode\\\": \\\"US\\\"\\r\\n }\\r\\n}\\r\\n\\r\\n\";\n\nreq.write(postData);\n\nreq.end();", "customLabel": "" }, { "id": "YNDuk387y_n1nrdjiZm8u", "language": "python", "code": "import http.client\n\nconn = http.client.HTTPSConnection(\"sandbox.crbcos.com\")\npayload = \"{\\r\\n \\\"masterAccountNumber\\\": \\\"2819503463\\\",\\r\\n \\\"title\\\": \\\"Jerry Penn\\\",\\r\\n \\\"customerId\\\": \\\"53c34cf0-4cd2-4768-937b-b30000dffdca\\\",\\r\\n \\\"beneficiary\\\": {\\r\\n \\\"firstName\\\": \\\"Jerry\\\" ,\\r\\n \\\"lastName\\\": \\\"Penn\\\",\\r\\n \\\"streetAddress1\\\": \\\"12 Main St\\\",\\r\\n \\\"city\\\": \\\"New York\\\",\\r\\n \\\"state\\\": \\\"NY\\\",\\r\\n \\\"postalCode\\\": \\\"10001\\\",\\r\\n \\\"countryCode\\\": \\\"US\\\"\\r\\n }\\r\\n}\\r\\n\\r\\n\"\nheaders = {\n 'Idempotency-key': '3392de17-6e92-4999-b943-cad5f19b1629'\n}\nconn.request(\"POST\", \"/core/v1/dda/subaccounts\", payload, headers)\nres = conn.getresponse()\ndata = res.read()\nprint(data.decode(\"utf-8\"))", "customLabel": "" }, { "id": "x-xbtFBHeYWkwytMqG-oM", "language": "ruby", "code": "require \"uri\"\nrequire \"net/http\"\n\nurl = URI(\"https://sandbox.crbcos.com/core/v1/dda/subaccounts\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"Idempotency-key\"] = \"3392de17-6e92-4999-b943-cad5f19b1629\"\nrequest.body = \"{\\r\\n \\\"masterAccountNumber\\\": \\\"2819503463\\\",\\r\\n \\\"title\\\": \\\"Jerry Penn\\\",\\r\\n \\\"customerId\\\": \\\"53c34cf0-4cd2-4768-937b-b30000dffdca\\\",\\r\\n \\\"beneficiary\\\": {\\r\\n \\\"firstName\\\": \\\"Jerry\\\" ,\\r\\n \\\"lastName\\\": \\\"Penn\\\",\\r\\n \\\"streetAddress1\\\": \\\"12 Main St\\\",\\r\\n \\\"city\\\": \\\"New York\\\",\\r\\n \\\"state\\\": \\\"NY\\\",\\r\\n \\\"postalCode\\\": \\\"10001\\\",\\r\\n \\\"countryCode\\\": \\\"US\\\"\\r\\n }\\r\\n}\\r\\n\\r\\n\"\n\nresponse = https.request(request)\nputs response.read_body\n", "customLabel": "" }, { "id": "YIsGdL1o4H5xd4F1Me99Y", "language": "go", "code": "package main\n\nimport (\n \"fmt\"\n \"strings\"\n \"net/http\"\n \"io\"\n)\n\nfunc main() {\n\n url := \"https://sandbox.crbcos.com/core/v1/dda/subaccounts\"\n method := \"POST\"\n\n payload := strings.NewReader(`{`+\"\n\"+`\n \"masterAccountNumber\": \"2819503463\",`+\"\n\"+`\n \"title\": \"Jerry Penn\",`+\"\n\"+`\n \"customerId\": \"53c34cf0-4cd2-4768-937b-b30000dffdca\",`+\"\n\"+`\n \"beneficiary\": {`+\"\n\"+`\n \"firstName\": \"Jerry\" ,`+\"\n\"+`\n \"lastName\": \"Penn\",`+\"\n\"+`\n \"streetAddress1\": \"12 Main St\",`+\"\n\"+`\n \"city\": \"New York\",`+\"\n\"+`\n \"state\": \"NY\",`+\"\n\"+`\n \"postalCode\": \"10001\",`+\"\n\"+`\n \"countryCode\": \"US\"`+\"\n\"+`\n }`+\"\n\"+`\n}`+\"\n\"+`\n`+\"\n\"+`\n`)\n\n client := &http.Client {\n }\n req, err := http.NewRequest(method, url, payload)\n\n if err != nil {\n fmt.Println(err)\n return\n }\n req.Header.Add(\"Idempotency-key\", \"3392de17-6e92-4999-b943-cad5f19b1629\")\n\n res, err := client.Do(req)\n if err != nil {\n fmt.Println(err)\n return\n }\n defer res.Body.Close()\n\n body, err := io.ReadAll(res.Body)\n if err != nil {\n fmt.Println(err)\n return\n }\n fmt.Println(string(body))\n}", "customLabel": "" } ], "selectedLanguageId": "P9idftSfTSKm5GwLRp3lQ" }, "results": { "languages": [ { "id": "vjutubmVyYLoLEjt5Wkle", "language": "200", "code": "{\n \"accountNumber\": \"302022615264\",\n \"accountType\": \"Deposit\",\n \"status\": \"Active\",\n \"ledgerType\": \"Passthrough\",\n \"productType\": \"Checking\",\n \"title\": \"Jerry Penn\",\n \"currentBalance\": 0,\n \"availableBalance\": 0,\n \"holdAmount\": 0,\n \"transactionCount\": 0,\n \"creditLimit\": 0,\n \"currency\": \"usd\",\n \"openedAt\": \"2025-06-24T03:05:04.7952946-04:00\",\n \"masterAccountNumber\": \"2819503463\",\n \"customerId\": \"53c34cf0-4cd2-4768-937b-b30000dffdca\",\n \"classification\": \"Personal\",\n \"beneficiary\": {\n \"firstName\": \"Jerry\",\n \"lastName\": \"Penn\",\n \"streetAddress1\": \"12 Main St\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postalCode\": \"10001\",\n \"countryCode\": \"US\"\n },\n \"partnerId\": \"cd9c12f4-7691-424a-b38b-af5b0134c611\",\n \"lastMaintenanceAt\": \"2025-06-24T03:05:04.7952946-04:00\",\n \"productId\": \"83bed086-8182-4151-a1e3-af5b01362783\",\n \"lastModifiedAt\": \"2025-06-24T03:05:04.8043224-04:00\"\n}", "customLabel": "" }, { "id": "PHTrfKPkW8FXNnMnFraRX", "language": "400", "code": "{\n \"errors\": [\n {\n \"code\": 2110,\n \"message\": \"Beneficiary required\"\n }\n ]\n}20", "customLabel": "" } ], "selectedLanguageId": "vjutubmVyYLoLEjt5Wkle" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [], "bodyDataParameters": [ { "name": "masterAccountNumber", "kind": "required", "type": "string", "description": "Master account to open the subledger under" }, { "name": "title", "kind": "required", "type": "string", "description": "The name on the account. Usually this is the account holder name, but not always.\n255 characters maximum.", "": "The name on the account. Usually this is the account holder name, but not always.\n255 characters maximum." }, { "name": "customerId", "kind": "optional", "type": "string", "description": "The unique ID assigned to a customer when the customer record is created. You need this ID to take action for a specific customer. For example, when opening an account or adding an address to a customer record. \nThe ID is in GUID format.", "": "The unique ID assigned to a customer when the customer record is created. You need this ID to take action for a specific customer. For example, when opening an account or adding an address to a customer record. \nThe ID is in GUID format." }, { "name": "classification", "kind": "optional", "type": "string", "description": "Can be one of two types of beneficiaries:\n- Personal\n- Business", "": "Can be one of two types of beneficiaries:\n- Personal\n- Business" }, { "name": "beneficiary", "kind": "optional", "type": "Object", "description": "Beneficiary profile for this subledger\nAlways omit accent marks. \nUse ^[A-Za-z0-9^ !_-@'`\\t()#\"\"\"\"*]+{}|~$%&,:.-\\]+$ as the regex for this object.", "children": [ { "name": "referenceId", "kind": "optional", "type": "string", "description": "Your organization's reference identifier for the beneficiary of this subaccount. 50 character limit." }, { "name": "firstName", "kind": "optional", "type": "string", "description": "For a personal beneficiary, the person's legal first name. 50 character limit." }, { "name": "middleName", "kind": "optional", "type": "string", "description": "For a personal beneficiary, the person's legal middle name. 50 character limit." }, { "name": "lastName", "kind": "optional", "type": "string", "description": "For a personal beneficiary, the person's legal last name. 50 character limit." }, { "name": "entityName", "kind": "optional", "type": "string", "description": "If the beneficiary is a business or organization enter its name. 255 character limit." }, { "name": "streetAddress1", "kind": "optional", "type": "string", "description": "Primary location details of account holder, for instance, street name, house/building number, PO box" }, { "name": "streetAddress2", "kind": "optional", "type": "string", "description": "Additional address information" }, { "name": "city", "kind": "optional", "type": "string", "description": "City full name" }, { "name": "state", "kind": "optional", "type": "string", "description": "State name. We recommend you enter the 2-character state code." }, { "name": "postalCode", "kind": "optional", "type": "string", "description": "Postal code, also known as ZIP code" }, { "name": "countryCode", "kind": "optional", "type": "string", "description": "2-letter ISO country code" }, { "name": "phoneNumber", "kind": "optional", "type": "string", "description": "Beneficiary phone number" }, { "name": "emailAddress", "kind": "optional", "type": "string", "description": "Beneficiary email address. 255 character limit." }, { "name": "notes", "kind": "optional", "type": "string", "description": "General notes about the beneficiary" }, { "name": "taxIdType", "kind": "optional", "type": "string", "description": "Tax ID type for the beneficiary:\n- Ssn (Social security number)\n- Ein (Employer identification number)\n- Itin (Individual tax ID number)\n- Vat (International VAT number)\n- Foreign (non-US domestic)" }, { "name": "taxId", "kind": "optional", "type": "string", "description": "Beneficiary tax ID number. 9 character minimum for SSN, EIN, or ITIN; 5 character minimum for VAT or Foreign. 20 character maximum." }, { "name": "birthDate", "kind": "optional", "type": "string", "description": "For a personal beneficiary, the person's birthdate, in the format YYYY-MM-DD" }, { "name": "dateFormed", "kind": "optional", "type": "string", "description": "For a business beneficiary, the date the business was formed, in the format YYYY-MM-DD" } ], "schema": [ { "name": "referenceId", "kind": "optional", "type": "string", "description": "Your organization's reference identifier for the beneficiary of this subaccount. 50 character limit." }, { "name": "firstName", "kind": "optional", "type": "string", "description": "For a personal beneficiary, the person's legal first name. 50 character limit." }, { "name": "middleName", "kind": "optional", "type": "string", "description": "For a personal beneficiary, the person's legal middle name. 50 character limit." }, { "name": "lastName", "kind": "optional", "type": "string", "description": "For a personal beneficiary, the person's legal last name. 50 character limit." }, { "name": "entityName", "kind": "optional", "type": "string", "description": "If the beneficiary is a business or organization enter its name. 255 character limit." }, { "name": "streetAddress1", "kind": "optional", "type": "string", "description": "Primary location details of account holder, for instance, street name, house/building number, PO box" }, { "name": "streetAddress2", "kind": "optional", "type": "string", "description": "Additional address information" }, { "name": "city", "kind": "optional", "type": "string", "description": "City full name" }, { "name": "state", "kind": "optional", "type": "string", "description": "State name. We recommend you enter the 2-character state code." }, { "name": "postalCode", "kind": "optional", "type": "string", "description": "Postal code, also known as ZIP code" }, { "name": "countryCode", "kind": "optional", "type": "string", "description": "2-letter ISO country code" }, { "name": "phoneNumber", "kind": "optional", "type": "string", "description": "Beneficiary phone number" }, { "name": "emailAddress", "kind": "optional", "type": "string", "description": "Beneficiary email address. 255 character limit." }, { "name": "notes", "kind": "optional", "type": "string", "description": "General notes about the beneficiary" }, { "name": "taxIdType", "kind": "optional", "type": "string", "description": "Tax ID type for the beneficiary:\n- Ssn (Social security number)\n- Ein (Employer identification number)\n- Itin (Individual tax ID number)\n- Vat (International VAT number)\n- Foreign (non-US domestic)" }, { "name": "taxId", "kind": "optional", "type": "string", "description": "Beneficiary tax ID number. 9 character minimum for SSN, EIN, or ITIN; 5 character minimum for VAT or Foreign. 20 character maximum." }, { "name": "birthDate", "kind": "optional", "type": "string", "description": "For a personal beneficiary, the person's birthdate, in the format YYYY-MM-DD" }, { "name": "dateFormed", "kind": "optional", "type": "string", "description": "For a business beneficiary, the date the business was formed, in the format YYYY-MM-DD" } ], "": "Beneficiary profile for this subledger\nAlways omit accent marks. \nUse ^[A-Za-z0-9^ !_-@'`\\t()#\"\"\"\"*]+{}|~$%&,:.-\\]+$ as the regex for this object." }, { "name": "clientIdentifier", "kind": "optional", "type": "string", "description": "Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.", "children": [] } ], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "response": [ { "name": "accountNumber", "kind": "optional", "type": "string", "description": "The subledger account number" }, { "name": "accountType", "kind": "optional", "type": "string", "description": "Deposit account type:\n- GeneralLedger\n- Deposit\n- CreditCard\n- StoredValue\n- Wallet\n- Unknown", "children": [] }, { "name": "status", "kind": "optional", "type": "string", "description": "Subledger account status:\n- Closed\n- Active", "children": [] }, { "name": "ledgerType", "kind": "optional", "type": "string", "description": "The subledger type:\n- Passthrough\n- Direct", "children": [] }, { "name": "productType", "kind": "optional", "type": "string", "description": "One of:\n- GeneralLedger\n- Checking\n- Savings\n- TimeDeposit\n- MoneyMarket\n- CreditCard\n- StoredValue\n- Wallet\n- Unknown", "children": [] }, { "name": "title", "kind": "optional", "type": "string", "description": "The name on the account. Usually this is the account holder name, but not always.", "children": [] }, { "name": "currentBalance", "kind": "optional", "type": "Integer", "description": "Current balance. A negative amount means a debit and a positive amount means a credit.", "children": [] }, { "name": "availableBalance", "kind": "optional", "type": "Integer", "description": "Available amount of the balance. A negative amount means a debit and a positive amount means a credit.", "children": [] }, { "name": "holdAmount", "kind": "optional", "type": "Integer", "description": "Amount of the hold (if any) placed on the account", "children": [] }, { "name": "transactionCount", "kind": "optional", "type": "Integer", "description": "Total number of transactions posted to the account", "children": [] }, { "name": "creditLimit", "kind": "optional", "type": "integer", "description": "Credit limit of the account customer", "children": [] }, { "name": "currency", "kind": "optional", "type": "string", "description": "Currency held in the account", "children": [] }, { "name": "openedAt", "kind": "optional", "type": "string", "description": "Date and time the deposit account was opened. The date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]", "children": [] }, { "name": "closedAt", "kind": "optional", "type": "string", "description": "The date and time that the account was closed. The date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm].", "children": [] }, { "name": "masterAccountNumber", "kind": "optional", "type": "string", "description": "Master account the subledger was opened under", "children": [] }, { "name": "customerId", "kind": "optional", "type": "string", "description": "The unique ID assigned to a customer when the customer record is created. You need this ID to take action for a specific customer. For example, when opening an account or adding an address to a customer record.", "children": [] }, { "name": "classification", "kind": "optional", "type": "string", "description": "Can be one of two types of beneficiaries:\n- Personal\n- Business", "children": [] }, { "name": "beneficiary", "kind": "optional", "type": "Object", "description": "Beneficiary profile for this subledger", "children": [ { "name": "referenceId", "kind": "optional", "type": "string", "description": "Your organization's reference identifier for the beneficiary of this subaccount" }, { "name": "firstName", "kind": "optional", "type": "string", "description": "The first name of the beneficiary" }, { "name": "middleName", "kind": "optional", "type": "string", "description": "The middle name of the beneficiary" }, { "name": "lastName", "kind": "optional", "type": "string", "description": "The last name of the beneficiary" }, { "name": "entityName", "kind": "optional", "type": "string", "description": "If the beneficiary is a business or organization enter its name. If the beneficiary is an individual enter their full name." }, { "name": "streetAddress1", "kind": "optional", "type": "string", "description": "Primary location details of account holder, for instance, street name, house/building number, PO box" }, { "name": "streetAddress2", "kind": "optional", "type": "string", "description": "Additional address information" }, { "name": "city", "kind": "optional", "type": "string", "description": "City full name" }, { "name": "state", "kind": "optional", "type": "string", "description": "State name" }, { "name": "postalCode", "kind": "optional", "type": "string", "description": "Postal code, also known as ZIP code" }, { "name": "countryCode", "kind": "optional", "type": "string", "description": "2-letter ISO country code" }, { "name": "phoneNumber", "kind": "optional", "type": "string", "description": "Beneficiary phone number" }, { "name": "emailAddress", "kind": "optional", "type": "string", "description": "Beneficiary email address" }, { "name": "notes", "kind": "optional", "type": "string", "description": "General notes about the beneficiary" }, { "name": "taxIdType", "kind": "optional", "type": "string", "description": "Tax ID type for the beneficiary:\n- Ssn (Social security number)\n- Ein (Employer identification number)\n- Itin (Individual tax ID number)\n- Vat (International VAT number)\n- Foreign (non-US domestic)" }, { "name": "taxId", "kind": "optional", "type": "string", "description": "Beneficiary tax ID number" }, { "name": "birthDate", "kind": "optional", "type": "string", "description": "Beneficiary birthdate" }, { "name": "dateFormed", "kind": "optional", "type": "string", "description": "Date the subledger was formed" } ] }, { "name": "partnerId", "kind": "optional", "type": "string", "description": "Your unique ID in the Cross River system. This ID is in GUID format.", "children": [] }, { "name": "lastMaintenanceAt", "kind": "optional", "type": "string", "description": "Date and time the deposit account last had maintenance performed on it. The date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]", "children": [] }, { "name": "lastTransactedAt", "kind": "optional", "type": "string", "description": "The date and time a transaction last took place on the account. The date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]", "children": [] }, { "name": "productId", "kind": "optional", "type": "string", "description": "ID in GUID format of your specific product type on which the account is based. Provided by Cross River.", "children": [] }, { "name": "clientIdentifier", "kind": "optional", "type": "string", "description": "Your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.", "children": [] }, { "name": "lastModifiedAt", "kind": "optional", "type": "string", "description": "Internal Cross River value. Date and time the database entry was last modified.", "children": [] }, { "name": "balances", "kind": "optional", "type": "object", "description": "There can be multiple account balances listed", "children": [ { "name": "accountNumber", "kind": "optional", "type": "string", "description": "Number of the account this information describes" }, { "name": "isSubAccount", "kind": "optional", "type": "boolean", "description": "If the account balance presented is for a subledger, true. Otherwise false." }, { "name": "currency", "kind": "optional", "type": "string", "description": "Currency held in the account" }, { "name": "currentBalance", "kind": "optional", "type": "integer", "description": "Balance including all transactions even if they have not yet settled" }, { "name": "availableBalance", "kind": "optional", "type": "integer", "description": "Balance available to the account holder" }, { "name": "holdAmount", "kind": "optional", "type": "integer", "description": "Amount of funds that cannot yet be accessed because the funds are on hold" }, { "name": "transactionCount", "kind": "optional", "type": "integer", "description": "Number of transactions in the last period" }, { "name": "lastModifiedAt", "kind": "optional", "type": "string", "description": "Internal Cross River value. Date and time the database entry was last modified. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]" }, { "name": "lastTransactedAt", "kind": "optional", "type": "string", "description": "The date and time a transaction last took place on the account. The date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]" } ] } ], "hasTryItOut": false, "autoGeneratedAnchorSlug": "endpoint-corev1ddasubaccounts", "legacyHash": "09rMP5ADyee998Z5jeC6h" } ``` :::