---
title: "Add Entities"
method: POST
path: "/entityGroup/{entityGroupId}/addEntities"
tags: ["entity-group"]
---

# Add Entities

`POST /entityGroup/{entityGroupId}/addEntities`

## Request

- Base URL: `https://api.mercoa.com`
- URL: `https://api.mercoa.com/entityGroup/{entityGroupId}/addEntities`
- Auth: HTTP bearer

Add entities to an entity group

## Path parameters

- `entityGroupId` string, required

## Request body

- EntityGroupTypesEntityGroupAddEntitiesRequest
  - `entityIds` EntityTypesEntityId[], required: List of entity IDs or foreign IDs to add to the group
  - `copyUsersFrom` union
    - boolean
    - string
  - `filterRoles` string[]: List of roles to filter users by. If not provided, all users will be copied. If provided, only users with the provided roles will be copied.

## Response `200`

Response with status 200

- EntityGroupTypesEntityGroupResponse
  - `id` string, required
  - `foreignId` string
  - `name` string
  - `emailToName` string
  - `entities` EntityTypesEntityResponse[], required
    - `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
  - `metadata` object, 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)