--- title: "Find payee counterparties" method: GET path: "/entity/{entityId}/counterparties/payees" tags: ["entity > counterparty"] --- # Find payee counterparties `GET /entity/{entityId}/counterparties/payees` ## Request - Base URL: `https://api.mercoa.com` - URL: `https://api.mercoa.com/entity/{entityId}/counterparties/payees` - Auth: HTTP bearer Find payee counterparties. This endpoint lets you find vendors linked to the entity. ## Path parameters - `entityId` string, required ## Query parameters - `name` string - `search` string - `networkType` 'ENTITY' | 'NETWORK' - `paymentMethods` boolean - `invoiceMetrics` boolean - `counterpartyId` string - `metadata` InvoiceTypesMetadataFilter - `key` string, required - `value` union, required - string - string[] - `returnMetadata` string - `limit` integer - `startingAfter` string ## Response `200` Response with status 200 - EntityTypesFindCounterpartiesResponse - `count` integer, required: Total number of counterparties for the given filters. This value is not limited by the limit parameter. It is provided so that you can determine how many pages of results are available. - `hasMore` boolean, required: True if there are more counterparties available for the given filters. - `data` EntityTypesCounterpartyResponse[], 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 - `accounts` EntityTypesCounterpartyCustomizationAccount[]: If the entity searching for counterparties has any accounts configured in the Payee/Payor relationship, they will be returned - `accountId` string, required: The ID the counterparty has assigned to this account. - `postalCode` string: The postal code the counterparty has assigned to this account. - `nameOnAccount` string: The name on the account the counterparty has assigned to this account. - `paymentMethods` PaymentMethodTypesPaymentMethodResponse[] - union - object - `type` 'bankAccount', required: Discriminator value: bankAccount - `id` string, required - `isDefaultSource` boolean, required: Indicates whether this payment method is the default source for the entity - `isDefaultDestination` boolean, required: Indicates whether this payment method is the default destination for the entity - `supportedCurrencies` PaymentMethodTypesCurrencyCode[], required - `externalAccountingSystemId` string: ID for this payment method in the external accounting system (e.g Rutter or Codat) - `frozen` boolean, required: Frozen payment methods cannot be used for payments, but will still be returned in API responses. - `metadata` object, required: Metadata associated with this payment method. - `confirmedByEntity` boolean: (ALPHA, MAY BE REMOVED) Indicates whether the payment method has been verified by the entity. This is useful if another entity has added this payment method to this entity, and you want the owner of the payment method to verify it is correct. - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `accountName` string, required - `bankName` string, required - `routingNumber` string, required - `accountNumber` string, required - `accountType` 'CHECKING' | 'SAVINGS' | 'UNKNOWN', required - `status` 'NEW' | 'VERIFIED' | 'VERIFICATION_FAILED' | 'PENDING' | 'ERRORED', required - `checkOptions` PaymentMethodTypesBankAccountCheckOptions - `enabled` boolean: If true, will allow the user to print checks from this bank account - `initialCheckNumber` integer: If provided, will start the check number sequence at the provided number. If not provided, will start at 5000. - `routingNumberOverride` string: If provided, will print a check with the provided routing number instead of the one from the bank account - `accountNumberOverride` string: If provided, will print a check with the provided account number instead of the one from the bank account - `accountHolderNameOverride` string: If provided, will print a check with the provided account holder name instead of the payer name from the invoice - `accountHolderAddressOverride` CommonsAddress - … - `signatoryName` string, required: Name of the person who's signature will be printed on the check. - `signatureImage` string: Base64 encoded image of the signature. If not provided, will use the signatoryName to generate a signature. Mercoa will automatically grayscale, resize, and convert the image to a PNG the image to fit on the check. - `useSignatureImage` boolean: If true, will print checks with the provided signatureImage. If false, will print checks with a generated signature from the signatoryName. If this parameter is not set the default behavior is to use the signatureImage if provided. - object - `type` 'card', required: Discriminator value: card - `id` string, required - `isDefaultSource` boolean, required: Indicates whether this payment method is the default source for the entity - `isDefaultDestination` boolean, required: Indicates whether this payment method is the default destination for the entity - `supportedCurrencies` PaymentMethodTypesCurrencyCode[], required - `externalAccountingSystemId` string: ID for this payment method in the external accounting system (e.g Rutter or Codat) - `frozen` boolean, required: Frozen payment methods cannot be used for payments, but will still be returned in API responses. - `metadata` object, required: Metadata associated with this payment method. - `confirmedByEntity` boolean: (ALPHA, MAY BE REMOVED) Indicates whether the payment method has been verified by the entity. This is useful if another entity has added this payment method to this entity, and you want the owner of the payment method to verify it is correct. - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `cardType` 'credit' | 'debit' | 'prepaid' | 'unknown', required - `cardBrand` 'AmericanExpress' | 'Discover' | 'Mastercard' | 'Visa', required - `lastFour` string, required - `expMonth` string, required - `expYear` string, required - object - `type` 'check', required: Discriminator value: check - `id` string, required - `isDefaultSource` boolean, required: Indicates whether this payment method is the default source for the entity - `isDefaultDestination` boolean, required: Indicates whether this payment method is the default destination for the entity - `supportedCurrencies` PaymentMethodTypesCurrencyCode[], required - `externalAccountingSystemId` string: ID for this payment method in the external accounting system (e.g Rutter or Codat) - `frozen` boolean, required: Frozen payment methods cannot be used for payments, but will still be returned in API responses. - `metadata` object, required: Metadata associated with this payment method. - `confirmedByEntity` boolean: (ALPHA, MAY BE REMOVED) Indicates whether the payment method has been verified by the entity. This is useful if another entity has added this payment method to this entity, and you want the owner of the payment method to verify it is correct. - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `payToTheOrderOf` string, required - `addressLine1` string, required - `addressLine2` string - `city` string, required - `stateOrProvince` string, required - `postalCode` string, required - `country` string, required - object - `type` 'custom', required: Discriminator value: custom - `id` string, required - `isDefaultSource` boolean, required: Indicates whether this payment method is the default source for the entity - `isDefaultDestination` boolean, required: Indicates whether this payment method is the default destination for the entity - `supportedCurrencies` PaymentMethodTypesCurrencyCode[], required - `externalAccountingSystemId` string: ID for this payment method in the external accounting system (e.g Rutter or Codat) - `frozen` boolean, required: Frozen payment methods cannot be used for payments, but will still be returned in API responses. - `metadata` object, required: Metadata associated with this payment method. - `confirmedByEntity` boolean: (ALPHA, MAY BE REMOVED) Indicates whether the payment method has been verified by the entity. This is useful if another entity has added this payment method to this entity, and you want the owner of the payment method to verify it is correct. - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `foreignId` string: ID for this payment method in your system - `accountName` string - `accountNumber` string - `availableBalance` number, double: The available balance for this payment method. - `schemaId` string, required - `schema` PaymentMethodTypesCustomPaymentMethodSchemaResponse, required - `id` string, required - `name` string, required - `isSource` boolean, required: This payment method can be used as a payment source for an invoice - `isDestination` boolean, required: This payment method can be used as a payment destination for an invoice - `supportedCurrencies` PaymentMethodTypesCurrencyCode[], required: List of currencies that this payment method supports. - `fields` PaymentMethodTypesCustomPaymentMethodSchemaField[], required - … - `estimatedProcessingTime` integer, required: Estimated time in days for this payment method to process a payments. 0 is an same-day payment methods, -1 is unknown processing time. - `maxAmount` number, double: The maximum amount that can be transferred from this payment method in a single transaction. - `minAmount` number, double: The minimum amount that can be transferred from this payment method in a single transaction. Default is 1. - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `data` object, required: Object of key/value pairs that matches the keys in the linked payment method schema. - object - `type` 'offPlatform', required: Discriminator value: offPlatform - `id` string, required - `isDefaultSource` boolean, required: Indicates whether this payment method is the default source for the entity - `isDefaultDestination` boolean, required: Indicates whether this payment method is the default destination for the entity - `supportedCurrencies` PaymentMethodTypesCurrencyCode[], required - `externalAccountingSystemId` string: ID for this payment method in the external accounting system (e.g Rutter or Codat) - `frozen` boolean, required: Frozen payment methods cannot be used for payments, but will still be returned in API responses. - `metadata` object, required: Metadata associated with this payment method. - `confirmedByEntity` boolean: (ALPHA, MAY BE REMOVED) Indicates whether the payment method has been verified by the entity. This is useful if another entity has added this payment method to this entity, and you want the owner of the payment method to verify it is correct. - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - object - `type` 'utility', required: Discriminator value: utility - `id` string, required - `isDefaultSource` boolean, required: Indicates whether this payment method is the default source for the entity - `isDefaultDestination` boolean, required: Indicates whether this payment method is the default destination for the entity - `supportedCurrencies` PaymentMethodTypesCurrencyCode[], required - `externalAccountingSystemId` string: ID for this payment method in the external accounting system (e.g Rutter or Codat) - `frozen` boolean, required: Frozen payment methods cannot be used for payments, but will still be returned in API responses. - `metadata` object, required: Metadata associated with this payment method. - `confirmedByEntity` boolean: (ALPHA, MAY BE REMOVED) Indicates whether the payment method has been verified by the entity. This is useful if another entity has added this payment method to this entity, and you want the owner of the payment method to verify it is correct. - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `utilityId` string, required: The ID of the utility that this payment method is linked to. - object - `type` 'wallet', required: Discriminator value: wallet - `id` string, required - `isDefaultSource` boolean, required: Indicates whether this payment method is the default source for the entity - `isDefaultDestination` boolean, required: Indicates whether this payment method is the default destination for the entity - `supportedCurrencies` PaymentMethodTypesCurrencyCode[], required - `externalAccountingSystemId` string: ID for this payment method in the external accounting system (e.g Rutter or Codat) - `frozen` boolean, required: Frozen payment methods cannot be used for payments, but will still be returned in API responses. - `metadata` object, required: Metadata associated with this payment method. - `confirmedByEntity` boolean: (ALPHA, MAY BE REMOVED) Indicates whether the payment method has been verified by the entity. This is useful if another entity has added this payment method to this entity, and you want the owner of the payment method to verify it is correct. - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `availableBalance` PaymentMethodTypesWalletBalance, required - `amount` number, double, required: The amount in major units of the currency. - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'CNY' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VED' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL', required - `pendingBalance` PaymentMethodTypesWalletBalance, required - `amount` number, double, required: The amount in major units of the currency. - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'CNY' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VED' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL', required - `counterpartyType` EntityTypesCounterpartyNetworkType[] - `invoiceMetrics` EntityTypesCounterpartyInvoiceMetricsResponse - `totalCount` integer, required - `totalAmount` number, double, required - `statuses` EntityTypesCounterpartyInvoiceMetricsStatusResponse[], required - `status` 'UNASSIGNED' | 'DRAFT' | 'NEW' | 'APPROVED' | 'SCHEDULED' | 'PENDING' | 'PAID' | 'ARCHIVED' | 'REFUSED' | 'CANCELED' | 'FAILED', required - `totalCount` integer, required - `totalAmount` number, double, 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)