Era API दस्तावेज़

अभी भी बीटा में

ये एंडपॉइंट आज काम करते हैं, लेकिन API अभी भी बदल रहा है, इसलिए कुछ जानकारी बदल सकती है। यह पेज आख़िरी बार कब अपडेट हुआ, यह जानने के लिए ऊपर दी गई 'आख़िरी अपडेट' तारीख़ देखें।

क्विकस्टार्ट

शुरू करने से पहले आपको एक Era अकाउंट चाहिए जिसमें कम से कम एक संस्थान जुड़ा हो — कनेक्शन के बिना इन एंडपॉइंट के पास लौटाने को कुछ नहीं होगा।

1
Era में साइन इन करें और अगर पहले से नहीं किया है तो कोई संस्थान जोड़ें।
2
डैशबोर्ड में अपनी API कीज़ खोलें और एक की बनाएं। शुरुआत में हर स्कोप पर निशान लगा होता है, इसलिए जो नहीं चाहिए उनसे निशान हटा दें — इन एंडपॉइंट के लिए banking:read बचता है। एक्सपायरी भी आप चुनते हैं; कभी न ख़त्म होने वाला विकल्प है ही नहीं।
3
की कॉपी कर लें। वह एक ही बार दिखती है, और हम दोबारा नहीं दिखा सकते। इसे कॉपी करके किसी सुरक्षित जगह रखें, जैसे किसी सीक्रेट्स मैनेजर में। अगर की खो जाए, तो आप उसे दोबारा नहीं देख सकते। इसकी जगह एक नई की बनाएँ।
4
अपनी रिक्वेस्ट के साथ उसे हेडर में भेजें।

cURL

curl "https://forge.era.app/api/banking/transactions?page=1&pageSize=20" \
  -H "X-API-Key: fmk_your_key_here"

रिस्पॉन्स · 200

{
  "transactions": [ … ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 412,
    "totalPages": 21
  },
  "historyWindowApplied": true,
  "historyWindowFloorDate": "2026-06-28",
  "historyWindowHiddenCount": 137,
  "historyWindowEarliestDate": "2024-03-02",
  "historyWindowDegraded": false
}

की बनाएं

उपलब्ध API

Era API में निम्नलिखित API शामिल हैं:

GET/banking/accounts
आपके हर जुड़े हुए संस्थान में, हर वह अकाउंट जिसे आप देख सकते हैं।
GET/banking/accounts/{accountId}/balance
एक अकाउंट का बैलेंस, देनदारी होने पर क्रेडिट से जुड़े फ़ील्ड सहित।
GET/banking/accounts/summary
आप जो भी अकाउंट देख सकते हैं, उन सबका कुल जोड़।
GET/banking/transactions
आपके ट्रांज़ैक्शन, एक बार में एक पेज।
PUT/banking/transactions/{id}
एक ट्रांज़ैक्शन बदलें
PUT/banking/transactions/bulk
एक साथ 100 तक बदलें
GET/banking/categories
पूरा कैटेगरी ढांचा, सब-कैटेगरी भी नेस्टेड।
POST/banking/categories
कैटेगरी जोड़ें
GET/banking/tags
आपके अकाउंट के सभी टैग, एक ही रिस्पॉन्स में।
POST/banking/tags
टैग बनाएँ

प्रमाणीकरण

अपनी की इन दो तरीकों में से किसी एक से भेजें:

ऑथेंटिकेशन के तरीके
तरीका	क्रेडेंशियल
हेडर	X-API-Key: fmk_your_key_here
बियरर टोकन	Authorization: Bearer fmk_your_key_here

हर रिक्वेस्ट TLS से एन्क्रिप्टेड होती है।

कीज़ ख़त्म होती हैं, और कितनी जल्दी — यह आप बनाते वक़्त चुनते हैं। ज़्यादा से ज़्यादा मुफ़्त प्लान पर 90 दिन और पेड प्लान पर 365 दिन। कभी न ख़त्म होने वाला विकल्प नहीं है, इसलिए इस पर बनाई किसी भी चीज़ को की समय रहते बदलने की योजना चाहिए।

रिस्पॉन्स हेडर

हर रिस्पॉन्स में यह शामिल होता है:

रिस्पॉन्स हेडर
हेडर	विवरण
fly-request-id	रिक्वेस्ट की एक यूनीक पहचान। किसी ख़ास रिक्वेस्ट के बारे में सपोर्ट से बात करते समय इसे बताएं। देखें: रिक्वेस्ट ID

एरर

यह API ये एरर स्टेटस कोड लौटाता है:

400
गलत इनपुट: कोई ग़लत पैरामीटर, खाली या 100 से ज़्यादा आइटम वाला बल्क अपडेट, या ऐसा राइट जो एक ही कॉल में एक ही फ़ील्ड को सेट भी करे और क्लियर भी।
401
की नहीं है, या ऐसी की जो पार्स नहीं होती। इसे X-API-Key हेडर या बियरर टोकन के रूप में भेजें।
402
प्लान का कोटा आड़े आ रहा है — आज के लिए, यह सिर्फ़ कैटेगरी बनाने पर लागू होता है।
403
की के पास इस कॉल को चाहिए वाला स्कोप नहीं है — या, दोनों ट्रांज़ैक्शन राइट में से किसी एक में, id किसी और की है या सिरे से मौजूद ही नहीं है। API इन दोनों में फ़र्क़ नहीं बताता।
409
आप लिख ही रहे थे कि किसी और चीज़ ने वह रो बदल दी। इसे फिर पढ़ें और अपना राइट फिर भेजें।

एरर के फ़ॉर्मेट

हर एरर एक ही फ़ॉर्मेट में लौटता है: statusCode, message, और एक errors ऑब्जेक्ट जो बताता है कि क्या गड़बड़ थी। गुम या अमान्य की के साथ बिना किसी बॉडी के भी जवाब आ सकता है।

उदाहरण

{
  "statusCode": 403,
  "message": "One or more errors occurred!",
  "errors": {
    "generalErrors": ["Transaction does not belong to the authenticated user"]
  }
}

रिक्वेस्ट ID

हर रिस्पॉन्स में एक fly-request-id हेडर होता है। किसी ख़ास रिक्वेस्ट के बारे में सपोर्ट से बात करते समय इसे बताएं।

cURL

# Print the response headers, including fly-request-id; discard the body
curl -sS -D - -o /dev/null "https://forge.era.app/api/banking/transactions?page=1&pageSize=20" \
  -H "X-API-Key: fmk_your_key_here"

cURL (राइट कॉल)

# A write call: same header, plus a JSON body
curl -sS -D - -X PUT "https://forge.era.app/api/banking/transactions/utgr_your_transaction_id" \
  -H "X-API-Key: fmk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"categoryKey": "fcat_dining", "merchantName": "Corner Cafe"}'

आम एरर

एक ही राइट में किसी फ़ील्ड को सेट करना और क्लियर करना — 400।
बल्क अपडेट में 100 से ज़्यादा id — 400, और कुछ नहीं बदलता। एक से कम भी वैसा ही है।
ऐसा ट्रांज़ैक्शन जो आपका नहीं है, या सिरे से मौजूद ही नहीं — 403, कभी 404 नहीं। यानी रिस्पॉन्स कभी नहीं बताता कि कोई id मौजूद है या नहीं, बस इतना बताता है कि वह आपकी नहीं है।
किसी और चीज़ ने पहले ही वह रो बदल दी — 409।

लिमिट

डॉक्यूमेंटेड दस एंडपॉइंट्स में से दो, एक कॉल में आप कितना मांग सकते हैं इस पर सीमा लगाते हैं। बाकी आठ नहीं लगाते।

इसका मतलब असीमित नहीं है: कीज़ अभी भी ख़त्म होती हैं, राइट्स पर अभी भी फ़ील्ड-लंबाई की सीमाएं हैं, और आपका प्लान अभी भी पुराना इतिहास छुपा सकता है। इनमें से कुछ भी रेट लिमिट नहीं है — नीचे देखें।

अकाउंट्स, बैलेंस, समरी, कैटेगरीज़, टैग्स, और सिंगल-ट्रांज़ेक्शन राइट पर कोई पर-कॉल वॉल्यूम सीमा नहीं है। आपको पूरा सेट वापस मिलता है, या वही एक रो जो आपने नाम से मांगी।
pageSize को मना नहीं किया जाता, 100 पर सीमित कर दिया जाता है। ज़्यादा माँगें तो भी आपको 200 के साथ 100 रो मिलेंगी — जो भेजा उस पर भरोसा करने की बजाय रिस्पॉन्स में pagination.pageSize पढ़ें।
ट्रांज़ैक्शन का बल्क राइट 100 id पर सीमित है, और pageSize से उलट इसे सीमित नहीं, मना कर दिया जाता है: 101 भेजें तो 400 मिलेगा और कुछ नहीं बदलेगा।
की बनाते समय आपके चुने शेड्यूल पर एक्सपायर होती है — फ़्री प्लान पर ज़्यादा से ज़्यादा 90 दिन, पेड प्लान पर 365 दिन। कभी न एक्सपायर होने का कोई विकल्प नहीं है।
आपका प्लान एक हिस्ट्री-विंडो फ़्लोर लगा सकता है जो पुराने ट्रांज़ैक्शन छुपा देता है। ट्रांज़ैक्शन के रिस्पॉन्स में historyWindow फ़ील्ड होते हैं जो बताते हैं कि कोई फ़्लोर लागू हुआ या नहीं और कहाँ।
प्लान एक API-रिक्वेस्ट भत्ता भी बताते हैं — फ़्री प्लान पर 500, हर पेड प्लान पर ज़्यादा।

देखें कि हर प्लान में क्या शामिल है

यहाँ जो नहीं है: आज REST पर कोई पर-रिक्वेस्ट थ्रॉटलिंग नहीं है, कोई 429 नहीं, और कोई रेट-लिमिट हेडर नहीं — यानी लीक हुई की को हमारी तरफ़ से कुछ भी धीमा नहीं करता। अगर कभी किसी की को लेकर शक हो, तो उसे रिवोक कर दें: इससे वह फ़ौरन बंद हो जाती है (ऊपर सिक्योरिटी एंड की हैंडलिंग देखें)। और, क्योंकि यह API बीटा में है, यह मत मान लीजिए कि यह हमेशा ऐसा ही रहेगा।

आम तौर-तरीक़े

रिस्पॉन्स के फ़ील्ड camelCase में होते हैं। क्वेरी पैरामीटर छोटे-बड़े अक्षर का फ़र्क़ नहीं देखते, इसलिए वहाँ भी camelCase चल जाता है — प्रकाशित स्पेक उन्हें PascalCase में लिखता है, इसीलिए आपको दोनों रूप दिखते हैं।

जो फ़ील्ड कैलेंडर का एक दिन बताता है, वह YYYY-MM-DD में होता है। जो फ़ील्ड एक पल बताता है, वह ऑफ़सेट के साथ ISO 8601 में होता है।

पेज का आकार ठुकराया नहीं जाता, बस सीमा तक काट दिया जाता है। pageSize में 500 माँगिए और आपको 100 पंक्तियाँ और एक 200 मिलेगा, कोई एरर नहीं — इसलिए जो भेजा उस पर भरोसा करने के बजाय pagination.pageSize वापस पढ़िए।

किसी रिस्पॉन्स में ऐसे फ़ील्ड आ सकते हैं जो इस पेज पर गिनाए नहीं गए। जिन्हें आप नहीं पहचानते, उन पर अटकने के बजाय उन्हें छोड़ दीजिए — यही वह बात है जो API के बढ़ते जाने पर भी आपके क्लाइंट को चलता रखती है।

REST सादा HTTP है, इसलिए इसे कॉल करने के लिए किसी SDK की ज़रूरत नहीं — HTTP क्लाइंट वाली कोई भी भाषा काफ़ी है। इंस्टॉल करने को कुछ नहीं है।

सुरक्षा और की प्रबंधन

एजेंट को मंज़ूरी देने से एक की बनती है

जब आप OAuth से किसी एजेंट को मंज़ूरी देते हैं, Era उसके लिए एक API की बना देता है। वह उसी डैशबोर्ड सूची में आती है जिसमें आपकी बनाई कीज़ हैं, और नाम Era ख़ुद क्लाइंट के नाम से बनाता है।

नाम कैसे बनता है

Auto -- Claude

उसमें ठीक वही स्कोप होते हैं जो आपने उस स्क्रीन पर मंज़ूर किए थे, और कुछ नहीं। डैशबोर्ड से उसे रद्द करें, और एजेंट तब तक आपके अकाउंट तक नहीं पहुँच पाएगा जब तक आप उसे दोबारा मंज़ूर न करें।

सादे REST कॉल लॉग नहीं होते

की बनाना और रद्द करना, दोनों आपके एक्टिविटी लॉग में दिखते हैं, और एजेंट MCP पर जो भी टूल कॉल करता है वह भी। हर REST कॉल अलग से नहीं दिखता — चाहे रीड हो या राइट — आज उस रास्ते पर हर रिक्वेस्ट का कोई लॉग नहीं है।

किसी की पर कभी शक हो तो उसे रद्द कर दीजिए। रद्द करना तुरंत लागू होता है, REST और MCP दोनों पर उस की को काट देता है, और नई बनाने में एक मिनट लगता है।

की पर भरोसा करने से पहले जान लेने लायक कुछ और बातें।
बात	इसका मतलब
स्कोप मोटे हैं	banking:read इस पेज की छह रीड से कहीं ज़्यादा कवर करता है — यही स्कोप आपके अकाउंट की बाक़ी रीड भी कवर करता है — बैलेंस, होल्डिंग, कनेक्शन, ख़र्च। एक ही स्कोप, इससे संकरा विकल्प है ही नहीं। लिखने वाले स्कोप भी उतने ही सूची में हैं जितने पढ़ने वाले — इसलिए किसी भी की को पासवर्ड की तरह संभालें। वह आपके पूरे अकाउंट की तरह काम करती है, किसी हिस्से की तरह नहीं। banking:write कैटेगरी, टैग और ट्रांज़ैक्शन के मेटाडेटा बदल सकता है, मैन्युअल अकाउंट और बैलेंस मैनेज कर सकता है, और इंस्टीट्यूशन कनेक्ट या डिसकनेक्ट कर सकता है — इस पेज का कोई भी स्कोप आपके बैंक अकाउंट्स के बीच पैसे नहीं भेज सकता।
स्कोप अपडेट नहीं होते	की के स्कोप बनाते वक़्त तय हो जाते हैं और बाद में कभी नहीं बदलते। जो चीज़ किसी स्कोप में तो आती है पर अभी चालू नहीं हुई, उसके लिए यह मायने रखता है: आज social:write दे दिया, तो जिस दिन साझा व्यू आएंगे उस दिन भी वह की उसे लिए बैठी होगी। जो आज इस्तेमाल कर रहे हैं वही दीजिए, जो शायद कभी करें वह नहीं।
मंज़ूरी की ज़रूरत नहीं	आप पहले से ही अपने अकाउंट में लॉग-इन हैं, इसलिए की बनाने के लिए किसी और की मंज़ूरी नहीं चाहिए — न कोई समीक्षा है, न प्रतीक्षा सूची, और Era में कोई आपके अनुरोध को मंज़ूरी नहीं देता। यह बनते ही आपके एक्टिविटी लॉग में दर्ज हो जाता है, तो कोई अनजान की आसानी से नज़र आ जाती है।
बैंक लॉगिन की पहुँच से बाहर रहता है	की आपके बैंक लॉगिन तक नहीं पहुँच सकती, क्योंकि Era के पास वह होता ही नहीं। आप उसे डेटा प्रदाता के चलाए कनेक्शन फ़्लो में डालते हैं, Era की किसी स्क्रीन पर नहीं — उसके बाद Era के पास रहता है सिर्फ़ हर कनेक्शन का एक एक्सेस टोकन, जो AES-256 से एन्क्रिप्टेड रहता है और संस्थान को डिस्कनेक्ट करके फेंका जा सकता है।
की हैश होती है, स्टोर नहीं	आपकी की 256 बिट का रैंडम डेटा है, जिसे स्टोर करने से पहले SHA-256 से हैश किया जाता है। हमारे पास हैश रहता है, की नहीं। खो जाए तो उसे रद्द कर के नई बना लें।

Era आपके डेटा की हिफ़ाज़त कैसे करता है

मुख्य संसाधन

अकाउंट

GET/banking/accounts

ज़रूरी स्कोप

banking:read

हर जुड़े संस्थान में फैले, वे सारे अकाउंट जो आपको दिखते हैं — और उनके बग़ल में उनकी गिनती भी जो छूट गए। हर अकाउंट अपने साथ अपना accountGroupKey लेकर आता है — वही मान जो बैलेंस वाला एंडपॉइंट अपने पाथ में लेता है — और वह connectionId भी जिससे वह जुड़ा है, इसलिए सबसे पहले यही कॉल कीजिए। connectionId लेता है ताकि आप एक ही कनेक्शन तक सीमित कर सकें, और includeExcluded ताकि आपके छिपाए हुए अकाउंट भी आ जाएँ।

क्वेरी पैरामीटर
connectionIdवैकल्पिक	सूची को एक ही कनेक्शन के अकाउंट तक सीमित करता है।
includeExcludedवैकल्पिक	टियर-एक्सक्लूडेड और छिपाए हुए अकाउंट भी शामिल करता है, उनके बैलेंस को धुंधला करके। डिफ़ॉल्ट रूप से false।

रिस्पॉन्स · 200

{
  "accounts": [
    {
      "accountGroupKey": "uagr_7f3c9a21",
      "connectionId": "ucon_4b19e02c",
      "name": "Everyday Checking",
      "currentBalance": 4820.16,
      "supportsTransactions": true,
      …
    }
  ],
  "excludedAccountCount": 1
}

जिस अकाउंट को आपने छिपाया है, या जिसे आपका प्लान बाहर रखता है, उसके बैलेंस वाले फ़ील्ड शून्य नहीं, null लौटते हैं — null का मतलब है रोक रखा गया, ख़ाली नहीं। supportsTransactions का null भी इसी भाव में है: उसका मतलब है कि Era कह नहीं सकता, यह कभी नहीं कि जवाब ना है।

अकाउंट का बैलेंस

GET/banking/accounts/{accountId}/balance

ज़रूरी स्कोप

banking:read

एक अकाउंट का बैलेंस, और अगर वह अकाउंट देनदारी है तो क्रेडिट वाले फ़ील्ड भी भरे हुए। पाथ उसी अकाउंट का accountGroupKey लेता है — वही मान जो /banking/accounts उसके लिए लौटाता है। किसी और आकार वाली की, लुकअप चलने से पहले ही ख़ारिज हो जाती है।

रिस्पॉन्स · 200

{
  "accountGroupKey": "uagr_7f3c9a21",
  "currentBalance": 4820.16,
  "availableBalance": 4712.03,
  "creditLimit": null,
  "currencyCode": "USD",
  "availableCredit": null,
  "asOf": "2026-08-11T09:32:00Z",
  "visibility": null
}

छिपाया हुआ अकाउंट हो, या वह जिसका कनेक्शन टूट चुका है — जवाब फिर भी 200 ही आता है, बस बैलेंस वाले फ़ील्ड null होते हैं। 404 सिर्फ़ तब मिलता है जब अकाउंट सचमुच है ही नहीं। यहाँ visibility फ़ील्ड पर नज़र रखिए: अकाउंट दिखता हो तो वह null है, और न दिखता हो तो tier_excluded जैसी कोई स्ट्रिंग।

अकाउंट का सार

GET/banking/accounts/summary

ज़रूरी स्कोप

banking:read

जो अकाउंट आपको दिखते हैं, उन सबका जोड़: totalAssets, totalLiabilities, और netWorthHint, जो पहले में से दूसरा घटाकर बनता है। कोई पैरामीटर नहीं लेता।

रिस्पॉन्स · 200

{
  "userId": "7d1c0b93a8e24f60",
  "accounts": [ … ],
  "totalVisibleCount": 6,
  "totalHiddenCount": 2,
  "totalAssets": 48210.75,
  "totalLiabilities": 9327.40,
  "netWorthHint": 38883.35,
  "computedAt": "2026-08-11T09:32:00Z"
}

netWorthHint सिर्फ़ इसी रिस्पॉन्स में आए अकाउंट गिनता है, इसलिए उसमें क्या छूट रहा है यह totalHiddenCount बताता है। इसे आख़िरी नेट वर्थ नहीं, शुरुआती आँकड़ा मानकर चलिए।

ट्रांज़ैक्शन

GET/banking/transactions

ज़रूरी स्कोप

banking:read

आपके ट्रांज़ैक्शन, एक बार में एक पेज, पेजिंग की गिनती के साथ लपेटकर। page और pageSize लेता है (ऊपरी सीमा 100), साथ में अकाउंट, तारीख़ की सीमा, लागू नियम और लगाए गए टैग के वैकल्पिक फ़िल्टर।

क्वेरी पैरामीटर
accountIdवैकल्पिक	एक अकाउंट के ट्रांज़ैक्शन तक सीमित करता है, उसके accountGroupKey से।
fromDateवैकल्पिक	सिर्फ़ इस तारीख़ को या उसके बाद के ट्रांज़ैक्शन।
toDateवैकल्पिक	सिर्फ़ इस तारीख़ को या उससे पहले के ट्रांज़ैक्शन।
pageवैकल्पिक	पेज नंबर, 1 से शुरू। डिफ़ॉल्ट रूप से 1।
pageSizeवैकल्पिक	प्रति पेज पंक्तियाँ। डिफ़ॉल्ट रूप से 50, 100 तक सीमित।
sortByवैकल्पिक	सॉर्ट करने का फ़ील्ड: transactionDate, amount, description, category, या merchantName।
sortDirectionवैकल्पिक	asc या desc। डिफ़ॉल्ट रूप से अवरोही।
categoryKeyवैकल्पिक	सिर्फ़ एक कैटेगरी के ट्रांज़ैक्शन, उसकी fcat_ की से।
searchवैकल्पिक	व्यापारी, विवरण, कैटेगरी, अकाउंट नाम और राशि पर फ़ुल-टेक्स्ट सर्च।
ruleIdsवैकल्पिक	सिर्फ़ वे ट्रांज़ैक्शन जिन्हें किसी ऑटोमेशन रूल ने छुआ, उस रूल की की से।
tagKeysवैकल्पिक	सिर्फ़ वे ट्रांज़ैक्शन जिन पर इनमें से कोई टैग लगा है।
reviewStatusवैकल्पिक	needs_review, reviewed, या flagged।
includeChildrenवैकल्पिक	categoryKey सेट होने पर, उसकी उप-कैटेगरी भी शामिल करता है। डिफ़ॉल्ट रूप से false।

रिस्पॉन्स · 200

{
  "transactions": [ … ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 412,
    "totalPages": 21
  },
  "historyWindowApplied": true,
  "historyWindowFloorDate": "2026-06-28",
  "historyWindowHiddenCount": 137,
  "historyWindowEarliestDate": "2024-03-02",
  "historyWindowDegraded": false
}

आपका प्लान हिस्ट्री-विंडो की एक सीमा लगा सकता है, जो उससे पुराने ट्रांज़ैक्शन छिपा देती है। रिस्पॉन्स में historyWindow वाले फ़ील्ड इसीलिए आते हैं: historyWindowApplied बताता है कि सीमा ने सचमुच कुछ छिपाया, historyWindowFloorDate बताता है वह कहाँ पड़ी, historyWindowHiddenCount बताता है उसके पीछे कितनी पंक्तियाँ हैं, और historyWindowEarliestDate बताता है कि आपकी हिस्ट्री असल में कहाँ तक जाती है। इनके बिना छोटा नतीजा उस अकाउंट से अलग नहीं दिखता जिसमें इससे पुराने ट्रांज़ैक्शन हैं ही नहीं। इनमें से दो आपका कोड बदल देते हैं: सीमा लगी होने पर भी historyWindowHiddenCount null हो सकता है, इसलिए null को शून्य नहीं, अनजान मानकर पढ़ें; और जब historyWindowDegraded true हो, तो उस कॉल पर Era आपके प्लान की पुष्टि नहीं कर पाया, इसलिए सीमा की तारीख़ तथ्य नहीं, अनुमान है। जिस पेड कॉल में प्लान की पुष्टि हो जाती है, वहाँ कोई सीमा नहीं लगती और historyWindowApplied false लौटता है।

प्लान में API अनुरोधों की सीमा भी बताई जाती है — मुफ़्त पर 500, और हर पेड प्लान पर उससे ज़्यादा। मौजूदा आँकड़े आपके प्लान की बाक़ी सीमाओं के साथ दिए गए हैं।

देखें कि हर प्लान में क्या शामिल है

एक ट्रांज़ैक्शन बदलें

किसी ट्रांज़ैक्शन पर चार चीज़ें आप ओवरराइड कर सकते हैं: उसकी कैटेगरी, व्यापारी का नाम, आपका अपना एक नोट, और उसकी समीक्षा-स्थिति। सिर्फ़ वही भेजें जो बदल रहे हैं — जो छोड़ेंगे वह जैसा है वैसा ही रहेगा। पाथ में दिया id उस ट्रांज़ैक्शन की utgr_ की है। यह डेटा बदलता है, इसलिए banking:read की जगह banking:write चाहिए।

PUT/banking/transactions/{id}

ज़रूरी स्कोप

banking:write

रिक्वेस्ट बॉडी
categoryKeyवैकल्पिक	जो कैटेगरी सौंपनी है, उसकी fcat_ की। न भेजें तो ट्रांज़ैक्शन अपनी मौजूदा कैटेगरी बनाए रखता है।
merchantNameवैकल्पिक	आपका अपना व्यापारी नाम, ज़्यादा से ज़्यादा 1000 वर्ण। न भेजें तो मौजूदा नाम बना रहता है।
descriptionवैकल्पिक	इस ट्रांज़ैक्शन पर आपका अपना नोट, ज़्यादा से ज़्यादा 5000 वर्ण। न भेजें तो मौजूदा नोट बना रहता है।
reviewStatusवैकल्पिक	इसे needs_review, reviewed, या flagged के तौर पर चिह्नित करें।
clearCategoryवैकल्पिक	आपका कैटेगरी ओवरराइड हटा देता है, ताकि Era का अपना वर्गीकरण फिर से लागू हो जाए। डिफ़ॉल्ट रूप से false।
clearMerchantNameवैकल्पिक	आपका व्यापारी-नाम ओवरराइड हटा देता है, ताकि आपके बैंक का भेजा नाम वापस आ जाए। डिफ़ॉल्ट रूप से false।
clearDescriptionवैकल्पिक	आपका विवरण ओवरराइड हटा देता है, ताकि आपके बैंक का भेजा विवरण वापस आ जाए। डिफ़ॉल्ट रूप से false।
clearReviewStatusवैकल्पिक	आपका समीक्षा-स्थिति ओवरराइड हटा देता है। डिफ़ॉल्ट रूप से false।

रिस्पॉन्स · 200

{
  "transaction": { … }
}

आपको पूरा अपडेटेड ट्रांज़ैक्शन वापस मिलता है, ठीक उसी आकार में जो ऊपर की सूची लौटाती है — यहाँ दोबारा नहीं दिखाया गया, क्योंकि यह एक बड़ा ऑब्जेक्ट है जो अभी भी बदल रहा है। एक ही कॉल में कोई फ़ील्ड सेट करना और उसे क्लियर करना 400 लौटाता है। ऐसा ट्रांज़ैक्शन जो आपका नहीं है, या है ही नहीं, 403 लौटाता है — API इन दोनों में फ़र्क़ नहीं बताता। और अगर आपके लिखते वक़्त किसी और चीज़ ने वही पंक्ति बदल दी, तो आपको 409 मिलता है: उसे दोबारा पढ़िए और दोबारा भेजिए।

एक साथ 100 तक बदलें

वही चार ओवरराइड, एक ही कॉल में ट्रांज़ैक्शन की एक सूची पर लागू। सूची के हर id को एक जैसे बदलाव मिलते हैं — हर ट्रांज़ैक्शन के लिए अलग-अलग बदलाव का कोई विकल्प नहीं है। यह डेटा बदलता है, इसलिए banking:read की जगह banking:write चाहिए।

PUT/banking/transactions/bulk

ज़रूरी स्कोप

banking:write

रिक्वेस्ट बॉडी
transactionIds	जिन ट्रांज़ैक्शन को बदलना है, उनकी utgr_ कीज़। कम से कम एक, और ज़्यादा से ज़्यादा 100। 100 से ज़्यादा होने पर काटा नहीं, ठुकराया जाता है — ऊपर वाले pageSize के उलट, आपको 400 मिलता है और कुछ भी नहीं बदलता।
categoryKeyवैकल्पिक	जो कैटेगरी सौंपनी है, उसकी fcat_ की। न भेजें तो ट्रांज़ैक्शन अपनी मौजूदा कैटेगरी बनाए रखता है।
merchantNameवैकल्पिक	आपका अपना व्यापारी नाम, ज़्यादा से ज़्यादा 1000 वर्ण। न भेजें तो मौजूदा नाम बना रहता है।
descriptionवैकल्पिक	इस ट्रांज़ैक्शन पर आपका अपना नोट, ज़्यादा से ज़्यादा 5000 वर्ण। न भेजें तो मौजूदा नोट बना रहता है।
reviewStatusवैकल्पिक	इसे needs_review, reviewed, या flagged के तौर पर चिह्नित करें।
clearCategoryवैकल्पिक	आपका कैटेगरी ओवरराइड हटा देता है, ताकि Era का अपना वर्गीकरण फिर से लागू हो जाए। डिफ़ॉल्ट रूप से false।
clearMerchantNameवैकल्पिक	आपका व्यापारी-नाम ओवरराइड हटा देता है, ताकि आपके बैंक का भेजा नाम वापस आ जाए। डिफ़ॉल्ट रूप से false।
clearDescriptionवैकल्पिक	आपका विवरण ओवरराइड हटा देता है, ताकि आपके बैंक का भेजा विवरण वापस आ जाए। डिफ़ॉल्ट रूप से false।
clearReviewStatusवैकल्पिक	आपका समीक्षा-स्थिति ओवरराइड हटा देता है। डिफ़ॉल्ट रूप से false।

रिस्पॉन्स · 200

{
  "transactions": [ … ]
}

आपको अपडेटेड ट्रांज़ैक्शन वापस मिलते हैं, ठीक उसी आकार में जो ऊपर की सूची लौटाती है। एक ही कॉल में कोई फ़ील्ड सेट करना और उसे क्लियर करना 400 लौटाता है, और ख़ाली सूची भी। ऐसी सूची जिसमें कोई ट्रांज़ैक्शन आपका न हो, या हो ही न, पूरी कॉल के लिए 403 लौटाती है — कुछ भी नहीं बदलता। अगर आपके लिखते वक़्त किसी और चीज़ ने उनमें से किसी पंक्ति को बदल दिया, तो आपको 409 मिलता है: उन्हें दोबारा पढ़िए और दोबारा भेजिए।

कैटेगरी

GET/banking/categories

ज़रूरी स्कोप

banking:read

पूरी कैटेगरी व्यवस्था: कैटेगरी का हर समूह, जिसके अंदर उसकी उप-कैटेगरी नेस्टेड हैं। यह व्यवस्था साझा है, हर अकाउंट के लिए अलग नहीं।

रिस्पॉन्स · 200

{
  "packs": [
    {
      "packSlug": "default",
      "packName": "Era default categories",
      "isDefault": true,
      "categories": [
        {
          "projectionKey": "fcat_food_dining",
          "categoryName": "Food & dining",
          "isTopLevel": true,
          "children": [ … ]
        }
      ]
    }
  ],
  "meterLimit": 25,
  "canCreateCustomCategories": true
}

कैटेगरी जोड़ें

किसी मौजूदा पैरेंट के तहत एक यूज़र-डिफ़ाइंड कैटेगरी। यह डेटा बदलता है, इसलिए banking:read की जगह banking:write चाहिए।

POST

ज़रूरी स्कोप

banking:write

रिक्वेस्ट बॉडी
slug	URL-सुरक्षित पहचानकर्ता — छोटे अक्षर, अंक और हाइफ़न, 2 से 50 वर्ण।
parentCategoryKey	उस कैटेगरी की fcat_ की, जिसके नीचे यह नेस्ट होगी।
name	डिस्प्ले नाम।
descriptionवैकल्पिक	वैकल्पिक विवरण।
iconNameवैकल्पिक	वैकल्पिक आइकन नाम।
spendingTypeवैकल्पिक	वैकल्पिक ख़र्च वर्गीकरण।
displayOrderवैकल्पिक	इसके साथी कैटेगरी के बीच वैकल्पिक क्रम-स्थिति।
assignmentEligibilityवैकल्पिक	किन ट्रांज़ैक्शन को यह कैटेगरी सौंपी जा सकती है, इसका वैकल्पिक नियम।
sourceSystemKeysवैकल्पिक	मौजूदा कैटेगरी की-ज़ की वैकल्पिक सूची, जिनके ट्रांज़ैक्शन आगे से यहाँ भेजे जाने चाहिए।
applyRetroactivelyवैकल्पिक	true होने पर, पुराने ट्रांज़ैक्शन को भी नए रूटिंग के हिसाब से फिर से जाँचता है। डिफ़ॉल्ट रूप से false।

रिस्पॉन्स · 201

{
  "categoryKey": "fcat_side_hustle_9f2a",
  "overlayProjectionKey": "fcov_9f2a1c",
  "action": "created",
  "isQuotaExceeded": false,
  "createdMappingRuleKeys": [ … ],
  …
}

रिस्पॉन्स retroactiveAffectedCount, mergeSourcesHiddenCount, mergeSourcesTotalCount, और meterGate भी लेकर आता है — ये फ़ील्ड यह कॉल कैटेगरी-मर्ज और कोटा-सीमित निर्माण के साथ साझा करती है, यहाँ नहीं दिखाए गए।

क्वेरी पैरामीटर
tagTypeवैकल्पिक	टैग की उत्पत्ति से फ़िल्टर करता है: user, system, या auto।
includeDeletedवैकल्पिक	हटाए गए टैग भी शामिल करता है। डिफ़ॉल्ट रूप से false।

रिस्पॉन्स · 200

{
  "tags": [
    {
      "tagKey": "utag_9c2f01ab",
      "name": "business-expense",
      "displayName": "Business expense",
      "tagType": "user",
      "color": "#6DC6BA",
      "transactionCount": 42
    }
  ]
}

टैग बनाएँ

एक नया टैग, छोटे अक्षरों में नॉर्मलाइज़्ड। यह डेटा बदलता है, इसलिए banking:read की जगह banking:write चाहिए — और यह सिर्फ़ user टैग बना सकता है; API के ज़रिए system की इजाज़त नहीं है।

POST

ज़रूरी स्कोप

banking:write

रिक्वेस्ट बॉडी
name	टैग का कैननिकल नाम।
displayNameवैकल्पिक	वैकल्पिक डिस्प्ले नाम। डिफ़ॉल्ट रूप से कैननिकल नाम।
tagTypeवैकल्पिक	डिफ़ॉल्ट रूप से user — यहाँ API सिर्फ़ यही मान स्वीकार करता है।
colorवैकल्पिक	दिखाने के लिए वैकल्पिक हेक्स रंग।
iconवैकल्पिक	वैकल्पिक आइकन नाम।

रिस्पॉन्स · 201

{
  "tag": {
    "tagKey": "utag_9c2f01ab",
    "name": "business-expense",
    "displayName": "Business expense",
    "tagType": "user",
    "version": 1,
    "createdAt": "2026-08-26T09:15:00Z"
  }
}