swagger.json

{"components":{"schemas":{"Category":{"properties":{"created":{"description":"Timestamp for when the category was created","example":"Tue, 01 Mar 2022 14:27:05 GMT","format":"date-time","readOnly":true,"type":"string"},"description":{"nullable":true,"type":"string"},"heron_id":{"description":"Unique ID of the category generated by Heron Data","example":"ctg_2mwjR58KSAqPenKBxtDHnB","readOnly":true,"type":"string"},"label":{"description":"The label of the category","example":"Rent","type":"string"}},"required":["label"],"type":"object"},"CategoryFeedback":{"properties":{"heron_id":{"example":"ctg_WSUgj6M3d8TeFLHi7VPPft","type":"string"},"label":{"example":"Insurance","type":"string"}},"type":"object"},"DeleteTransactionParams":{"properties":{"account_id":{"default":null,"nullable":true,"type":"string"},"end_user_id":{"default":null,"nullable":true,"type":"string"},"heron_id":{"default":null,"example":"txn_agVJBv4VN5bR5NV7eVzkcK","nullable":true,"type":"string"},"only_duplicates":{"default":null,"description":"if true, deletes only duplicates","nullable":true,"type":"boolean"},"request_id":{"default":null,"nullable":true,"type":"string"}},"type":"object"},"EndUser":{"properties":{"confidence":{"description":"Aggregated confidence for the end user across all transactions; between 0 and 1","example":0.42,"readOnly":true,"type":"number"},"created":{"description":"When the end user was created in Heron system","example":"2022-01-18T14:27:05.994372","format":"date-time","readOnly":true,"type":"string"},"criteria":{"default":null,"description":"Information about an end user that can be used as rules for underwriting","example":{"history_days":{"value":40}},"nullable":true,"readOnly":true,"type":"object"},"end_user_id":{"description":"id defined by user; links to the end_user_id for transactions","example":"fb1118a0-0a6c-4a2a-9691-746ce9ac5ed8","type":"string"},"heron_id":{"description":"Unique id for end user generated by Heron","example":"eus_bn3ZQD7rA3PGwvkGj3gW6U","readOnly":true,"type":"string"},"last_updated":{"description":"When the end user was last updated in Heron system","example":"2022-03-01T14:27:05.994400","format":"date-time","readOnly":true,"type":"string"},"name":{"description":"Name of end user; may help to improve categorisation accuracy","example":"Company Name Inc.","nullable":true,"type":"string"},"status":{"description":"Status of end user; 'ready' triggers async processing, 'review_requested' triggers manual review request","enum":["new","ready","review_requested","reviewed"],"example":"ready","type":"string"}},"required":["end_user_id","status"],"type":"object"},"EndUserBalanceInputParams":{"properties":{"end_user_heron_id":{"default":null,"description":"Heron-generated id for end user; either end_user_id or end_user_heron_id is required","example":"eus_eeGLTHE3LKhbZuZiDRLVVs","nullable":true,"type":"string"},"end_user_id":{"default":null,"description":"end_user_id for statistics; either end_user_id or end_user_heron_id is required","example":"your_end_user_id","nullable":true,"type":"string"},"timestamp_max":{"default":null,"description":"Filter for transactions with timestamp earlier than the input value","example":"2022-02-28T14:27:05.995828","format":"date-time","nullable":true,"type":"string"},"timestamp_min":{"default":null,"description":"Filter for transactions with timestamp after the input value","example":"2022-03-01T14:27:05.995809","format":"date-time","nullable":true,"type":"string"}},"type":"object"},"EndUserForecastInputParams":{"properties":{"category_heron_id":{"description":"Heron ID of category to be forecasted; either category_heron_id or category_label must be present","example":"ctg_7WSk6DKKvYg5DEpR7HTbNy","nullable":true,"type":"string"},"category_label":{"description":"Label of category to be forecasted; either category_heron_id or category_label must be present","example":"Revenue","nullable":true,"type":"string"},"date_granularity":{"default":"month","description":"Aggregate results over time, i.e., aggregate by week or by month","enum":["week","month"],"example":"month","type":"string"},"end_user_heron_id":{"default":null,"description":"Heron-generated id for end user; either end_user_id or end_user_heron_id is required","example":"eus_eeGLTHE3LKhbZuZiDRLVVs","nullable":true,"type":"string"},"end_user_id":{"default":null,"description":"end_user_id for statistics; either end_user_id or end_user_heron_id is required","example":"your_end_user_id","nullable":true,"type":"string"}},"type":"object"},"EndUserForecastOutputSchema":{"properties":{"date":{"description":"Forecast date at specified date granularity","example":"2022-03-01","type":"string"},"predicted":{"description":"Predicted amount","example":42.42,"type":"number"},"predicted_lower":{"description":"Predict amount lower bound","example":4.24,"type":"number"},"predicted_upper":{"description":"Predicted amount upper bound","example":420.42,"type":"number"}},"type":"object"},"EndUserReadParams":{"properties":{"criteria":{"default":null,"description":"Information about the end user that can be used as rules for underwriting","example":{"history_days":{"value":40}},"nullable":true,"readOnly":true,"type":"object"},"end_user_id":{"default":null,"description":"Filter by ID associated with end_user_id field in transactions","example":"your_end_user_id","nullable":true,"type":"string"},"heron_id":{"default":null,"description":"Unique ID generated by Heron","example":"eus_NKD8xwxRULBxMTWBRS447Z","nullable":true,"type":"string"},"limit":{"default":1000,"description":"Pagination limit per page","type":"integer"},"name":{"default":null,"description":"Filter by name associated with end user","example":"your_end_user_name","nullable":true,"type":"string"},"order_by":{"default":"last_updated_desc","description":"Order to return end users by","enum":["last_updated_desc","last_updated_asc"],"type":"string"},"page":{"default":1,"description":"Pagination page number","type":"integer"},"status":{"default":null,"description":"Filter by status of end user","enum":["new","ready","processed","reviewed","review_requested"],"example":"reviewed","nullable":true,"type":"string"}},"type":"object"},"EndUserStatsInputParams":{"properties":{"category_heron_ids":{"default":[],"description":"Filter by specific categories","example":["ctg_CkuoR3PifEAwaX5xgjz9NX","ctg_EAp8B7WKsYP2m7yGiFDueN"],"items":{"type":"string"},"type":"array"},"date_granularity":{"default":"month","description":"Aggregate results over time, e.g., by week or by quarter","enum":["day","week","month","quarter","year"],"example":"month","type":"string"},"end_user_heron_id":{"default":null,"description":"Heron-generated id for end user; either end_user_id or end_user_heron_id is required","example":"eus_eeGLTHE3LKhbZuZiDRLVVs","nullable":true,"type":"string"},"end_user_id":{"default":null,"description":"end_user_id for statistics; either end_user_id or end_user_heron_id is required","example":"your_end_user_id","nullable":true,"type":"string"},"from_date":{"default":null,"description":"Filter for transactions with timestamp after the input value (as date)","example":"2022-03-01","format":"date","nullable":true,"type":"string"},"group_by":{"default":"category","description":"Pivot results by merchant or by category","enum":["category","merchant"],"example":"category","type":"string"},"merchant_heron_ids":{"default":[],"description":"Filter by specific merchants","example":["mrc_HuuEZRgMURi9xkDycFdBjT","mrc_6sVrtkH9ggsNcoWAgkxnyX"],"items":{"type":"string"},"type":"array"},"to_date":{"default":null,"description":"Filter for transactions with timestamp before the input value (as date)","example":"2022-02-28","format":"date","nullable":true,"type":"string"}},"type":"object"},"GetTransactionParams":{"properties":{"category_heron_id":{"default":[],"description":"Filter by the heron_id of the category that the transaction is annotated with","example":"ctg_9iLZUbAEYQ6w6E9QwDvWE4","items":{"type":"string"},"nullable":true,"type":"array"},"confidence_max":{"description":"Filter by maximum confidence of annotation associated with transaction","maximum":1,"minimum":0,"type":"number"},"confidence_min":{"description":"Filter by minimum confidence of annotation associated with transaction","maximum":1,"minimum":0,"type":"number"},"created_date_max":{"description":"Filter by latest transaction upload date - when Heron received the transaction","example":"2020-04-27","format":"date","type":"string"},"created_date_min":{"description":"Filter by earliest transaction upload date - when Heron received the transaction","example":"2020-04-27","format":"date","type":"string"},"description_keyword":{"description":"Filter by keyword match on transaction description; case insensitive","type":"string"},"description_regex":{"description":"Filter by regex matching transaction description","type":"string"},"end_user_id":{"description":"End user id of transaction","type":"string"},"from_date":{"description":"Deprecated; see created_date_ or timestamp_date_","format":"date","type":"string"},"has_matching_transaction":{"description":"Filter by whether the transaction has a matching transaction","type":"boolean"},"heron_id":{"description":"Heron generated Id of transaction","example":"txn_6zCaHQaJdYQZVfhU4LxMxj","type":"string"},"include_duplicates":{"description":"Whether or not to include duplicate transactions in the response. Defaults to false unless request_id is provided, in which case it defaults to true.","type":"boolean"},"is_recurring":{"description":"Filter by whether the transaction is recurring","type":"boolean"},"last_updated_max":{"description":"Filter for transactions whose values were last updated in Heron systems before the specified input value","example":"2022-03-01T14:27:05.538146","format":"date-time","type":"string"},"last_updated_min":{"description":"Filter for transactions whose values were last updated in Heron systems after the specified input value","example":"2022-03-01T14:27:05.538133","format":"date-time","type":"string"},"limit":{"default":1000,"description":"Number of transactions to return per page","maximum":10000,"minimum":1,"type":"integer"},"max_amount":{"description":"Filter by maximum amount of transaction","type":"number"},"min_amount":{"description":"Filter by minimum amount of transaction","type":"number"},"order_by":{"default":"id_asc","description":"What to order transactions by","enum":["amount_asc","amount_desc","abs_amount_asc","abs_amount_desc","description_asc","description_desc","timestamp_asc","timestamp_desc","id_asc","id_desc"],"type":"string"},"page":{"default":1,"description":"Page of transaction to return","type":"integer"},"reference_id":{"description":"Reference Id of transaction","type":"string"},"request_id":{"description":"Request-Id header returned in the response of POST transactions. Sending this parameter will return all transactions sent in a particular POST request, including any duplicates.","type":"string"},"timestamp_date_max":{"description":"Filter by latest transaction timestamp","example":"2020-04-27","format":"date","type":"string"},"timestamp_date_min":{"description":"Filter by earliest transaction timestamp","example":"2020-04-27","format":"date","type":"string"},"to_date":{"description":"Deprecated; see created_date_ or timestamp_date_","format":"date","type":"string"},"transaction_code":{"description":"Filter by transaction code","type":"string"}},"type":"object"},"Merchant":{"properties":{"categories":{"items":{"$ref":"#/components/schemas/MerchantCategory"},"readOnly":true,"type":"array"},"heron_id":{"example":"mrc_d9AybrfShyEYXGjy5HxvZ2","readOnly":true,"type":"string"},"icon_url":{"format":"url","type":"string"},"logo_url":{"format":"url","type":"string"},"name":{"type":"string"},"url":{"format":"url","type":"string"}},"required":["name","url"],"type":"object"},"MerchantCategory":{"properties":{"code":{"example":"7311","readOnly":true,"type":"string"},"description":{"default":null,"example":"Advertising services","nullable":true,"readOnly":true,"type":"string"},"slug":{"default":null,"example":"advertising_services","nullable":true,"readOnly":true,"type":"string"}},"required":["code"],"type":"object"},"MerchantExtract":{"properties":{"categories":{"items":{"$ref":"#/components/schemas/MerchantCategory"},"readOnly":true,"type":"array"},"confidence":{"default":null,"maximum":1,"minimum":0,"nullable":true,"type":"number"},"heron_id":{"example":"mrc_d9AybrfShyEYXGjy5HxvZ2","readOnly":true,"type":"string"},"icon_url":{"format":"url","readOnly":true,"type":"string"},"logo_url":{"format":"url","readOnly":true,"type":"string"},"name":{"default":null,"example":"Amazon","nullable":true,"readOnly":true,"type":"string"},"url":{"default":null,"example":"https://www.amazon.com/","format":"url","nullable":true,"readOnly":true,"type":"string"}},"type":"object"},"MerchantFeedback":{"properties":{"heron_id":{"example":"mrc_bg7s7aiMWotKcjjAYp7W9Z","type":"string"},"is_correct":{"default":false,"example":false,"type":"boolean"},"name":{"example":"Spotify","type":"string"}},"type":"object"},"PaymentProcessor":{"properties":{"heron_id":{"example":"mrc_d9AybrfShyEYXGjy5HxvZ2","readOnly":true,"type":"string"},"name":{"type":"string"},"url":{"format":"url","type":"string"}},"required":["name","url"],"type":"object"},"TransactionAnnotation":{"properties":{"annotator":{"description":"Annotator type","example":"predicted","type":"string"},"confidence":{"description":"The confidence associated with the category annotation","example":0.5,"type":"number"},"heron_id":{"description":"Unique ID of category; generated by Heron Data","example":"ctg_hFN8Vod7jYKTKxqgYkrcCq","type":"string"},"label":{"description":"Label of category","example":"Rent","type":"string"},"model_version":{"description":"The model version that produced the categorisation","example":"377559cb-1bb7-4f7b-9f06-d7b1e1556881","type":"string"}},"type":"object"},"TransactionFeedbackParams":{"properties":{"trigger_webhook":{"default":true,"description":"If true, enables the triggering of transaction_updated webhook. Set to false to supress trigger. Default true","type":"boolean"}},"type":"object"},"TransactionFeedbackSchema":{"properties":{"category":{"allOf":[{"$ref":"#/components/schemas/CategoryFeedback"}],"default":{}},"merchant":{"allOf":[{"$ref":"#/components/schemas/MerchantFeedback"}],"default":{}}},"type":"object"},"TransactionGetOutput":{"properties":{"account_id":{"description":"Your unique ID for account associated with transaction","example":"checking_account_202348","nullable":true,"type":"string"},"amount":{"description":"Amount of transaction","example":42.42,"type":"number"},"balance":{"description":"The running balance of the account after transaction ocurred","example":42.0,"nullable":true,"type":"number"},"categories":{"description":"The category associated with the transaction","items":{"$ref":"#/components/schemas/TransactionAnnotation"},"type":"array"},"created":{"description":"When transaction was created in Heron system","example":"2022-03-01T14:27:05.536333","format":"date-time","type":"string"},"currency":{"description":"ISO 4217 currency code","example":"USD","maxLength":3,"minLength":3,"nullable":true,"type":"string"},"description":{"description":"The text description for the transaction","example":"GOOGLE *ADS12340929 cc@google.com US","type":"string"},"description_clean":{"description":"The cleaned description of the transaction","example":"GOOGLE ADS","type":"string"},"duplicate_of_id":{"description":"Indicates that the transaction is a duplicate and gives the heron_id of the original","example":"txn_iZfR4XWcVv3QKPm9smNTEe","type":"string"},"end_user_id":{"description":"Your unique ID for end user associated with transaction","example":"my_best_customer_203948","nullable":true,"type":"string"},"has_matching_transaction":{"description":"Whether the transaction is a transfer; requires end_user_id and timestamp to be present","type":"boolean"},"heron_id":{"description":"Unique ID of transaction; generated by Heron Data","example":"txn_GwQHyCawphLtck6XF8wU9T","type":"string"},"is_potential_duplicate":{"description":"Indicates whether the transaction has another transaction similar to it","readOnly":true,"type":"boolean"},"is_recurring":{"description":"Whether the transaction is recurring or not; requires end_user_id and timestamp to be present","type":"boolean"},"last_updated":{"description":"When transaction was last updated in Heron system; could be from recategorisation or attribute updates","example":"2022-03-01T14:27:05.536360","format":"date-time","type":"string"},"mcc_code":{"description":"Merchant category code associated with transaction that you may have received from other sources","nullable":true,"type":"string","writeOnly":true},"merchant":{"allOf":[{"$ref":"#/components/schemas/Merchant"}],"description":"The merchant associated with the transaction"},"payment_processor":{"allOf":[{"$ref":"#/components/schemas/PaymentProcessor"}],"description":"The payment processor associated with the transaction"},"reference_id":{"description":"Your unique ID for transaction","example":"my_favourite_transaction_231098","nullable":true,"type":"string"},"request_id":{"description":"ID associated with request, e.g., all transactions in same POST request will have same request_id","example":"req_kWhUK5Jxa3wQ9qrei48idh","nullable":true,"type":"string"},"timestamp":{"description":"The ISO 8601 timezone aware timestamp of the transaction; takes precedence over 'date'","example":"2021-11-12T10:38:05Z","format":"date-time","nullable":true,"type":"string"},"transaction_code":{"description":"Code associated with transaction to indicate the type of transaction","example":"DEBIT","nullable":true,"type":"string"}},"required":["amount","description"],"type":"object"},"TransactionInput":{"properties":{"account_id":{"description":"Your unique ID for account associated with transaction","example":"checking_account_202348","nullable":true,"type":"string"},"amount":{"description":"Amount of transaction","example":42.42,"type":"number"},"balance":{"description":"The running balance of the account after transaction ocurred","example":42.0,"nullable":true,"type":"number"},"categories_default":{"description":"Category of transaction that you may have received from other sources","example":"shopping","nullable":true,"type":"string","writeOnly":true},"currency":{"description":"ISO 4217 currency code","example":"USD","maxLength":3,"minLength":3,"nullable":true,"type":"string"},"date":{"description":"The date of the transaction; 'timestamp' field takes priority over 'date'","example":"2020-04-27","format":"date","nullable":true,"type":"string","writeOnly":true},"description":{"description":"The text description for the transaction","example":"GOOGLE *ADS12340929 cc@google.com US","type":"string"},"end_user_id":{"description":"Your unique ID for end user associated with transaction","example":"my_best_customer_203948","nullable":true,"type":"string"},"mcc_code":{"description":"Merchant category code associated with transaction that you may have received from other sources","nullable":true,"type":"string","writeOnly":true},"merchant_name":{"description":"Merchant name associated with transaction that you may have received from other sources","nullable":true,"type":"string","writeOnly":true},"reference_id":{"description":"Your unique ID for transaction","example":"my_favourite_transaction_231098","nullable":true,"type":"string"},"timestamp":{"description":"The ISO 8601 timezone aware timestamp of the transaction; takes precedence over 'date'","example":"2021-11-12T10:38:05Z","format":"date-time","nullable":true,"type":"string"},"transaction_code":{"description":"Code associated with transaction to indicate the type of transaction","example":"DEBIT","nullable":true,"type":"string"}},"required":["amount","description"],"type":"object"},"TransactionPostOutput":{"properties":{"account_id":{"description":"Your unique ID for account associated with transaction","example":"checking_account_202348","nullable":true,"type":"string"},"amount":{"description":"Amount of transaction","example":42.42,"type":"number"},"balance":{"description":"The running balance of the account after transaction ocurred","example":42.0,"nullable":true,"type":"number"},"categories":{"description":"The category associated with the transaction","items":{"$ref":"#/components/schemas/TransactionAnnotation"},"type":"array"},"currency":{"description":"ISO 4217 currency code","example":"USD","maxLength":3,"minLength":3,"nullable":true,"type":"string"},"description":{"description":"The text description for the transaction","example":"GOOGLE *ADS12340929 cc@google.com US","type":"string"},"description_clean":{"description":"The cleaned description of the transaction","example":"GOOGLE ADS","type":"string"},"duplicate_of_id":{"description":"Indicates that the transaction is a duplicate and gives the heron_id of the original","example":"txn_iZfR4XWcVv3QKPm9smNTEe","type":"string"},"end_user_id":{"description":"Your unique ID for end user associated with transaction","example":"my_best_customer_203948","nullable":true,"type":"string"},"has_matching_transaction":{"description":"Whether the transaction is a transfer; requires end_user_id and timestamp to be present","type":"boolean"},"heron_id":{"description":"Unique ID of transaction; generated by Heron Data","example":"txn_GwQHyCawphLtck6XF8wU9T","type":"string"},"is_potential_duplicate":{"description":"Indicates whether the transaction has another transaction similar to it","readOnly":true,"type":"boolean"},"is_recurring":{"description":"Whether the transaction is recurring or not; requires end_user_id and timestamp to be present","type":"boolean"},"mcc_code":{"description":"Merchant category code associated with transaction that you may have received from other sources","nullable":true,"type":"string","writeOnly":true},"merchant":{"allOf":[{"$ref":"#/components/schemas/Merchant"}],"description":"The merchant associated with the transaction"},"payment_processor":{"allOf":[{"$ref":"#/components/schemas/PaymentProcessor"}],"description":"The payment processor associated with the transaction"},"reference_id":{"description":"Your unique ID for transaction","example":"my_favourite_transaction_231098","nullable":true,"type":"string"},"request_id":{"description":"ID associated with request, e.g., all transactions in same POST request will have same request_id","example":"req_kWhUK5Jxa3wQ9qrei48idh","nullable":true,"type":"string"},"timestamp":{"description":"The ISO 8601 timezone aware timestamp of the transaction; takes precedence over 'date'","example":"2021-11-12T10:38:05Z","format":"date-time","nullable":true,"type":"string"},"transaction_code":{"description":"Code associated with transaction to indicate the type of transaction","example":"DEBIT","nullable":true,"type":"string"}},"required":["amount","description"],"type":"object"}},"securitySchemes":{"BasicAuth":{"scheme":"basic","type":"http"}}},"consumes":["application/json"],"contact":{"email":"help@herondata.io","name":"Heron Data","url":"https://herondata.io"},"info":{"title":"Heron Data API","version":"2021-07-19"},"openapi":"3.0.0","paths":{"/api/categories":{"get":{"description":"Get available categories","externalDocs":{"description":"Find more info here","url":"https://docs.herondata.io/categories"},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"categories":{"items":{"$ref":"#/components/schemas/Category"},"type":"array"}},"type":"object"}}},"description":"OK"},"401":{"description":"Unauthorized"}},"security":[{"BasicAuth":[]}],"summary":"Get categories","tags":["Categories"]}},"/api/end_users":{"get":{"description":"Get a list of EndUsers","parameters":[{"description":"Pagination page number","in":"query","name":"page","required":false,"schema":{"default":1,"type":"integer"}},{"description":"Filter by name associated with end user","in":"query","name":"name","required":false,"schema":{"default":null,"example":"your_end_user_name","nullable":true,"type":"string"}},{"description":"Pagination limit per page","in":"query","name":"limit","required":false,"schema":{"default":1000,"type":"integer"}},{"description":"Filter by status of end user","in":"query","name":"status","required":false,"schema":{"default":null,"enum":["new","ready","processed","reviewed","review_requested"],"example":"reviewed","nullable":true,"type":"string"}},{"description":"Unique ID generated by Heron","in":"query","name":"heron_id","required":false,"schema":{"default":null,"example":"eus_NKD8xwxRULBxMTWBRS447Z","nullable":true,"type":"string"}},{"description":"Filter by ID associated with end_user_id field in transactions","in":"query","name":"end_user_id","required":false,"schema":{"default":null,"example":"your_end_user_id","nullable":true,"type":"string"}},{"description":"Order to return end users by","in":"query","name":"order_by","required":false,"schema":{"default":"last_updated_desc","enum":["last_updated_desc","last_updated_asc"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"_meta":{"properties":{"limit":{"example":1000,"type":"integer"},"next_url":{"type":"string"},"page":{"example":1,"type":"integer"},"pages":{"example":3,"type":"integer"},"prev_url":{"type":"string"},"total":{"example":3500,"type":"integer"}},"type":"object"},"end_users":{"items":{"$ref":"#/components/schemas/EndUser","type":"object"},"type":"array"}},"type":"object"}}},"description":"OK"}},"security":[{"BasicAuth":[]}],"summary":"List EndUsers","tags":["EndUsers"]},"post":{"description":"Create a new end user. If transactions have previously been sent for this `end_user_id`, use `PUT end_users` to update instead.\n","requestBody":{"content":{"application/json":{"schema":{"properties":{"end_user":{"$ref":"#/components/schemas/EndUser","type":"object"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"end_user":{"$ref":"#/components/schemas/EndUser","type":"object"}},"type":"object"}}},"description":"OK"}},"security":[{"BasicAuth":[]}],"summary":"Create EndUser","tags":["EndUsers"]},"put":{"description":"Confirm an end user is ready for async procesing by sending a status of \"ready\". The `end_user_id` must have previously been sent with at least one Transaction.\n","requestBody":{"content":{"application/json":{"schema":{"properties":{"end_user":{"$ref":"#/components/schemas/EndUser","type":"object"}},"type":"object"}}},"description":"Dictionary representing an EndUser","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"end_user":{"$ref":"#/components/schemas/EndUser","type":"object"}},"type":"object"}}},"description":"OK"}},"security":[{"BasicAuth":[]}],"summary":"Update EndUser","tags":["EndUsers"]}},"/api/end_users/balance":{"get":{"description":"Get balance for given EndUser on a per account level","parameters":[{"description":"Heron-generated id for end user; either end_user_id or end_user_heron_id is required","in":"query","name":"end_user_heron_id","required":false,"schema":{"default":null,"example":"eus_eeGLTHE3LKhbZuZiDRLVVs","nullable":true,"type":"string"}},{"description":"Filter for transactions with timestamp earlier than the input value","in":"query","name":"timestamp_max","required":false,"schema":{"default":null,"example":"2022-02-28T14:27:05.995828","format":"date-time","nullable":true,"type":"string"}},{"description":"Filter for transactions with timestamp after the input value","in":"query","name":"timestamp_min","required":false,"schema":{"default":null,"example":"2022-03-01T14:27:05.995809","format":"date-time","nullable":true,"type":"string"}},{"description":"end_user_id for statistics; either end_user_id or end_user_heron_id is required","in":"query","name":"end_user_id","required":false,"schema":{"default":null,"example":"your_end_user_id","nullable":true,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"accounts":{"items":{"properties":{"account_id":{"type":"string"},"balance":{"type":"number"},"last_transaction_timestamp":{"format":"date-time","type":"string"}},"type":"object"},"type":"array"},"summary":{"properties":{"balance":{"type":"number"},"timestamp":{"format":"date-time","type":"string"}},"type":"object"}},"type":"object"}}},"description":"OK"}},"security":[{"BasicAuth":[]}],"summary":"Get EndUser balance","tags":["EndUsers"]}},"/api/end_users/forecast":{"get":{"description":"Get forecast amounts for a given EndUser and category","parameters":[{"description":"Label of category to be forecasted; either category_heron_id or category_label must be present","in":"query","name":"category_label","required":false,"schema":{"example":"Revenue","nullable":true,"type":"string"}},{"description":"Heron-generated id for end user; either end_user_id or end_user_heron_id is required","in":"query","name":"end_user_heron_id","required":false,"schema":{"default":null,"example":"eus_eeGLTHE3LKhbZuZiDRLVVs","nullable":true,"type":"string"}},{"description":"Aggregate results over time, i.e., aggregate by week or by month","in":"query","name":"date_granularity","required":false,"schema":{"default":"month","enum":["week","month"],"example":"month","type":"string"}},{"description":"Heron ID of category to be forecasted; either category_heron_id or category_label must be present","in":"query","name":"category_heron_id","required":false,"schema":{"example":"ctg_7WSk6DKKvYg5DEpR7HTbNy","nullable":true,"type":"string"}},{"description":"end_user_id for statistics; either end_user_id or end_user_heron_id is required","in":"query","name":"end_user_id","required":false,"schema":{"default":null,"example":"your_end_user_id","nullable":true,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/EndUserForecastOutputSchema","type":"object"},"type":"array"}}},"description":"OK"}},"security":[{"BasicAuth":[]}],"summary":"Get EndUser forecasts","tags":["EndUsers"]}},"/api/end_users/statistics":{"get":{"description":"Get summarized statistics for a given EndUser","parameters":[{"description":"Filter for transactions with timestamp before the input value (as date)","in":"query","name":"to_date","required":false,"schema":{"default":null,"example":"2022-02-28","format":"date","nullable":true,"type":"string"}},{"description":"Pivot results by merchant or by category","in":"query","name":"group_by","required":false,"schema":{"default":"category","enum":["category","merchant"],"example":"category","type":"string"}},{"description":"Heron-generated id for end user; either end_user_id or end_user_heron_id is required","in":"query","name":"end_user_heron_id","required":false,"schema":{"default":null,"example":"eus_eeGLTHE3LKhbZuZiDRLVVs","nullable":true,"type":"string"}},{"description":"Filter for transactions with timestamp after the input value (as date)","in":"query","name":"from_date","required":false,"schema":{"default":null,"example":"2022-03-01","format":"date","nullable":true,"type":"string"}},{"description":"Aggregate results over time, e.g., by week or by quarter","in":"query","name":"date_granularity","required":false,"schema":{"default":"month","enum":["day","week","month","quarter","year"],"example":"month","type":"string"}},{"description":"end_user_id for statistics; either end_user_id or end_user_heron_id is required","in":"query","name":"end_user_id","required":false,"schema":{"default":null,"example":"your_end_user_id","nullable":true,"type":"string"}},{"description":"Filter by specific categories","explode":true,"in":"query","name":"category_heron_ids","required":false,"schema":{"default":[],"example":["ctg_CkuoR3PifEAwaX5xgjz9NX","ctg_EAp8B7WKsYP2m7yGiFDueN"],"items":{"type":"string"},"type":"array"},"style":"form"},{"description":"Filter by specific merchants","explode":true,"in":"query","name":"merchant_heron_ids","required":false,"schema":{"default":[],"example":["mrc_HuuEZRgMURi9xkDycFdBjT","mrc_6sVrtkH9ggsNcoWAgkxnyX"],"items":{"type":"string"},"type":"array"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"statistics":{"items":{"properties":{"dt":{"type":"string"},"heron_id":{"type":"string"},"label":{"type":"string"},"value":{"type":"number"}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"OK"}},"security":[{"BasicAuth":[]}],"summary":"Get EndUser statistics","tags":["EndUsers"]}},"/api/hello_world":{"get":{"description":"Test endpoint (no authentication)","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"hello":{"type":"string"}},"type":"object"}}},"description":"url works"}},"tags":["Testing"]}},"/api/hello_world/authenticated":{"get":{"description":"Test authentication","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"hello":{"type":"string"}},"type":"object"}}},"description":"Authentication works"},"401":{"description":"Unauthorized"}},"security":[{"BasicAuth":[]}],"tags":["Testing"]}},"/api/merchants/extract":{"post":{"description":"Extract Merchant from a transaction description","requestBody":{"content":{"application/json":{"schema":{"properties":{"description":{"example":"PAYPAL* AMZN Mktp 198748320","required":true,"type":"string"}},"type":"object"}}},"description":"The bank transaction description as a string","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"description_clean":{"example":"Amzn Mktp","nullable":true,"type":"string"},"merchant":{"$ref":"#/components/schemas/MerchantExtract","nullable":true,"type":"object"},"payment_processor":{"$ref":"#/components/schemas/PaymentProcessor","nullable":true,"type":"object"}},"type":"object"}}},"description":"The `merchant` key is not null when we find a positive match to our database. When we could not match a merchant, `merchant` is null and `description_clean` is set to a substring of the original description that our models identified as the relevant entity.\n"}},"security":[{"BasicAuth":[]}],"tags":["Merchants"]}},"/api/merchants/search":{"get":{"description":"Search Merchants by name","parameters":[{"description":"Full or partial name, minimum 3 characters","in":"query","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"merchants":{"items":{"$ref":"#/components/schemas/Merchant","type":"object"},"type":"array"}},"type":"object"}}},"description":"A list of up to 5 merchants which match the search term, sorted by descending order of their URL rank and the frequency this merchant has been seen historically.\n"}},"security":[{"BasicAuth":[]}],"tags":["Merchants"]}},"/api/merchants/{heron_id}":{"get":{"description":"Get Merchant by heron_id","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"merchant":{"$ref":"#/components/schemas/Merchant","type":"object"}},"type":"object"}}},"description":"OK"}},"security":[{"BasicAuth":[]}],"tags":["Merchants"]}},"/api/transactions":{"delete":{"description":"Delete transactions","parameters":[{"description":"if true, deletes only duplicates","in":"query","name":"only_duplicates","required":false,"schema":{"default":null,"nullable":true,"type":"boolean"}},{"in":"query","name":"account_id","required":false,"schema":{"default":null,"nullable":true,"type":"string"}},{"in":"query","name":"request_id","required":false,"schema":{"default":null,"nullable":true,"type":"string"}},{"in":"query","name":"heron_id","required":false,"schema":{"default":null,"example":"txn_agVJBv4VN5bR5NV7eVzkcK","nullable":true,"type":"string"}},{"in":"query","name":"end_user_id","required":false,"schema":{"default":null,"nullable":true,"type":"string"}}],"responses":{"202":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"}},"type":"object"}}},"description":"OK"}},"security":[{"BasicAuth":[]}],"tags":["Transactions"]},"get":{"description":"Get transactions","parameters":[{"description":"Page of transaction to return","in":"query","name":"page","required":false,"schema":{"default":1,"type":"integer"}},{"description":"Deprecated; see created_date_ or timestamp_date_","in":"query","name":"to_date","required":false,"schema":{"format":"date","type":"string"}},{"description":"Filter by minimum amount of transaction","in":"query","name":"min_amount","required":false,"schema":{"type":"number"}},{"description":"Filter for transactions whose values were last updated in Heron systems before the specified input value","in":"query","name":"last_updated_max","required":false,"schema":{"example":"2022-03-01T14:27:05.538146","format":"date-time","type":"string"}},{"description":"End user id of transaction","in":"query","name":"end_user_id","required":false,"schema":{"type":"string"}},{"description":"Heron generated Id of transaction","in":"query","name":"heron_id","required":false,"schema":{"example":"txn_6zCaHQaJdYQZVfhU4LxMxj","type":"string"}},{"description":"Filter by whether the transaction is recurring","in":"query","name":"is_recurring","required":false,"schema":{"type":"boolean"}},{"description":"Number of transactions to return per page","in":"query","name":"limit","required":false,"schema":{"default":1000,"maximum":10000,"minimum":1,"type":"integer"}},{"description":"Filter by maximum amount of transaction","in":"query","name":"max_amount","required":false,"schema":{"type":"number"}},{"description":"Filter by minimum confidence of annotation associated with transaction","in":"query","name":"confidence_min","required":false,"schema":{"maximum":1,"minimum":0,"type":"number"}},{"description":"Filter by latest transaction upload date - when Heron received the transaction","in":"query","name":"created_date_max","required":false,"schema":{"example":"2020-04-27","format":"date","type":"string"}},{"description":"What to order transactions by","in":"query","name":"order_by","required":false,"schema":{"default":"id_asc","enum":["amount_asc","amount_desc","abs_amount_asc","abs_amount_desc","description_asc","description_desc","timestamp_asc","timestamp_desc","id_asc","id_desc"],"type":"string"}},{"description":"Whether or not to include duplicate transactions in the response. Defaults to false unless request_id is provided, in which case it defaults to true.","in":"query","name":"include_duplicates","required":false,"schema":{"type":"boolean"}},{"description":"Reference Id of transaction","in":"query","name":"reference_id","required":false,"schema":{"type":"string"}},{"description":"Deprecated; see created_date_ or timestamp_date_","in":"query","name":"from_date","required":false,"schema":{"format":"date","type":"string"}},{"description":"Filter by keyword match on transaction description; case insensitive","in":"query","name":"description_keyword","required":false,"schema":{"type":"string"}},{"description":"Filter by earliest transaction timestamp","in":"query","name":"timestamp_date_min","required":false,"schema":{"example":"2020-04-27","format":"date","type":"string"}},{"description":"Filter by latest transaction timestamp","in":"query","name":"timestamp_date_max","required":false,"schema":{"example":"2020-04-27","format":"date","type":"string"}},{"description":"Filter by regex matching transaction description","in":"query","name":"description_regex","required":false,"schema":{"type":"string"}},{"description":"Filter by maximum confidence of annotation associated with transaction","in":"query","name":"confidence_max","required":false,"schema":{"maximum":1,"minimum":0,"type":"number"}},{"description":"Filter by whether the transaction has a matching transaction","in":"query","name":"has_matching_transaction","required":false,"schema":{"type":"boolean"}},{"description":"Filter for transactions whose values were last updated in Heron systems after the specified input value","in":"query","name":"last_updated_min","required":false,"schema":{"example":"2022-03-01T14:27:05.538133","format":"date-time","type":"string"}},{"description":"Filter by transaction code","in":"query","name":"transaction_code","required":false,"schema":{"type":"string"}},{"description":"Filter by the heron_id of the category that the transaction is annotated with","explode":true,"in":"query","name":"category_heron_id","required":false,"schema":{"default":[],"example":"ctg_9iLZUbAEYQ6w6E9QwDvWE4","items":{"type":"string"},"nullable":true,"type":"array"},"style":"form"},{"description":"Request-Id header returned in the response of POST transactions. Sending this parameter will return all transactions sent in a particular POST request, including any duplicates.","in":"query","name":"request_id","required":false,"schema":{"type":"string"}},{"description":"Filter by earliest transaction upload date - when Heron received the transaction","in":"query","name":"created_date_min","required":false,"schema":{"example":"2020-04-27","format":"date","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"_meta":{"properties":{"next_url":{"type":"string"},"page":{"type":"integer"},"pages":{"type":"integer"},"per_page":{"type":"integer"},"prev_url":{"type":"string"}},"type":"object"},"_summary":{"properties":{"returned_transactions":{"type":"integer"},"transactions":{"type":"integer"}},"type":"object"},"transactions":{"items":{"$ref":"#/components/schemas/TransactionGetOutput"},"type":"array"}},"type":"object"}}},"description":"OK"},"401":{"description":"Unauthorized"}},"security":[{"BasicAuth":[]}],"tags":["Transactions"]},"post":{"description":"Enrich and categorize transactions. Please send a **maximum of 1,000 transactions** per request to avoid timeouts.\n","externalDocs":{"description":"Find more info here","url":"https://docs.herondata.io/transactions"},"requestBody":{"content":{"application/json":{"schema":{"properties":{"transactions":{"items":{"$ref":"#/components/schemas/TransactionInput"},"type":"array"}},"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"_summary":{"properties":{"request_id":{"description":"Unique UUID per request","type":"string"}},"type":"object"},"transactions":{"items":{"$ref":"#/components/schemas/TransactionPostOutput"},"type":"array"}},"type":"object"}}},"description":"OK"},"413":{"content":{"application/json":{"schema":{"properties":{"code":{"example":413,"type":"integer"},"description":{"example":"Transaction batch size exceeds max of 2500","type":"string"},"name":{"example":"Payload Too Large","type":"string"}},"type":"object"}}},"description":"Payload Too Large"}},"security":[{"BasicAuth":[]}],"summary":"Enrich and categorize transactions","tags":["Transactions"]}},"/api/transactions/{heron_id}/feedback":{"put":{"description":"Provide feedback on a Transaction's Categories and Merchants","requestBody":{"content":{"application/json":{"schema":{"properties":{"transaction":{"$ref":"#/components/schemas/TransactionFeedbackSchema","type":"object"}},"type":"object"}}},"description":"A partial Transaction object with the suggested Category and/or Merchant. If you provide a heron_id for Category or Merchant, you don't need to provide other fields. If you don't know the Merchant heron_id nor name, you can just send the is_correct boolean. If heron_id is provided, we disregard name and label. If is_correct is set to true, we disregard all other Merchant fields\n","required":true},"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"}},"security":[{"BasicAuth":[]}],"summary":"Transaction Feedback","tags":["Transactions"]}}},"produces":["application/json"],"responses":{"401":"Unauthorized"},"security":[{"BasicAuth":[]}],"servers":[{"description":"Production","url":"https://app.herondata.io"}]}