> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.mercoa.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mercoa.com/_mcp/server. # Create Bulk Entities (Sync) POST https://api.mercoa.com/entities Content-Type: application/json Create multiple entities in bulk. This endpoint will process synchronously and return a list of entities that were created or failed to create. Reference: https://docs.mercoa.com/embedded-ap-ar/api-reference/entity/bulk/create ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Query parameters - `emitWebhooks` (boolean, optional, default: false) — If true, webhooks will be emitted for each entity that is created. By default, webhooks are not emitted. ### Body (application/json) This endpoint expects an object. - `object` - Bulk Entity Creation from Object - `entities` (list of object, required) - `isCustomer` (boolean, required) — If this entity has a direct relationship with your organization (e.g your direct customer or client), set this to true. Otherwise, set to false (e.g your customer's vendors). - `accountType` (enum, required) - Allowed values: `business`, `individual` - `profile` (object, required) - `business` (object, optional) — If this entity is a business, set this field - `legalBusinessName` (string, required) - `email` (string, optional) — Email address for the business. Required for KYB. - `businessType` (enum, optional) - Allowed values: `soleProprietorship`, `unincorporatedAssociation`, `trust`, `publicCorporation`, `privateCorporation`, `llc`, `partnership`, `unincorporatedNonProfit`, `incorporatedNonProfit` - `phone` (object, optional) — Phone number for the business. Required for KYB. - `countryCode` (string, required) - `number` (string, required) - `doingBusinessAs` (string, optional) - `website` (string, optional) — Website URL for the business. Must be in the format http://www.example.com. Required for KYB if description is not provided. - `description` (string, optional) — Description of the business. Required for KYB if website is not provided. - `address` (object, optional) — Address for the business. Required for KYB. - `addressLine1` (string, required) - `city` (string, required) - `stateOrProvince` (string, required) — State or province code. Must be in the format XX. - `postalCode` (string, required) — Postal code. Must be in the format XXXXX or XXXXX-XXXX. - `addressLine2` (string, optional) - `country` (string, optional) - `taxId` (object, optional) — Tax ID for the business. Currently only EIN is supported. Required for KYB. - `ein` (object, required) - `formationDate` (datetime, optional) — Date of business formation - `industryCodes` (object, optional) — Industry code for the business. Required to collect funds. - `mcc` (string, optional) - `averageMonthlyTransactionVolume` (double, optional) — Average monthly transaction volume for the business. Required to collect funds. - `averageTransactionSize` (double, optional) — Average transaction size for the business. Required to collect funds. - `maxTransactionSize` (double, optional) — Maximum transaction size for the business. Required to collect funds. - `individual` (object, optional) — If this entity is a individual, set this field - `name` (object, required) - `firstName` (string, required) - `lastName` (string, required) - `middleName` (string, optional) - `suffix` (string, optional) - `email` (string, optional) - `phone` (object, optional) - `countryCode` (string, required) - `number` (string, required) - `address` (object, optional) - `addressLine1` (string, required) - `city` (string, required) - `stateOrProvince` (string, required) — State or province code. Must be in the format XX. - `postalCode` (string, required) — Postal code. Must be in the format XXXXX or XXXXX-XXXX. - `addressLine2` (string, optional) - `country` (string, optional) - `birthDate` (object, optional) - `day` (string, optional) - `month` (string, optional) - `year` (string, optional) - `governmentID` (object, optional) - `ssn` (string, required) — Full Social Security Number. Must be in the format 123-45-6789. - `isPayor` (boolean, required) — If this entity will be paying invoices, set this to true. - `isPayee` (boolean, required) — If this entity will be receiving payments, set this to true. - `foreignId` (string, optional) — The ID used to identify this entity in your system. This ID must be unique across all entities in your system. - `emailTo` (string, optional) — Sets the email address to which to send invoices to be added to the Invoice Inbox. Only provide the local-part/username of the email address, do not include the @domain.com - `emailToAlias` (list of string, optional) — Email inbox alias addresses. Used when forwarding emails to the emailTo address from an alias. Include the full email address. - `isNetworkPayor` (boolean, optional) — Control if this entity should be available as a payor to any entity on your platform. If set to false, this entity will only be available as a payor to entities that have a direct relationship with this entity. Defaults to false. - `isNetworkPayee` (boolean, optional) — Control if this entity should be available as a payee to any entity on your platform. If set to false, this entity will only be available as a payee to entities that have a direct relationship with this entity. Defaults to false. - `logo` (string, optional) — Base64 data URL of the entity logo. Must be in the `data:image/*;base64,XXXX` format. We recommend a PNG image under 100KB. Supported file types are `png`, `jpeg`, `gif`, `svg`. - `metadata` (map from string to string, optional) — Simple key/value metadata associated with this entity. For more complex metadata, use the Metadata API. - `connectedEntity` (object, optional) - `id` (string, required) — The ID of the entity to connect to. - `linkCreatedAsPayor` (boolean, required) — If true, the created entities will be linked to the connected entity as a payor (customer). - `linkCreatedAsPayee` (boolean, required) — If true, the created entities will be linked to the connected entity as a payee (vendor). ## Response ### 200 - `data` (list of object, required) - `id` (string, optional) — The ID of the entity that was created. If the entity was not created, this will be undefined - `foreignId` (string, optional) — If provided, this is the foreign ID of the entity that was created. - `error` (string, optional) — The error message if the entity was not created ## Errors ### 400 Bad Request - `errorName` ("BadRequest", required) - `content` (string, required) ### 401 Unauthorized - `errorName` ("Unauthorized", required) - `content` (string, required) ### 403 Forbidden - `errorName` ("Forbidden", required) - `content` (string, required) ### 404 Not Found - `errorName` ("NotFound", required) - `content` (string, required) ### 409 Conflict - `errorName` ("Conflict", required) - `content` (string, required) ### 500 Internal Server Error - `errorName` ("InternalServerError", required) - `content` (string, required) ### 501 Unimplemented - `errorName` ("Unimplemented", required) - `content` (string, required) ## Examples **Request** ```json { "connectedEntity": { "id": "ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced", "linkCreatedAsPayor": false, "linkCreatedAsPayee": true }, "entities": [ { "isCustomer": true, "isPayor": true, "isPayee": false, "accountType": "business", "foreignId": "MY-DB-ID-12345", "profile": { "business": { "email": "customer@acme.com", "legalBusinessName": "Acme Inc.", "website": "http://www.acme.com", "businessType": "llc", "phone": { "countryCode": "1", "number": "4155551234" }, "address": { "addressLine1": "123 Main St", "addressLine2": "Unit 1", "city": "San Francisco", "stateOrProvince": "CA", "postalCode": "94105", "country": "US" }, "taxId": { "ein": { "number": "12-3456789" } } } } } ] } ``` **Response** ```json { "data": [ { "id": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d", "foreignId": "YOUR-ENTITY-ID" }, { "foreignId": "YOUR-SECOND-ENTITY-ID", "error": "Entity creation failed" } ] } ``` **SDK Code** ```python FromObjects import requests url = "https://api.mercoa.com/entities" payload = { "connectedEntity": { "id": "ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced", "linkCreatedAsPayor": False, "linkCreatedAsPayee": True }, "entities": [ { "isCustomer": True, "isPayor": True, "isPayee": False, "accountType": "business", "foreignId": "MY-DB-ID-12345", "profile": { "business": { "email": "customer@acme.com", "legalBusinessName": "Acme Inc.", "website": "http://www.acme.com", "businessType": "llc", "phone": { "countryCode": "1", "number": "4155551234" }, "address": { "addressLine1": "123 Main St", "addressLine2": "Unit 1", "city": "San Francisco", "stateOrProvince": "CA", "postalCode": "94105", "country": "US" }, "taxId": { "ein": { "number": "12-3456789" } } } } } ] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```typescript FromObjects import { MercoaClient } from "@mercoa/javascript"; const client = new MercoaClient({ token: "YOUR_TOKEN" }); await client.entity.bulk.create({ body: { connectedEntity: { id: "ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced", linkCreatedAsPayor: false, linkCreatedAsPayee: true }, entities: [{ isCustomer: true, isPayor: true, isPayee: false, accountType: "business", foreignId: "MY-DB-ID-12345", profile: { business: { email: "customer@acme.com", legalBusinessName: "Acme Inc.", website: "http://www.acme.com", businessType: "llc", phone: { countryCode: "1", number: "4155551234" }, address: { addressLine1: "123 Main St", addressLine2: "Unit 1", city: "San Francisco", stateOrProvince: "CA", postalCode: "94105", country: "US" }, taxId: { ein: { number: "12-3456789" } } } } }] } }); ``` ```go FromObjects package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.mercoa.com/entities" payload := strings.NewReader("{\n \"connectedEntity\": {\n \"id\": \"ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced\",\n \"linkCreatedAsPayor\": false,\n \"linkCreatedAsPayee\": true\n },\n \"entities\": [\n {\n \"isCustomer\": true,\n \"isPayor\": true,\n \"isPayee\": false,\n \"accountType\": \"business\",\n \"foreignId\": \"MY-DB-ID-12345\",\n \"profile\": {\n \"business\": {\n \"email\": \"customer@acme.com\",\n \"legalBusinessName\": \"Acme Inc.\",\n \"website\": \"http://www.acme.com\",\n \"businessType\": \"llc\",\n \"phone\": {\n \"countryCode\": \"1\",\n \"number\": \"4155551234\"\n },\n \"address\": {\n \"addressLine1\": \"123 Main St\",\n \"addressLine2\": \"Unit 1\",\n \"city\": \"San Francisco\",\n \"stateOrProvince\": \"CA\",\n \"postalCode\": \"94105\",\n \"country\": \"US\"\n },\n \"taxId\": {\n \"ein\": {\n \"number\": \"12-3456789\"\n }\n }\n }\n }\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby FromObjects require 'uri' require 'net/http' url = URI("https://api.mercoa.com/entities") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"connectedEntity\": {\n \"id\": \"ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced\",\n \"linkCreatedAsPayor\": false,\n \"linkCreatedAsPayee\": true\n },\n \"entities\": [\n {\n \"isCustomer\": true,\n \"isPayor\": true,\n \"isPayee\": false,\n \"accountType\": \"business\",\n \"foreignId\": \"MY-DB-ID-12345\",\n \"profile\": {\n \"business\": {\n \"email\": \"customer@acme.com\",\n \"legalBusinessName\": \"Acme Inc.\",\n \"website\": \"http://www.acme.com\",\n \"businessType\": \"llc\",\n \"phone\": {\n \"countryCode\": \"1\",\n \"number\": \"4155551234\"\n },\n \"address\": {\n \"addressLine1\": \"123 Main St\",\n \"addressLine2\": \"Unit 1\",\n \"city\": \"San Francisco\",\n \"stateOrProvince\": \"CA\",\n \"postalCode\": \"94105\",\n \"country\": \"US\"\n },\n \"taxId\": {\n \"ein\": {\n \"number\": \"12-3456789\"\n }\n }\n }\n }\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java FromObjects import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.mercoa.com/entities") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"connectedEntity\": {\n \"id\": \"ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced\",\n \"linkCreatedAsPayor\": false,\n \"linkCreatedAsPayee\": true\n },\n \"entities\": [\n {\n \"isCustomer\": true,\n \"isPayor\": true,\n \"isPayee\": false,\n \"accountType\": \"business\",\n \"foreignId\": \"MY-DB-ID-12345\",\n \"profile\": {\n \"business\": {\n \"email\": \"customer@acme.com\",\n \"legalBusinessName\": \"Acme Inc.\",\n \"website\": \"http://www.acme.com\",\n \"businessType\": \"llc\",\n \"phone\": {\n \"countryCode\": \"1\",\n \"number\": \"4155551234\"\n },\n \"address\": {\n \"addressLine1\": \"123 Main St\",\n \"addressLine2\": \"Unit 1\",\n \"city\": \"San Francisco\",\n \"stateOrProvince\": \"CA\",\n \"postalCode\": \"94105\",\n \"country\": \"US\"\n },\n \"taxId\": {\n \"ein\": {\n \"number\": \"12-3456789\"\n }\n }\n }\n }\n }\n ]\n}") .asString(); ``` ```php FromObjects request('POST', 'https://api.mercoa.com/entities', [ 'body' => '{ "connectedEntity": { "id": "ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced", "linkCreatedAsPayor": false, "linkCreatedAsPayee": true }, "entities": [ { "isCustomer": true, "isPayor": true, "isPayee": false, "accountType": "business", "foreignId": "MY-DB-ID-12345", "profile": { "business": { "email": "customer@acme.com", "legalBusinessName": "Acme Inc.", "website": "http://www.acme.com", "businessType": "llc", "phone": { "countryCode": "1", "number": "4155551234" }, "address": { "addressLine1": "123 Main St", "addressLine2": "Unit 1", "city": "San Francisco", "stateOrProvince": "CA", "postalCode": "94105", "country": "US" }, "taxId": { "ein": { "number": "12-3456789" } } } } } ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp FromObjects using RestSharp; var client = new RestClient("https://api.mercoa.com/entities"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"connectedEntity\": {\n \"id\": \"ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced\",\n \"linkCreatedAsPayor\": false,\n \"linkCreatedAsPayee\": true\n },\n \"entities\": [\n {\n \"isCustomer\": true,\n \"isPayor\": true,\n \"isPayee\": false,\n \"accountType\": \"business\",\n \"foreignId\": \"MY-DB-ID-12345\",\n \"profile\": {\n \"business\": {\n \"email\": \"customer@acme.com\",\n \"legalBusinessName\": \"Acme Inc.\",\n \"website\": \"http://www.acme.com\",\n \"businessType\": \"llc\",\n \"phone\": {\n \"countryCode\": \"1\",\n \"number\": \"4155551234\"\n },\n \"address\": {\n \"addressLine1\": \"123 Main St\",\n \"addressLine2\": \"Unit 1\",\n \"city\": \"San Francisco\",\n \"stateOrProvince\": \"CA\",\n \"postalCode\": \"94105\",\n \"country\": \"US\"\n },\n \"taxId\": {\n \"ein\": {\n \"number\": \"12-3456789\"\n }\n }\n }\n }\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift FromObjects import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "connectedEntity": [ "id": "ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced", "linkCreatedAsPayor": false, "linkCreatedAsPayee": true ], "entities": [ [ "isCustomer": true, "isPayor": true, "isPayee": false, "accountType": "business", "foreignId": "MY-DB-ID-12345", "profile": ["business": [ "email": "customer@acme.com", "legalBusinessName": "Acme Inc.", "website": "http://www.acme.com", "businessType": "llc", "phone": [ "countryCode": "1", "number": "4155551234" ], "address": [ "addressLine1": "123 Main St", "addressLine2": "Unit 1", "city": "San Francisco", "stateOrProvince": "CA", "postalCode": "94105", "country": "US" ], "taxId": ["ein": ["number": "12-3456789"]] ]] ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/entities")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```