--- title: "Create Bulk Entities (Sync)" method: POST path: "/entities" tags: ["entity > bulk"] --- # Create Bulk Entities (Sync) `POST /entities` ## Request - Base URL: `https://api.mercoa.com` - URL: `https://api.mercoa.com/entities` - Auth: HTTP bearer Create multiple entities in bulk. This endpoint will process synchronously and return a list of entities that were created or failed to create. ## Query parameters - `emitWebhooks` boolean ## Request body - EntityTypesBulkEntityCreationRequest - `connectedEntity` EntityTypesBulkConnectedEntity - `id` string, required - `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). - `entities` EntityTypesEntityCreationRequest[], required - `foreignId` string: The ID used to identify this entity in your system. This ID must be unique across all entities in your system. - `emailTo` string: 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` string[]: Email inbox alias addresses. Used when forwarding emails to the emailTo address from an alias. Include the full email address. - `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` 'business' | 'individual', required - `profile` EntityTypesProfileRequest, required - `business` EntityTypesBusinessProfileRequest - `email` string: Email address for the business. Required for KYB. - `legalBusinessName` string, required - `businessType` 'soleProprietorship' | 'unincorporatedAssociation' | 'trust' | 'publicCorporation' | 'privateCorporation' | 'llc' | 'partnership' | 'unincorporatedNonProfit' | 'incorporatedNonProfit' - `phone` CommonsPhoneNumber - `countryCode` string, required - `number` string, required - `doingBusinessAs` string - `website` string: Website URL for the business. Must be in the format http://www.example.com. Required for KYB if description is not provided. - `description` string: Description of the business. Required for KYB if website is not provided. - `address` CommonsAddress - `addressLine1` string, required - `addressLine2` string - `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. - `country` string - `taxId` EntityTypesTaxID - `ein` EntityTypesEin, required - `number` string, required: Must be in the format XX-XXXXXXX. - `formationDate` string, date-time: Date of business formation - `industryCodes` EntityTypesIndustryCodes - `mcc` string - `averageMonthlyTransactionVolume` number, double: Average monthly transaction volume for the business. Required to collect funds. - `averageTransactionSize` number, double: Average transaction size for the business. Required to collect funds. - `maxTransactionSize` number, double: Maximum transaction size for the business. Required to collect funds. - `individual` EntityTypesIndividualProfileRequest - `email` string - `name` CommonsFullName, required - `firstName` string, required - `middleName` string - `lastName` string, required - `suffix` string - `phone` CommonsPhoneNumber - `countryCode` string, required - `number` string, required - `address` CommonsAddress - `addressLine1` string, required - `addressLine2` string - `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. - `country` string - `birthDate` CommonsBirthDate - `day` string - `month` string - `year` string - `governmentID` CommonsIndividualGovernmentID - `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. - `isNetworkPayor` boolean: 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: 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: 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` object: Simple key/value metadata associated with this entity. For more complex metadata, use the Metadata API. ## Response `200` Response with status 200 - EntityTypesBulkEntityCreationResponse - `data` EntityTypesBulkEntityCreationFromObjectResponse[], required - `id` string: The ID of the entity that was created. If the entity was not created, this will be undefined - `foreignId` string: If provided, this is the foreign ID of the entity that was created. - `error` string: The error message if the entity was not created ## Other responses - `400`: Error response with status 400 - `401`: Error response with status 401 - `403`: Error response with status 403 - `404`: Error response with status 404 - `409`: Error response with status 409 - `500`: Error response with status 500 - `501`: Error response with status 501 --- [API](https://skmtc.dev/mercoa/apis/mercoa-2.md) - [All operations](https://skmtc.dev/mercoa/apis/mercoa-2/llms.txt) - [OpenAPI document](https://skmtc.dev/mercoa/apis/mercoa-2/revisions/00a8e403ae18?raw)