> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ntropy.com/documentation/api/batches/post-batch-v-3-batches-post/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ntropy.com/_mcp/server. # Submit a batch of requests POST https://api.ntropy.com/v3/batches Content-Type: application/json Creates a batch of requests and runs them asynchronously. Each element of `data` has to be compatible with the body expected by the `operation`. A batch representing the progress and the status of the process is returned as a result. You can retrieve the results using [/v3/batches/:id/results](./get-batch-results) once the batch has finished processing. This endpoints supports up to 24960 requests. Complete guide: [Batches](../../../batches). Reference: https://docs.ntropy.com/documentation/api/batches/post-batch-v-3-batches-post ## Authentication - `X-Api-Key` header (required) — API Key authentication via header ## Request ### Body (application/json) This endpoint expects a BatchInput. - `operation` (enum, required) - Allowed values: `POST /v3/transactions` - `data` (list of TransactionInput, required) ## Response ### 200 Successful Response - `id` (string, required) — A unique identifier for the batch. - `operation` (enum, required) - Allowed values: `POST /v3/transactions` - `status` (enum, required) — The status of the batch. Results are not available for a batch with an error status. - Allowed values: `processing`, `completed`, `error` - `created_at` (datetime, required) — The timestamp of when the batch was created. - `updated_at` (datetime, required) — The timestamp of when the batch was last updated. - `progress` (integer, required) — The number of transactions processed so far. - `total` (integer, required) — The total number of transactions in the batch. ## Errors ### 422 Unprocessable Entity Error Validation Error - `detail` (list of ValidationError, optional) ## Types ### 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. ### ValidationError - `loc` (list of ValidationErrorLocItems, required) - `msg` (string, required) - `type` (string, required) ### 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` ### ValidationErrorLocItems ## Examples ### Example_0 **Request** ```json { "body": { "operation": "POST /v3/transactions", "data": [ { "id": "txn_9f8b7c6d5e4a3b2c", "description": "Amazon Marketplace Purchase", "date": "2024-04-10", "amount": 59.99, "entry_type": "outgoing", "currency": "USD" } ] } } ``` **Response** ```json { "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ef", "operation": "POST /v3/transactions", "status": "processing", "created_at": "2024-04-11T08:15:00Z", "updated_at": "2024-04-11T08:15:30Z", "progress": 1, "total": 1 } ``` **SDK Code** ```python Example_0 import requests url = "https://api.ntropy.com/v3/batches" payload = { "body": { "operation": "POST /v3/transactions", "data": [ { "id": "txn_9f8b7c6d5e4a3b2c", "description": "Amazon Marketplace Purchase", "date": "2024-04-10", "amount": 59.99, "entry_type": "outgoing", "currency": "USD" } ] } } headers = { "X-Api-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Example_0 const url = 'https://api.ntropy.com/v3/batches'; const options = { method: 'POST', headers: {'X-Api-Key': '', 'Content-Type': 'application/json'}, body: '{"body":{"operation":"POST /v3/transactions","data":[{"id":"txn_9f8b7c6d5e4a3b2c","description":"Amazon Marketplace Purchase","date":"2024-04-10","amount":59.99,"entry_type":"outgoing","currency":"USD"}]}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Example_0 package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ntropy.com/v3/batches" payload := strings.NewReader("{\n \"body\": {\n \"operation\": \"POST /v3/transactions\",\n \"data\": [\n {\n \"id\": \"txn_9f8b7c6d5e4a3b2c\",\n \"description\": \"Amazon Marketplace Purchase\",\n \"date\": \"2024-04-10\",\n \"amount\": 59.99,\n \"entry_type\": \"outgoing\",\n \"currency\": \"USD\"\n }\n ]\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 Example_0 require 'uri' require 'net/http' url = URI("https://api.ntropy.com/v3/batches") 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 \"body\": {\n \"operation\": \"POST /v3/transactions\",\n \"data\": [\n {\n \"id\": \"txn_9f8b7c6d5e4a3b2c\",\n \"description\": \"Amazon Marketplace Purchase\",\n \"date\": \"2024-04-10\",\n \"amount\": 59.99,\n \"entry_type\": \"outgoing\",\n \"currency\": \"USD\"\n }\n ]\n }\n}" response = http.request(request) puts response.read_body ``` ```java Example_0 import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ntropy.com/v3/batches") .header("X-Api-Key", "") .header("Content-Type", "application/json") .body("{\n \"body\": {\n \"operation\": \"POST /v3/transactions\",\n \"data\": [\n {\n \"id\": \"txn_9f8b7c6d5e4a3b2c\",\n \"description\": \"Amazon Marketplace Purchase\",\n \"date\": \"2024-04-10\",\n \"amount\": 59.99,\n \"entry_type\": \"outgoing\",\n \"currency\": \"USD\"\n }\n ]\n }\n}") .asString(); ``` ```php Example_0 request('POST', 'https://api.ntropy.com/v3/batches', [ 'body' => '{ "body": { "operation": "POST /v3/transactions", "data": [ { "id": "txn_9f8b7c6d5e4a3b2c", "description": "Amazon Marketplace Purchase", "date": "2024-04-10", "amount": 59.99, "entry_type": "outgoing", "currency": "USD" } ] } }', 'headers' => [ 'Content-Type' => 'application/json', 'X-Api-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp Example_0 using RestSharp; var client = new RestClient("https://api.ntropy.com/v3/batches"); var request = new RestRequest(Method.POST); request.AddHeader("X-Api-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"body\": {\n \"operation\": \"POST /v3/transactions\",\n \"data\": [\n {\n \"id\": \"txn_9f8b7c6d5e4a3b2c\",\n \"description\": \"Amazon Marketplace Purchase\",\n \"date\": \"2024-04-10\",\n \"amount\": 59.99,\n \"entry_type\": \"outgoing\",\n \"currency\": \"USD\"\n }\n ]\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Example_0 import Foundation let headers = [ "X-Api-Key": "", "Content-Type": "application/json" ] let parameters = ["body": [ "operation": "POST /v3/transactions", "data": [ [ "id": "txn_9f8b7c6d5e4a3b2c", "description": "Amazon Marketplace Purchase", "date": "2024-04-10", "amount": 59.99, "entry_type": "outgoing", "currency": "USD" ] ] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ntropy.com/v3/batches")! 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() ``` ### cURL **SDK Code** ```python Python SDK from ntropy_sdk import SDK sdk = SDK("cd1H...Wmhl") batch = sdk.batches.create( operation="POST /v3/transactions", data=[ { "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": { "country": "US", }, } ], ) ``` ```javascript cURL const url = 'https://api.ntropy.com/v3/batches'; const options = {method: 'POST', headers: {'X-Api-Key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go cURL package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ntropy.com/v3/batches" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("X-Api-Key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby cURL require 'uri' require 'net/http' url = URI("https://api.ntropy.com/v3/batches") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-Api-Key"] = '' response = http.request(request) puts response.read_body ``` ```java cURL import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ntropy.com/v3/batches") .header("X-Api-Key", "") .asString(); ``` ```php cURL request('POST', 'https://api.ntropy.com/v3/batches', [ 'headers' => [ 'X-Api-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp cURL using RestSharp; var client = new RestClient("https://api.ntropy.com/v3/batches"); var request = new RestRequest(Method.POST); request.AddHeader("X-Api-Key", ""); IRestResponse response = client.Execute(request); ``` ```swift cURL import Foundation let headers = ["X-Api-Key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ntropy.com/v3/batches")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers 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() ```