> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ntropy.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ntropy.com/_mcp/server. # Synchronously enrich transactions POST https://api.ntropy.com/v3/transactions Content-Type: application/json Enriches a transaction with information about entities, locations and categories. Besides the original `id` that was submitted, the response only contains the enriched fields. To view the complete transaction, including the original fields, such as description or amount, you can use any of the Transactions API listing methods. Complete guide: [Transaction Enrichment](../../../enrichment/introduction). Reference: https://docs.ntropy.com/documentation/api/transactions/post-transaction-v-3-transactions-post ## Authentication - `X-Api-Key` header (required) — API Key authentication via header ## Request ### Body (application/json) This endpoint expects a TransactionInput. - `id` (string, required) — A unique identifier of the transaction - `description` (string, required) — The description string of the transaction - `date` (date, required) — The date that the transaction was posted. Uses ISO 8601 format (YYYY-MM-DD) - `amount` (double, required) — The amount of the transaction in the `currency`. Must be a positive value. For example, if the `currency` is USD, then it's the amount in dollars. - `entry_type` (enum, required) — The direction of the flow of the money from the perspective of the account holder. `outgoing` to represent money leaving the account, such as purchases or fees, while `incoming` represents money entering the account, such as income or refunds. - Allowed values: `incoming`, `outgoing` - `currency` (enum, required) — The currency of the transaction in ISO 4217 format - Allowed values: `EUR`, `AED`, `AFN`, `XCD`, `ALL`, `AMD`, `AOA`, `ARS`, `USD`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `XOF`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BRL`, `BSD`, `INR`, `NOK`, `BWP`, `BYR`, `BZD`, `CAD`, `CDF`, `XAF`, `CHF`, `NZD`, `CLP`, `CNY`, `COP`, `CRC`, `CUP`, `CVE`, `ANG`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `MAD`, `ERN`, `ETB`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HUF`, `IDR`, `ILS`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `ZAR`, `LYD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRO`, `MUR`, `MVR`, `MWK`, `MXN`, `MYR`, `MZN`, `XPF`, `NGN`, `NIO`, `NPR`, `OMR`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `STD`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `UYU`, `UZS`, `VEF`, `VND`, `VUV`, `WST`, `YER`, `ZMW`, `ZWL`, `HRK` - `account_holder_id` (string, optional, nullable) — The unique ID of the account holder. Unsetting it will disable [categorization](/enrichment/categories). - `location` (LocationInput, optional, nullable) — Location of where the transaction has taken place. This can greatly improve entity identification, especially under ambiguity. ## Response ### 200 Enriched transactions. - `created_at` (datetime, required) — The timestamp of when the account holder was created. - `id` (string, required) — A unique identifier for the transaction. If two transactions are submitted with the same `id` the most recent one will replace the previous one. - `entities` (Entities, optional, nullable) — Entities found by identity identification - `categories` (Categories, optional, nullable) - `location` (Location, optional, nullable) - `error` (TransactionError, optional, nullable) ## Errors ### 422 Unprocessable Entity Error Validation Error - `detail` (list of ValidationError, optional) ## Types ### LocationInput Location of where the transaction has taken place. This can greatly improve entity identification, especially under ambiguity. - `raw_address` (string, optional, nullable) — An unstructured string containing the address - `country` (enum, optional, nullable) — The country where the transaction was made in ISO 3166-2 format - Allowed values: `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AO`, `AR`, `AS`, `AT`, `AU`, `AW`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BL`, `BM`, `BN`, `BO`, `BQ`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CU`, `CV`, `CW`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `ME`, `MF`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RS`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `SS`, `ST`, `SV`, `SX`, `SY`, `SZ`, `TC`, `TD`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW` ### Entities Entities found by identity identification - `counterparty` (Counterparty, optional, nullable) - `intermediaries` (list of Intermediary, optional) ### Categories - `general` (string, required, nullable) — The category of the transaction. View the valid set of categories for your key [here](../../../categories). - `accounting` (enum, optional, nullable) — The corresponding accounting category. Only available for `business` transactions. - Allowed values: `operational expenses`, `cost of goods sold`, `revenue`, `financing`, `taxes`, `investing`, `not enough information` ### Location - `raw_address` (string, optional, nullable) — An unstructured string containing the address - `structured` (LocationStructured, optional, nullable) — When raw is set, a structured representation of it. ### TransactionError - `code` (enum, required) - Allowed values: `account_holder_not_found`, `internal_error` - `message` (string, required) ### ValidationError - `loc` (list of ValidationErrorLocItems, required) - `msg` (string, required) - `type` (string, required) ### Counterparty - `type` (enum, required) - Allowed values: `person`, `organization` - `id` (string, optional, nullable) — The unique UUID identifier of the entity - `name` (string, optional, nullable) — The name of the entity - `website` (string, optional, nullable) — The website URL of the entity - `phone_number` (string, optional, nullable) — The phone number of the entity. This is a premium feature, please contact support to enable it. - `tax_number` (string, optional, nullable) — The tax number of the entity. This is a premium feature, please contact support to enable it. - `naics2017` (string, optional, nullable) — The 2017 NAICS code of the entity. This is a premium feature, please contact support to enable it. - `logo` (string, optional, nullable) — Logo's URL - `mccs` (list of integer, optional) — A list of [Merchant Category Codes](https://en.wikipedia.org/wiki/Merchant_category_code) - `parent` (EntityParent, optional, nullable) — The parent entity ### Intermediary - `id` (string, optional, nullable) — The unique UUID identifier of the entity - `name` (string, optional, nullable) — The name of the entity - `website` (string, optional, nullable) — The website URL of the entity - `phone_number` (string, optional, nullable) — The phone number of the entity. This is a premium feature, please contact support to enable it. - `tax_number` (string, optional, nullable) — The tax number of the entity. This is a premium feature, please contact support to enable it. - `naics2017` (string, optional, nullable) — The 2017 NAICS code of the entity. This is a premium feature, please contact support to enable it. - `logo` (string, optional, nullable) — Logo's URL - `mccs` (list of integer, optional) — A list of [Merchant Category Codes](https://en.wikipedia.org/wiki/Merchant_category_code) - `parent` (EntityParent, optional, nullable) — The parent entity ### LocationStructured - `street` (string, optional, nullable) — The street name of the location - `city` (string, optional, nullable) — The city where the location is situated - `state` (string, optional, nullable) — The state or region of the location - `postcode` (string, optional, nullable) — The postal code or ZIP code of the location - `country_code` (string, optional, nullable) — The country code of the location in ISO 3166-2 format - `country` (string, optional, nullable) — The full name of the country - `house_number` (string, optional, nullable) — The house number if, applicable - `latitude` (double, optional, nullable) — The latitude coordinate of the location - `longitude` (double, optional, nullable) — The longitude coordinate of the location - `google_maps_url` (string, optional, nullable) — A URL link to view the location on Google Maps - `apple_maps_url` (string, optional, nullable) — A URL link to view the location on Apple Maps - `store_number` (string, optional, nullable) — A unique identifier for a specific store or branch, if applicable ### ValidationErrorLocItems ### EntityParent - `id` (string, optional, nullable) — The unique UUID identifier of the entity - `name` (string, optional, nullable) — The name of the entity - `website` (string, optional, nullable) — The website URL of the entity - `phone_number` (string, optional, nullable) — The phone number of the entity. This is a premium feature, please contact support to enable it. - `tax_number` (string, optional, nullable) — The tax number of the entity. This is a premium feature, please contact support to enable it. - `naics2017` (string, optional, nullable) — The 2017 NAICS code of the entity. This is a premium feature, please contact support to enable it. ## Examples **Request** ```json { "id": "xbx8YP14g565Xk", "description": "SQ* STARBUCKS 10 Union Sq", "date": "2024-03-30", "amount": 10, "entry_type": "outgoing", "currency": "USD", "account_holder_id": "35b927b6-6fda-40aa-93b8-95b47c2b2cad", "location": { "country": "US" } } ``` **Response** ```json { "created_at": "2024-03-30T00:00:00", "id": "xbx8YP14g565Xk", "entities": { "counterparty": { "type": "organization", "id": "d4bc3c80-ec1a-3da2-836e-2a4ca4758be5", "name": "Starbucks", "website": "starbucks.com", "phone_number": "+1 4153753176", "tax_number": "80-0429876", "naics2017": "541519", "logo": "https://logos.ntropy.com/starbucks.com", "mccs": [ 5814 ] }, "intermediaries": [ { "id": "916bc837-55ef-3106-88f6-5a8269ca9f2a", "name": "Square, Inc.", "website": "squareup.com", "logo": "https://logos.ntropy.com/squareup.com", "mccs": [] } ] }, "categories": { "general": "coffee shop" }, "location": { "raw_address": "10 Union Square E, New York, New York 10003, United States", "structured": { "street": "Union Square East", "city": "New York", "state": "New York", "postcode": "10003", "country_code": "US", "country": "United States", "house_number": "10", "latitude": 40.734834, "longitude": -73.989782, "google_maps_url": "https://www.google.com/maps/search/?api=1&query=40.734834,-73.989782", "apple_maps_url": "https://maps.apple.com/?q=40.734834,-73.989782" } } } ``` **SDK Code** ```python Python SDK from ntropy_sdk import SDK sdk = SDK("cd1H...Wmhl") enriched = sdk.transactions.create( id="xbx8YP14g565Xk", description="SQ* STARBUCKS 10 Union Sq", account_holder_id="35b927b6-6fda-40aa-93b8-95b47c2b2cad", amount=10.0, entry_type="outgoing", date="2024-03-30", currency="USD", location=dict(country="US"), ) ``` ```javascript const url = 'https://api.ntropy.com/v3/transactions'; const options = { method: 'POST', headers: {'X-Api-Key': '', 'Content-Type': 'application/json'}, body: '{"id":"xbx8YP14g565Xk","description":"SQ* STARBUCKS 10 Union Sq","date":"2024-03-30","amount":10,"entry_type":"outgoing","currency":"USD","account_holder_id":"35b927b6-6fda-40aa-93b8-95b47c2b2cad","location":{"country":"US"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ntropy.com/v3/transactions" payload := strings.NewReader("{\n \"id\": \"xbx8YP14g565Xk\",\n \"description\": \"SQ* STARBUCKS 10 Union Sq\",\n \"date\": \"2024-03-30\",\n \"amount\": 10,\n \"entry_type\": \"outgoing\",\n \"currency\": \"USD\",\n \"account_holder_id\": \"35b927b6-6fda-40aa-93b8-95b47c2b2cad\",\n \"location\": {\n \"country\": \"US\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Api-Key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ntropy.com/v3/transactions") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-Api-Key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"id\": \"xbx8YP14g565Xk\",\n \"description\": \"SQ* STARBUCKS 10 Union Sq\",\n \"date\": \"2024-03-30\",\n \"amount\": 10,\n \"entry_type\": \"outgoing\",\n \"currency\": \"USD\",\n \"account_holder_id\": \"35b927b6-6fda-40aa-93b8-95b47c2b2cad\",\n \"location\": {\n \"country\": \"US\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ntropy.com/v3/transactions") .header("X-Api-Key", "") .header("Content-Type", "application/json") .body("{\n \"id\": \"xbx8YP14g565Xk\",\n \"description\": \"SQ* STARBUCKS 10 Union Sq\",\n \"date\": \"2024-03-30\",\n \"amount\": 10,\n \"entry_type\": \"outgoing\",\n \"currency\": \"USD\",\n \"account_holder_id\": \"35b927b6-6fda-40aa-93b8-95b47c2b2cad\",\n \"location\": {\n \"country\": \"US\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.ntropy.com/v3/transactions', [ 'body' => '{ "id": "xbx8YP14g565Xk", "description": "SQ* STARBUCKS 10 Union Sq", "date": "2024-03-30", "amount": 10, "entry_type": "outgoing", "currency": "USD", "account_holder_id": "35b927b6-6fda-40aa-93b8-95b47c2b2cad", "location": { "country": "US" } }', 'headers' => [ 'Content-Type' => 'application/json', 'X-Api-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ntropy.com/v3/transactions"); var request = new RestRequest(Method.POST); request.AddHeader("X-Api-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"id\": \"xbx8YP14g565Xk\",\n \"description\": \"SQ* STARBUCKS 10 Union Sq\",\n \"date\": \"2024-03-30\",\n \"amount\": 10,\n \"entry_type\": \"outgoing\",\n \"currency\": \"USD\",\n \"account_holder_id\": \"35b927b6-6fda-40aa-93b8-95b47c2b2cad\",\n \"location\": {\n \"country\": \"US\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-Api-Key": "", "Content-Type": "application/json" ] let parameters = [ "id": "xbx8YP14g565Xk", "description": "SQ* STARBUCKS 10 Union Sq", "date": "2024-03-30", "amount": 10, "entry_type": "outgoing", "currency": "USD", "account_holder_id": "35b927b6-6fda-40aa-93b8-95b47c2b2cad", "location": ["country": "US"] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ntropy.com/v3/transactions")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```