Search entities — Mercoa

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

Query parameters

paymentMethodsbooleanOptional

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

isCustomerbooleanOptional

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.

foreignIdstringOptional

ID used to identify this entity in your system

statusenumOptional

isPayeebooleanOptional

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.

isPayorbooleanOptional

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.

namestringOptionalDeprecated

Use search instead. Deprecated. Filter entities by name. Partial matches are supported.

searchstringOptional

Find entities by name, email, or emailTo. Partial matches are supported.

metadataobjectOptional

Filter entities by simple key/value metadata. Each filter will be applied as an AND condition. Duplicate keys will be ignored.

returnMetadatastringOptional

Return simple key/value metadata for the specified keys for the entities. For more complex metadata, use the Metadata API.

limitintegerOptional

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

startingAfterstringOptional

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

Response

This endpoint returns an object.

countinteger

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

hasMoreboolean

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

datalist of objects

1 curl -G https://api.mercoa.com/entity \ 2 -H "Authorization: Bearer <token>" \ 3 -d isCustomer=true \ 4 -d foreignId=MY-DB-ID-12345 \ 5 -d paymentMethods=true

1 { 2 "count": 1, 3 "hasMore": false, 4 "data": [ 5 { 6 "acceptedTos": true, 7 "accountType": "business", 8 "createdAt": "2024-01-01T00:00:00Z", 9 "email": "customer@acme.com", 10 "id": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c", 11 "isCustomer": true, 12 "isNetworkPayee": false, 13 "isNetworkPayor": false, 14 "isPayee": false, 15 "isPayor": true, 16 "name": "Acme Inc.", 17 "profile": { 18 "business": { 19 "legalBusinessName": "Acme Inc.", 20 "taxIDProvided": true, 21 "email": "customer@acme.com", 22 "businessType": "llc", 23 "phone": { 24 "countryCode": "1", 25 "number": "4155551234" 26 }, 27 "address": { 28 "addressLine1": "123 Main St", 29 "city": "San Francisco", 30 "stateOrProvince": "CA", 31 "postalCode": "94105", 32 "addressLine2": "Unit 1", 33 "country": "US" 34 }, 35 "ownersProvided": true, 36 "taxId": { 37 "ein": { 38 "number": "12-3456789" 39 } 40 } 41 } 42 }, 43 "status": "verified", 44 "updatedAt": "2024-01-02T00:00:00Z", 45 "foreignId": "MY-DB-ID-12345", 46 "paymentMethods": [ 47 { 48 "type": "bankAccount", 49 "accountName": "My Checking Account", 50 "accountNumber": "99988767623", 51 "accountType": "CHECKING", 52 "bankName": "Chase", 53 "createdAt": "2021-01-01T00:00:00Z", 54 "frozen": false, 55 "id": "pm_4794d597-70dc-4fec-b6ec-c5988e759769", 56 "isDefaultDestination": true, 57 "isDefaultSource": true, 58 "metadata": {}, 59 "routingNumber": "12345678", 60 "status": "VERIFIED", 61 "supportedCurrencies": [ 62 "USD" 63 ], 64 "updatedAt": "2021-01-01T00:00:00Z" 65 } 66 ] 67 } 68 ] 69 }

1	curl -G https://api.mercoa.com/entity \
2	-H "Authorization: Bearer <token>" \
3	-d isCustomer=true \
4	-d foreignId=MY-DB-ID-12345 \
5	-d paymentMethods=true

1	{
2	"count": 1,
3	"hasMore": false,
4	"data": [
5	{
6	"acceptedTos": true,
7	"accountType": "business",
8	"createdAt": "2024-01-01T00:00:00Z",
9	"email": "customer@acme.com",
10	"id": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
11	"isCustomer": true,
12	"isNetworkPayee": false,
13	"isNetworkPayor": false,
14	"isPayee": false,
15	"isPayor": true,
16	"name": "Acme Inc.",
17	"profile": {
18	"business": {
19	"legalBusinessName": "Acme Inc.",
20	"taxIDProvided": true,
21	"email": "customer@acme.com",
22	"businessType": "llc",
23	"phone": {
24	"countryCode": "1",
25	"number": "4155551234"
26	},
27	"address": {
28	"addressLine1": "123 Main St",
29	"city": "San Francisco",
30	"stateOrProvince": "CA",
31	"postalCode": "94105",
32	"addressLine2": "Unit 1",
33	"country": "US"
34	},
35	"ownersProvided": true,
36	"taxId": {
37	"ein": {
38	"number": "12-3456789"
39	}
40	}
41	}
42	},
43	"status": "verified",
44	"updatedAt": "2024-01-02T00:00:00Z",
45	"foreignId": "MY-DB-ID-12345",
46	"paymentMethods": [
47	{
48	"type": "bankAccount",
49	"accountName": "My Checking Account",
50	"accountNumber": "99988767623",
51	"accountType": "CHECKING",
52	"bankName": "Chase",
53	"createdAt": "2021-01-01T00:00:00Z",
54	"frozen": false,
55	"id": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
56	"isDefaultDestination": true,
57	"isDefaultSource": true,
58	"metadata": {},
59	"routingNumber": "12345678",
60	"status": "VERIFIED",
61	"supportedCurrencies": [
62	"USD"
63	],
64	"updatedAt": "2021-01-01T00:00:00Z"
65	}
66	]
67	}
68	]
69	}