Entities
When a transaction is enriched, usually one or more entities are returned that represent the parties in the transaction, such as the merchant and any intermediary. The entities are unique and identified by their id.
An entity on our system represents an organization that can have any number of physical locations, and be present in multiple countries. The same entity (as in, with the same id) can be obtained from different locations and websites due to this reason. When querying our system for the website amazon.de and amazon.com, the Amazon entity is retrieved but the different websites are also kept as they are both valid websites for the returned entity. In the same way, the system can provide different locations referring to particular physical stores (if the query requests it) while also providing the same id in these cases.
Each entity has the following structure:
| attribute | type | summary |
|---|---|---|
| id | string | Unique identifier in UUID4 format that represents the entity |
| name | string | The name associated with the entity |
| website | string | The website of the entity |
| logo | string | If applicable, the logo for the entity |
| location | string | If applicable, the location of the entity (i.e., when the entity refers to a phyisical location) |
| location_structured | LocationStructured | If applicable, the location in LocationStructured format |
Entities are returned in transaction enrichment, but there are also some operations that can be done separately, such as querying our entity database for a specific entity either by name or by website.
Querying entities
It is possible to query our entity database directly through the API by using the GET /v2/entities endpoint. An entity can be queried by name or by website, and a location hint can also be provided to narrow down the search.
You can query an entity by name:
$ curl \
-H "X-API-KEY: <YOUR-API-KEY>" \
-H "Content-Type: application/json" \
-X GET \
https://api.ntropy.com/v2/entities?name=Amazon
Or by website:
$ curl \
-H "X-API-KEY: <YOUR-API-KEY>" \
-H "Content-Type: application/json" \
-X GET \
https://api.ntropy.com/v2/entities?website=amazon.co.uk
You can also provide a location hint in order to narrow down the search to a specific physical place:
$ curl \
-H "X-API-KEY: <YOUR-API-KEY>" \
-H "Content-Type: application/json" \
-X GET \
https://api.ntropy.com/v2/entities?name=Starbucks&location=Union%20Square%20New%20York