Mercoa entity > user API
The entity > user API from Mercoa — 4 operation(s) for entity > user.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/mercoa:mercoa-entity-user-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Reference entity > user API
version: 1.0.0
servers:
- url: https://api.mercoa.com
description: Production
tags:
- name: entity > user
paths:
/entity/{entityId}/users:
get:
operationId: entity_user_find
summary: Search entity users
tags:
- entity > user
parameters:
- name: entityId
in: path
description: Entity ID or Entity ForeignID
required: true
schema:
$ref: '#/components/schemas/entityTypes_EntityId'
- name: foreignId
in: query
description: ID used to identify user in your system
required: false
schema:
type: string
- name: role
in: query
description: Filter users by role. If multiple roles are provided, users with any of the roles will be returned.
required: false
schema:
type: string
- name: name
in: query
description: Filter users by name. Partial matches are supported.
required: false
schema:
type: string
- name: email
in: query
description: Filter users by email. Partial matches are supported.
required: false
schema:
type: string
- name: limit
in: query
description: Number of entities to return. Limit can range between 1 and 100, and the default is 10.
required: false
schema:
type: integer
- name: startingAfter
in: query
description: The ID of the user to start after. If not provided, the first page of entities will be returned.
required: false
schema:
$ref: '#/components/schemas/entityTypes_EntityUserId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/entityTypes_FindEntityUserResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- BadRequest
content:
type: string
required:
- errorName
- content
'401':
description: Error response with status 401
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Unauthorized
content:
type: string
required:
- errorName
- content
'403':
description: Error response with status 403
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Forbidden
content:
type: string
required:
- errorName
- content
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFound
content:
type: string
required:
- errorName
- content
'409':
description: Error response with status 409
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Conflict
content:
type: string
required:
- errorName
- content
'500':
description: Error response with status 500
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- InternalServerError
content:
type: string
required:
- errorName
- content
'501':
description: Error response with status 501
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Unimplemented
content:
type: string
required:
- errorName
- content
security:
- default: []
/entity/{entityId}/user:
post:
operationId: entity_user_create
summary: Create entity user
tags:
- entity > user
parameters:
- name: entityId
in: path
description: Entity ID or Entity ForeignID
required: true
schema:
$ref: '#/components/schemas/entityTypes_EntityId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/entityTypes_EntityUserResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- BadRequest
content:
type: string
required:
- errorName
- content
'401':
description: Error response with status 401
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Unauthorized
content:
type: string
required:
- errorName
- content
'403':
description: Error response with status 403
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Forbidden
content:
type: string
required:
- errorName
- content
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFound
content:
type: string
required:
- errorName
- content
'409':
description: Error response with status 409
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Conflict
content:
type: string
required:
- errorName
- content
'500':
description: Error response with status 500
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- InternalServerError
content:
type: string
required:
- errorName
- content
'501':
description: Error response with status 501
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Unimplemented
content:
type: string
required:
- errorName
- content
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/entityTypes_EntityUserRequest'
security:
- default: []
/entity/{entityId}/user/{userId}:
get:
operationId: entity_user_get
summary: Get entity user
tags:
- entity > user
parameters:
- name: entityId
in: path
description: Entity ID or Entity ForeignID
required: true
schema:
$ref: '#/components/schemas/entityTypes_EntityId'
- name: userId
in: path
description: User ID or User ForeignID
required: true
schema:
$ref: '#/components/schemas/entityTypes_EntityUserId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/entityTypes_EntityUserResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- BadRequest
content:
type: string
required:
- errorName
- content
'401':
description: Error response with status 401
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Unauthorized
content:
type: string
required:
- errorName
- content
'403':
description: Error response with status 403
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Forbidden
content:
type: string
required:
- errorName
- content
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFound
content:
type: string
required:
- errorName
- content
'409':
description: Error response with status 409
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Conflict
content:
type: string
required:
- errorName
- content
'500':
description: Error response with status 500
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- InternalServerError
content:
type: string
required:
- errorName
- content
'501':
description: Error response with status 501
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Unimplemented
content:
type: string
required:
- errorName
- content
security:
- default: []
post:
operationId: entity_user_update
summary: Update entity user
tags:
- entity > user
parameters:
- name: entityId
in: path
description: Entity ID or Entity ForeignID
required: true
schema:
$ref: '#/components/schemas/entityTypes_EntityId'
- name: userId
in: path
description: User ID or User ForeignID
required: true
schema:
$ref: '#/components/schemas/entityTypes_EntityUserId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/entityTypes_EntityUserResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- BadRequest
content:
type: string
required:
- errorName
- content
'401':
description: Error response with status 401
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Unauthorized
content:
type: string
required:
- errorName
- content
'403':
description: Error response with status 403
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Forbidden
content:
type: string
required:
- errorName
- content
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFound
content:
type: string
required:
- errorName
- content
'409':
description: Error response with status 409
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Conflict
content:
type: string
required:
- errorName
- content
'500':
description: Error response with status 500
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- InternalServerError
content:
type: string
required:
- errorName
- content
'501':
description: Error response with status 501
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Unimplemented
content:
type: string
required:
- errorName
- content
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/entityTypes_EntityUserRequest'
security:
- default: []
delete:
operationId: entity_user_delete
summary: Delete entity user
description: 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.
tags:
- entity > user
parameters:
- name: entityId
in: path
description: Entity ID or Entity ForeignID
required: true
schema:
$ref: '#/components/schemas/entityTypes_EntityId'
- name: userId
in: path
description: User ID or User ForeignID
required: true
schema:
$ref: '#/components/schemas/entityTypes_EntityUserId'
responses:
'200':
description: Successful response
'400':
description: Error response with status 400
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- BadRequest
content:
type: string
required:
- errorName
- content
'401':
description: Error response with status 401
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Unauthorized
content:
type: string
required:
- errorName
- content
'403':
description: Error response with status 403
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Forbidden
content:
type: string
required:
- errorName
- content
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFound
content:
type: string
required:
- errorName
- content
'409':
description: Error response with status 409
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Conflict
content:
type: string
required:
- errorName
- content
'500':
description: Error response with status 500
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- InternalServerError
content:
type: string
required:
- errorName
- content
'501':
description: Error response with status 501
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Unimplemented
content:
type: string
required:
- errorName
- content
security:
- default: []
/entity/{entityId}/user/{userId}/token:
post:
operationId: entity_user_getToken
summary: Generate JWT Token
description: 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.
tags:
- entity > user
parameters:
- name: entityId
in: path
description: Entity ID or Entity ForeignID
required: true
schema:
$ref: '#/components/schemas/entityTypes_EntityId'
- name: userId
in: path
description: User ID or User ForeignID
required: true
schema:
$ref: '#/components/schemas/entityTypes_EntityUserId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
type: string
'400':
description: Error response with status 400
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- BadRequest
content:
type: string
required:
- errorName
- content
'401':
description: Error response with status 401
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Unauthorized
content:
type: string
required:
- errorName
- content
'403':
description: Error response with status 403
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Forbidden
content:
type: string
required:
- errorName
- content
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFound
content:
type: string
required:
- errorName
- content
'409':
description: Error response with status 409
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Conflict
content:
type: string
required:
- errorName
- content
'500':
description: Error response with status 500
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- InternalServerError
content:
type: string
required:
- errorName
- content
'501':
description: Error response with status 501
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- Unimplemented
content:
type: string
required:
- errorName
- content
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/entityTypes_TokenGenerationOptions'
security:
- default: []
components:
schemas:
entityTypes_TokenGenerationStyleOptions:
type: object
properties:
primaryColor:
type: string
required:
- primaryColor
title: TokenGenerationStyleOptions
entityTypes_TokenGenerationPagesOptions:
type: object
properties:
paymentMethods:
type: boolean
representatives:
type: boolean
notifications:
type: boolean
counterparties:
type: boolean
approvals:
type: boolean
emailLog:
type: boolean
title: TokenGenerationPagesOptions
entityTypes_TokenGenerationVendorOptions:
type: object
properties:
disableCreation:
type: boolean
description: If true, the user will not be able to create new vendors.
network:
$ref: '#/components/schemas/entityTypes_VendorNetwork'
required:
- network
title: TokenGenerationVendorOptions
entityTypes_FindEntityUserResponse:
type: object
properties:
count:
type: integer
description: Total number of users 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:
type: boolean
description: True if there are more users available for the given filters.
data:
type: array
items:
$ref: '#/components/schemas/entityTypes_EntityUserResponse'
required:
- count
- hasMore
- data
title: FindEntityUserResponse
entityTypes_EntityUserResponse:
type: object
properties:
id:
$ref: '#/components/schemas/entityTypes_EntityUserId'
foreignId:
type: string
description: The ID used to identify this user in your system.
email:
type: string
name:
type: string
roles:
type: array
items:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- roles
- createdAt
- updatedAt
title: EntityUserResponse
entityTypes_TokenGenerationOptions:
type: object
properties:
expiresIn:
type: string
description: Expressed in seconds or a string describing a time span. The default is 1h.
invoice:
$ref: '#/components/schemas/entityTypes_TokenGenerationInvoiceOptions'
pages:
$ref: '#/components/schemas/entityTypes_TokenGenerationPagesOptions'
style:
$ref: '#/components/schemas/entityTypes_TokenGenerationStyleOptions'
vendors:
$ref: '#/components/schemas/entityTypes_TokenGenerationVendorOptions'
entity:
$ref: '#/components/schemas/entityTypes_TokenGenerationEntityOptions'
sessionId:
type: string
description: Optional session ID to use for the token. If not provided, this token will not be associated with a session.
title: TokenGenerationOptions
entityTypes_TokenGenerationEntityOptions:
type: object
properties:
enableMercoaPayments:
type: boolean
description: If true, will require entity to undergo KYB to use Mercoa payment rails and will capture required KYB data in the portal.
title: TokenGenerationEntityOptions
entityTypes_EntityId:
type: string
title: EntityId
entityTypes_EntityUserRequest:
type: object
properties:
foreignId:
type: string
description: The ID used to identify this user in your system.
email:
type: string
name:
type: string
roles:
type: array
items:
type: string
description: 'List of roles. A role can be any string. For example: "payer", "approver", "viewer"'
title: EntityUserRequest
entityTypes_TokenGenerationInvoiceOptions:
type: object
properties:
lineItems:
$ref: '#/components/schemas/entityTypes_LineItemAvailabilities'
description: Defaults to OPTIONAL. If set to REQUIRED, the user will be required to provide at least one line item when creating an invoice. If set to DISABLED, the user will not be able to provide line items when creating an invoice.
status:
type: array
items:
$ref: '#/components/schemas/invoiceTypes_InvoiceStatus'
recurring:
type: boolean
description: If true, recurring invoice templates will be available to the user.
required:
- status
title: TokenGenerationInvoiceOptions
invoiceTypes_InvoiceStatus:
type: string
enum:
- UNASSIGNED
- DRAFT
- NEW
- APPROVED
- SCHEDULED
- PENDING
- PAID
- ARCHIVED
- REFUSED
- CANCELED
- FAILED
title: InvoiceStatus
entityTypes_VendorNetwork:
type: string
enum:
- all
- platform
- entity
title: VendorNetwork
entityTypes_EntityUserId:
type: string
title: EntityUserId
entityTypes_LineItemAvailabilities:
type: string
enum:
- DISABLED
- OPTIONAL
- REQUIRED
title: LineItemAvailabilities
securitySchemes:
default:
type: http
scheme: bearer