Entities

🧾 Entities

Entities represent the clients (users) of a Member's platform. They are the core participants in the ecosystem and serve as the basis for identifying transaction sources and destinations.

🧍‍♂️ Types of Entities

Entities can be one of the following types:

Type	Description
`Individual`	A natural person acting as a customer (e.g., private user of the platform).
`Business`	A legal entity such as a company or organization.

🛠️ Creating an Entity

To create an entity, use the following endpoint: POST /api/v1/entities

⚙️ Enabling Rules Based on Entity Fields

When integrating with this endpoint, certain fields can be used to power rule-based monitoring and risk detection. These fields allow for custom alerts and logic based on user behavior or status.

Field	Description / Example Use Case
`riskRating`	Defines the risk profile of the entity (`LOW`, `MEDIUM`, `HIGH`) Example: Trigger alerts for spikes in transaction volume for `MEDIUM` risk entities.
`externalCreatedAt`	Timestamp of when the entity was first created in your system Example: Flag high-volume transactions from newly created entities.
`annualSalary`	(For individuals) Reported yearly income Example: Raise an alert if deposits exceed a certain % of the user’s monthly salary.
`annualTurnover`	(For businesses) Reported yearly revenue Example: Raise an alert if a business deposits over X% of its monthly turnover within a short time span.

These fields help tailor your platform's compliance and risk framework, enabling proactive monitoring of financial behavior.

📘 Field Descriptions

Field	Type	Description
`type`	`string`	Type of entity: `INDIVIDUAL` or `BUSINESS`.
`id`	`string`	Unique identifier for the entity in Fiat Republic's system.
`externalId`	`string`	Member's identifier for the entity (e.g., `pyr_`, `eus_`).
`externalUpdatedAt`	`integer` (timestamp)	Timestamp of last update in the Member’s system (in milliseconds).
`externalCreatedAt`	`integer / null`	Timestamp of creation in the Member’s system (in milliseconds).
`externalStatus`	`string / null`	Current status in the Member’s system (e.g., `ACTIVE`).
`externalType`	`string`	Classification of the entity on the Member's side (e.g., `PAYER`, `END_USER`).
`email`	`string / null`	Email address of the entity (if available).
`phone`	`string / null`	Phone number of the entity (if available).
`riskRating`	`string / null`	Risk classification: e.g., `LOW`, `MEDIUM`, `HIGH` (if assigned).
`createdAt`	`integer` (timestamp)	Timestamp of creation in Fiat Republic's system (in milliseconds).
`updatedAt`	`integer` (timestamp)	Timestamp of last update in Fiat Republic's system (in milliseconds).
`metadata`	`object`	Optional metadata object for custom fields.
`firstName`	`string`	First name of the individual.
`middleName`	`string / null`	Middle name of the individual (if provided).
`lastName`	`string / null`	Last name of the individual (if provided).
`pep`	`boolean / null`	Indicates if the person is a Politically Exposed Person.
`birthCountry`	`string / null`	ISO 3166-1 alpha-2 code of the country of birth.
`nationality`	`string / null`	ISO 3166-1 alpha-2 code of nationality.
`dob`	`string / null`	Date of birth in `YYYY-MM-DD` format.
`address`	`object`
`address.line1`	`string`	First line of the address.
`address.line2`	`string / null`	Second line of the address (optional).
`address.city`	`string / null`	City (if provided).
`address.postalCode`	`string / null`	Postal code (if provided).
`address.country`	`string / null`	ISO 3166-1 alpha-2 country code (e.g., `DE`).
`annualSalaryRange`	`object`
`annualSalaryRange.min`	`number`	Minimum value of the annual salary range.
`annualSalaryRange.max`	`number`	Maximum value of the annual salary range.