Push Transactions (BYO data)

POST/users/{user_id}/connections/{connection_id}/transactions

Ingest a batch of raw transactions into an external connection for HSA-eligibility enrichment. Idempotent on external_transaction_id within the connection: re-pushed ids update the stored transaction and re-adjudicate. Returns 202. Enrichment results arrive via transactions.ingested webhooks and are read from /users/{user_id}/expenses. Requires the ingest key scope, a write scope with no product counterpart, so read-only keys can never push data. Calling this on a Sail-managed connection returns 409 connection_not_external.

Path Parameters

user_idstringrequired

The Sail user id.

connection_idstringrequired

The Sail connection id.

Body application/json

transactionsobject[]required

Batch of transactions to ingest, up to 500 per request.

Show transactions properties

external_transaction_idstringrequired

Customer’s stable id for this transaction. Idempotency key within the connection.

datestring<date>required

Transaction date.

amountnumber<float>required

Positive decimal; purchases only.

descriptionstringrequired

Raw bank descriptor.

merchant_namestring

Merchant name, if known. Null otherwise.

mccstring

Merchant category code, if known.

currencystring

ISO 4217 currency code.

Response

Batch accepted for enrichment.

statusstring

The batch’s processing status.

job_idstring

Identifier for tracking this ingestion job.

acceptedinteger

New transactions queued for enrichment.

duplicates_updatedinteger

Rows whose external_transaction_id already existed; updated and re-adjudicated.

connection_not_external: transactions can only be pushed to external connections.

Standard error envelope covering 400, 401, 403, 404, 429, and 500.

errorobject

The error detail.

Show error properties

codestring

Machine-readable code, e.g. not_found, token_scope_mismatch, product_not_enabled, insufficient_key_scope, insufficient_token_scope, user_token_required, user_token_expired, invalid_user_token, invalid_key_configuration, connection_not_reconnectable, rate_limited.

messagestring

Human-readable error message. May change, so match on error.code instead.

paramstring

The request field that caused the error, when applicable. Null otherwise.

curl -X POST "https://live.savewithsail.com/api/v1/users/<user_id>/connections/<connection_id>/transactions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -d '{ "transactions": [ { "external_transaction_id": "acme-tx-1001", "date": "2024-01-01", "amount": 0, "description": "WALGREENS #4821 RX", "merchant_name": "string", "mcc": "string", "currency": "USD" } ] }'

const response = await fetch(`https://live.savewithsail.com/api/v1/users/${user_id}/connections/${connection_id}/transactions`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer <token>' }, body: JSON.stringify({ "transactions": [ { "external_transaction_id": "acme-tx-1001", "date": "2024-01-01", "amount": 0, "description": "WALGREENS #4821 RX", "merchant_name": "string", "mcc": "string", "currency": "USD" } ] }) }); const data = await response.json();

import requests response = requests.request( "POST", "https://live.savewithsail.com/api/v1/users/{user_id}/connections/{connection_id}/transactions", headers={ "Authorization": "Bearer <token>" }, json={ "transactions": [ { "external_transaction_id": "acme-tx-1001", "date": "2024-01-01", "amount": 0, "description": "WALGREENS #4821 RX", "merchant_name": "string", "mcc": "string", "currency": "USD" } ] }, ) data = response.json()

<?php $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "https://live.savewithsail.com/api/v1/users/<user_id>/connections/<connection_id>/transactions"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json", "Authorization: Bearer <token>"]); curl_setopt($ch, CURLOPT_POSTFIELDS, '{ "transactions": [ { "external_transaction_id": "acme-tx-1001", "date": "2024-01-01", "amount": 0, "description": "WALGREENS #4821 RX", "merchant_name": "string", "mcc": "string", "currency": "USD" } ] }'); $response = curl_exec($ch); curl_close($ch);

package main import ( "fmt" "io" "net/http" "strings" ) func main() { req, _ := http.NewRequest("POST", "https://live.savewithsail.com/api/v1/users/<user_id>/connections/<connection_id>/transactions", strings.NewReader(`{ "transactions": [ { "external_transaction_id": "acme-tx-1001", "date": "2024-01-01", "amount": 0, "description": "WALGREENS #4821 RX", "merchant_name": "string", "mcc": "string", "currency": "USD" } ] }`)) req.Header.Set("Content-Type", "application/json") req.Header.Set("Authorization", "Bearer <token>") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) }

HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://live.savewithsail.com/api/v1/users/<user_id>/connections/<connection_id>/transactions")) .header("Content-Type", "application/json") .header("Authorization", "Bearer <token>") .method("POST", HttpRequest.BodyPublishers.ofString("{\n \"transactions\": [\n {\n \"external_transaction_id\": \"acme-tx-1001\",\n \"date\": \"2024-01-01\",\n \"amount\": 0,\n \"description\": \"WALGREENS #4821 RX\",\n \"merchant_name\": \"string\",\n \"mcc\": \"string\",\n \"currency\": \"USD\"\n }\n ]\n}")) .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());

require "net/http" require "uri" uri = URI("https://live.savewithsail.com/api/v1/users/<user_id>/connections/<connection_id>/transactions") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = uri.scheme == "https" request = Net::HTTP::Post.new(uri) request["Content-Type"] = "application/json" request["Authorization"] = "Bearer <token>" request.body = "{\n \"transactions\": [\n {\n \"external_transaction_id\": \"acme-tx-1001\",\n \"date\": \"2024-01-01\",\n \"amount\": 0,\n \"description\": \"WALGREENS #4821 RX\",\n \"merchant_name\": \"string\",\n \"mcc\": \"string\",\n \"currency\": \"USD\"\n }\n ]\n}" response = http.request(request) puts response.body