--- title: "Create entity" method: POST path: "/entity" tags: ["entity"] --- # Create entity `POST /entity` ## Request - Base URL: `https://api.mercoa.com` - URL: `https://api.mercoa.com/entity` - Auth: HTTP bearer ## Request body - union - EntityTypesEntityCreationRequest - `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. - EntityTypesEntityCloneRequest - `createFromId` string, 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. - `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 - EntityTypesEntityResponse - `id` string, required - `name` string, required - `email` string, required - `foreignId` string: The ID used to identify this entity in your system - `emailTo` string: Local-part/username of the email address to which to send invoices to be added to the Invoice Inbox. - `emailToAlias` string[]: Email inbox alias addresses. Used when forwarding emails to the emailTo address from an alias. - `isCustomer` boolean, required: True if this entity has a direct relationship with your organization. - `accountType` 'business' | 'individual', required - `profile` EntityTypesProfileResponse, required - `business` EntityTypesBusinessProfileResponse - `email` string - `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 - `description` string - `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 - `ownersProvided` boolean: True if all representatives have been provided for this business. - `taxIDProvided` boolean, required - `taxId` EntityTypesTaxID - `ein` EntityTypesEin, required - `number` string, required: Must be in the format XX-XXXXXXX. - `formationDate` string, date-time - `industryCodes` EntityTypesIndustryCodes - `mcc` string - `averageMonthlyTransactionVolume` number, double - `averageTransactionSize` number, double - `maxTransactionSize` number, double - `individual` EntityTypesIndividualProfileResponse - `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 - `birthDateProvided` boolean, required - `governmentIDProvided` boolean, required - `logo` string: URL for the entity logo - `status` 'unverified' | 'pending' | 'resubmit' | 'review' | 'verified' | 'failed', required - `oatfiStatus` string: The OatFi status of this entity - `oatfiUnderwritingResponse` object: The OatFi underwriting response of this entity - `acceptedTos` boolean, required: True if this entity has accepted the terms of service. - `isPayor` boolean, required: True if this entity can pay invoices. - `isPayee` boolean, required: True if this entity can receive payments. - `isNetworkPayor` boolean, required: True if this entity is available as a payor to any entity on your platform. Otherwise this entity will only be available as a payor to entities that have a direct relationship with this entity. - `isNetworkPayee` boolean, required: True if this entity is available as a payee to any entity on your platform. Otherwise this entity will only be available as a payee to entities that have a direct relationship with this entity. - `metadata` object: Simple key/value metadata associated with this entity. For more complex metadata, use the Metadata API. - `createdAt` string, date-time, required - `updatedAt` string, date-time, required ## 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)