Understand the data model

A business is data Coris knows about, and an account is that business in your portfolio. Every integration uses the six objects on this page.

Legal entityThe registered owner.
EstablishmentA location or website.legal_entity_id
AccountOne merchant in your portfolio.establishment_id
PersonAn owner or controller.account_id
TransactionA payment on an account.account_id

Follow one business through the objects

Walk one business from its legal entity to an account, in the same session as the Quickstart.

Read the legal entity behind the business.

LEGAL_ENTITY_ID=$(printf '%s' "$PROFILE" | jq -r '.legal_entity.id')

curl -s "$CORIS_BASE_URL/legal_entity/$LEGAL_ENTITY_ID/" \
  -H "Authorization: Token $CORIS_API_KEY" | jq

legal_entity_id = profile["legal_entity"]["id"]

response = requests.get(f"{BASE_URL}/legal_entity/{legal_entity_id}/", headers=HEADERS)
print(response.json())

const legalEntityId = profile.legal_entity.id;

const legalEntity = await fetch(`${BASE_URL}/legal_entity/${legalEntityId}/`, {
  headers: HEADERS,
});
console.log(await legalEntity.json());

Try GET /legal_entity/{legal_entity_id}/ in the API explorer.

Create an account from establishment.id. With establishment_id, the 201 holds the account itself. With business details instead, the 201 holds a request_id to poll.

REFERENCE_ID="acme-plumbing-$(date +%s)"

ACCOUNT=$(curl -s -X POST "$CORIS_BASE_URL/accounts/" \
  -H "Authorization: Token $CORIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"reference_id\": \"$REFERENCE_ID\", \"establishment_id\": \"$ESTABLISHMENT_ID\"}")

ACCOUNT_ID=$(printf '%s' "$ACCOUNT" | jq -r '.id')
echo "$ACCOUNT_ID"

reference_id = f"acme-plumbing-{int(time.time())}"

response = requests.post(
    f"{BASE_URL}/accounts/",
    headers=HEADERS,
    json={"reference_id": reference_id, "establishment_id": establishment_id},
)
response.raise_for_status()
account_id = response.json()["id"]
print(account_id)

const referenceId = `acme-plumbing-${Date.now()}`;

const createdAccount = await fetch(`${BASE_URL}/accounts/`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ reference_id: referenceId, establishment_id: establishmentId }),
});
if (!createdAccount.ok) throw new Error(await createdAccount.text());
const account = await createdAccount.json();
const accountId = account.id;
console.log(accountId);

Try POST /accounts/ in the API explorer.

Read the account back with your own ID. Most paths that take account_id also accept your reference_id. The Merchant Profiler PDF report paths take only the Coris id.

curl -s "$CORIS_BASE_URL/accounts/$REFERENCE_ID/" \
  -H "Authorization: Token $CORIS_API_KEY" | jq

response = requests.get(f"{BASE_URL}/accounts/{reference_id}/", headers=HEADERS)
print(response.json())

const byReference = await fetch(`${BASE_URL}/accounts/${referenceId}/`, {
  headers: HEADERS,
});
console.log(await byReference.json());

Try GET /accounts/{account_id}/ in the API explorer.

Read the response

Step 3 returns the account. This sample is shortened.

{
  "id": "c47f0e21-6a9b-4d38-a2e5-1b8d3f90c6a7",
  "reference_id": "acme-plumbing-1762300800",
  "name": "Acme Plumbing Co.",
  "created": 1762300800,
  "updated": 1762300800,
  "tpv": 0,
  "legal_name": null,
  "dba_name": null,
  "source": "api"
}

Field	Meaning	What to do
`id`	The Coris account ID.	Store it, or use `reference_id` instead.
`reference_id`	Your ID for this merchant.	Keep it unique. A repeat returns `409`.
`tpv`	Payment volume in USD cents over the last 450 days.	`0` means none yet. Other routes can return `null`, which means not available.

The six objects

Object	What it is	ID	Created by
Business	The real-world company. In the API it is an establishment with its legal entity.	No single ID. Use `establishment.id`.	Coris, through search or Merchant Profiler
Establishment	A location or website where the business operates.	`establishment.id`	Coris
Legal entity	The registered owner of the business.	`legal_entity.id`	Coris
Account	One merchant in your portfolio, linked to an establishment.	`id` and your `reference_id`	You, or a Stripe or Adyen event
Person	An owner or controller of an account.	`id`	You, or a processor event
Transaction	A payment on an account.	`id` and your `transaction_id`	You, or a processor event

Establishments and legal entities are Coris-sourced data. Accounts, persons and transactions belong to your workspace.

Which ID you hold at each step

After this call	You hold	Use it for
Merchant Profiler or Business Search	`establishment.id`, `legal_entity.id`	`/establishment/` and `/legal_entity/` endpoints, and `establishment_id` on `POST /accounts/`
Create an account	`id`, and your `reference_id`	`/accounts/` endpoints. From here, carry the account ID.

See the glossary for KYB, MCC, OFAC and other terms.

What to do next

Your goal	Object to start from
Check a business once	Establishment and legal entity. No account needed.
Watch a merchant over time	Account. See Monitor your portfolio.
Send a whole portfolio	Accounts, by file or API. See Fintechs, ISOs and sponsor banks.

FAQ

When do I need an account?

You need one for monitoring, persons, transactions and tags. Business data calls work without it.

Can two accounts share one establishment?

Yes. Each has its own reference_id, so two merchant records can point to one establishment.

What does the sandbox `reference_id` need to be?

Any string that is new in your workspace. The samples add a timestamp so you can run them twice.

Next: Authenticate your requests