Search all entities with the given filters. If no filters are provided, all entities will be returned.

Bad Request

Unauthorized

Forbidden

Not Found

Conflict

Internal Server Error

Unimplemented

Find Entity With foreignId

If true, will include entity payment methods as part of the response

If true, only entities with a direct relationship to the requesting organization will be returned. If false or not provided, all entities will be returned.

ID used to identify this entity in your system

If true, entities that are marked as payees will be returned.
If false or not provided, entities that are marked as payees will not be returned.

If true or not provided, entities that are marked as payors will be returned.
If false, entities that are marked as payors will not be returned.

Filter entities by name. Partial matches are supported.

Number of entities to return. Limit can range between 1 and 100, and the default is 10.

The ID of the entity to start after. If not provided, the first page of entities will be returned.

Search entities

BusinessPayor

Create entity

Get entity

Update entity

Delete entity

This endpoint is used to indicate acceptance of Mercoa's terms of service for an entity. Send a request to this endpoint only after the entity has accepted the Mercoa ToS. Entities must accept Mercoa ToS before they can be send or pay invoices using Mercoa's payment rails.

Default

Accept Terms of Service

This endpoint is used to initiate KYB for an entity.
Send a request to this endpoint only after the entity has accepted the Mercoa ToS,
all representatives have been added, and all required fields have been filled out.

Initiate KYB

Generate a JWT token for an entity with the given options. This token can be used to authenticate the entity in the Mercoa API and iFrame.

Generate JWT Token

Get a Plaid link token for an entity. This token can be used to add or update a bank account to the entity using Plaid Link.

Plaid Link token

Generate an onboarding link for the entity.

The type of onboarding link to generate. If not provided, the default is payee. The onboarding options are determined by your organization's onboarding configuration.

Expressed in seconds or a string describing a time span. The default is 24h.

The ID of the entity to connect to. If onboarding a payee, this should be the payor entity ID. If onboarding a payor, this should be the payee entity ID. If no connected entity ID is provided, the onboarding link will be for a standalone entity.

Generate Onboarding Link

Send an email with a onboarding link to the entity. The email will be sent to the email address associated with the entity.

Expressed in seconds or a string describing a time span. The default is 7 days.

Send Onboarding Email

Get all entity users

Get email log

Email Log

Create entity user

Get entity user

Update entity user

Delete entity user. This will also remove the user from all approval policies. If an approval policy will break as a result of this operation, this request will fail.

Delete entity user

Generate a JWT token for an entity user with the given options. This token can be used to authenticate the entity and entity user in the Mercoa API and iFrame.

Notification Policy

Notifications

User

Retrieve all invoice approval policies associated with an entity

Get All

Create an invoice approval policy associated with an entity

Create

Retrieve an invoice approval policy associated with an entity

Update an invoice approval policy associated with an entity

Update

Delete an invoice approval policy associated with Entity. BEWARE: Any approval policy deletion will result in all associated downstream policies also being deleted.

Delete

Approval Policy

Find payee counterparties. This endpoint lets you find vendors linked to the entity.

Find payee counterparties

Find payor counterparties. This endpoint lets you find customers linked to the entity.

Find payor counterparties

Create association between Entity and a given list of Payees. If a Payee has previously been archived, unarchive the Payee.

Link Payees

Marks Payees as unsearchable by Entity via Counterparty search. Invoices associated with these Payees will still be searchable via Invoice search.

Hide Payee

Create association between Entity and a given list of Payors. If a Payor has previously been archived, unarchive the Payor.

Link Payors

Marks Payors as unsearchable by Entity via Counterparty search. Invoices associated with these Payors will still be searchable via Invoice search.

Hide Payors

Counterparty

Create/Link an entity to an external accounting system like Codat or Rutter

Create/Update External Entity

Get a link to connect an entity to an external accounting system like Quickbooks or Xero

Connect External System

Sync an entity with an external accounting system. Will sync customers/vendors and invoices.

Sync External System

External Accounting System

Get invoices for an entity with the given filters.

Get invoice metrics for an entity with the given filters. Invoices will be grouped by currency. If none of excludePayables, excludeReceivables, payerId, vendorId, or invoiceId status filters are provided, excludeReceivables will be set to true.

Get Metrics

Invoice

Retrieve all metadata options associated with this entity

Retrieve metadata associated with a specific key

Update metadata associated with a specific key

Delete all metadata associated with a specific key

Metadata

Retrieve all notification policies associated with this entity

Retrieve notification policy associated with this entity

Update notification policy associated with this entity

Only custom payment methods can be updated.

Mark a payment method as inactive. This will not remove the payment method from the system, but will prevent it from being used in the future.

Initiate micro deposits for a bank account

Initiate micro deposits

Verify micro deposits

Get the available balance of a payment method. Only bank accounts added with Plaid are supported. This endpoint will return a cached value and will refresh the balance when called.

Get available balance

Payment Method

Representative

Entity

Search invoices for all entities in the organization

Find invoices created by a specific entity

Filter invoices by the ID of the entity that created the invoice.

Start date for invoice created on date filter.

End date for invoice created date filter.

Direction to order invoices by. Defaults to asc.

Number of invoices to return. Limit can range between 1 and 100, and the default is 10.

The ID of the invoice to start after. If not provided, the first page of invoices will be returned.

Find invoices by vendor name, invoice number, or amount. Partial matches are supported.

Filter invoices by metadata. Each filter will be applied as an AND condition. Duplicate keys will be ignored.

Filter invoices by assigned approver user ID.

Filter invoices by approver action. Needs to be used with approverId. For example, if you want to find all invoices that have been approved by a specific user, you would use approverId and approverAction=APPROVE.

DEPRECATED. Fees are now included by default in the response.

Search invoices

Create an invoice

Get an invoice

Update an invoice

Only invoices in the DRAFT and NEW status can be deleted.

Delete an invoice

Add Approver

Approve

Reject

Approval

Get all comments associated with this invoice

Comment

Get attachments (scanned/uploaded PDFs and images) associated with this invoice

Get Attachments

Upload documents (scanned/uploaded PDFs and images) associated with this Invoice

Upload Attachment

Delete an attachment (scanned/uploaded PDFs and images) associated with this invoice

Delete Attachment

Generate a PDF of the invoice. This PDF is generated from the data in the invoice, not from the uploaded documents.

Get Invoice PDF

Get a PDF of the check for the invoice. If the invoice does not have check as the disbursement method, an error will be returned. If the disbursement option for the check is set to 'MAIL', a void copy of the check will be returned. If the disbursement option for the check is set to 'PRINT', a printable check will be returned. If the invoice is NOT marked as PAID, the check will be a void copy.

Get Check PDF

Get the email subject and body that was used to create this invoice.

Get Source Email

Document

Get temporary link for payer to send payment

Get payment link

Trigger email to payer inviting them to make payment

Send payment email

Get temporary link for vendor to accept payment

Get disbursement link

Trigger email to vendor inviting them into the vendor portal

Send disbursement email

Payment Links

include supported payment methods in response

include external accounting system provider info in response

include payee onboarding options in response

include payor onboarding options in response

Get log of all emails sent to this organization. Content format subject to change.

Number of logs to return. Limit can range between 1 and 100, and the default is 10.

The ID of the log to start after. If not provided, the first page of logs will be returned.

Retrieve notification configuration for this notification type

Update notification configuration for this notification type

Reset notification configuration for this notification type

Reset

Notification Configuration

Organization

Find bank

Bank Lookup

Delete custom payment method schema. Schema that have been used in an invoice cannot be deleted.

Custom Payment Method Schema

Calculate the fees associated with an payment given the amount, payment source, and disbursement method. Can be used to calculate fees for a payment before creating an invoice.

Calculate fees

Fees

Run OCR on an Base64 encoded image or PDF. This endpoint will block until the OCR is complete.

Limit OCR vendor search to a specific network

When using the Entity vendor network, specify the entity to use if. EntityId on an auth token will take precedence over this parameter.

Run OCR (Sync)

Run OCR on an Base64 encoded image or PDF. This endpoint will return immediately and the OCR will be processed asynchronously.

Run OCR (Async)

Get the status and results of an asynchronous OCR job.

Get OCR Response (Async)

BankAddress

BankLookupResponse

Address

State or province code. Must be in the format XX.

Postal code. Must be in the format XXXXX or XXXXX-XXXX.

BirthDate

FullName

IndividualGovernmentID

Full Social Security Number. Must be in the format 123-45-6789.

OrderDirection

PhoneNumber

EmailLog

EmailLogId

EmailLogResponse

Total number of logs 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.

True if there are more logs available for the given filters.

AccountType

AmountTrigger

ApprovalPolicyId

ApprovalPolicyRequest

List of triggers that will cause this policy to be evaluated. If no triggers are provided, the policy will be evaluated for all invoices.

The policy ID of the previous approval policy in the chain of policies. Use 'root' if no upstreamPolicyId is intended to be set.

1	{
2	"availableBalance": 1,
3	"currency": "AED",
4	"status": "AVAILABLE",
5	"updatedAt": "2023-01-01T00:00:00Z"
6	}

Home

Getting Started

Concepts

Guides

SDKs

API Reference

Get available balance

Path parameters

Response

1	curl https://api.mercoa.com/entity/:entityId/paymentMethod/:paymentMethodId/balance \
2	-H "Authorization: Bearer <token>"