Receipt-Bot API provides a collection of endpoints for uploading documents and associated metadata for data extraction.
\nIt is a REST-based service that authenticates requests using an API key.
\nThe process is divided into two steps;
\nStep 1) Make a request to FileUpload API to start the data extraction by passing the document with base64 encoding.
\nStep 2) Either receive the extracted data on a webhook when the document is processed or make a second request to get the extracted data.
\nOur API uses resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
\nThe base URL for the API is the following:
\n\nThe Receipt Bot API uses an API key to authenticate each request.
\nTo get your API key;
\nRegister an account with Receipt Bot.
\nNavigate to the \"Integration\" page using the \"Business Configuration\" option from the side menu.
\nClick the \"Show Keys\" button at the bottom of the page.
\nYou should be able to see the \"Organization API Key\" and \"Business ID\".
\nNote: If you are an invited user, please ask the account admin to share the keys, as you may not have access to view the keys.
\nTo change your API key, navigate to the Integration page using the \"Business Configuration\" option in your Receipt Bot account and click the \"Generate new key\" button. Your old keys will be invalidated, and a new one will appear on the screen.
\nPlease keep your API key secure and do not share it in publicly accessible locations on your website, GitHub, client-side code, etc.
\nWe return standard response status codes to indicate the status of a request.
\nReceipt Bot enforces a limit of 60 requests per minute. If you exceed this limit and send over 60 requests within a minute, the system will respond with an error carrying the status code 429.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Base URL","slug":"base-url"},{"content":"Authentication","slug":"authentication"},{"content":"Response Codes","slug":"response-codes"},{"content":"Request Throttling","slug":"request-throttling"}],"owner":"14388213","collectionId":"6bd9ad4a-5825-4bf4-be62-f7f76269c434","publishedId":"2sA3kYjLPj","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2024-07-26T13:06:24.000Z"},"item":[{"name":"File Upload","id":"59894509-1946-43db-8299-ccf4a40a836a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"APIKey","value":"{{APIKey}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"businessId\": \"ABC-1234-1234-1234-1234567\",\r\n \"moduleId\": 1,\r\n \"fileName\": \"Example.pdf\", \r\n \"fileContent\": \"The content of the file is converted into a base 64 string\",\r\n \"documentTypeId\": 2\r\n\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.receipt-bot.com/FileUpload","description":"This endpoint uploads a new file to Receipt-Bot for data extraction. You can pass the file as a base64-encoded file.
\nThe end-point only accepts one file per request. (Please create separate requests if you need to upload multiple files. If multiple documents merged into a PDF file are sent in a request, Receipt Bot will split the file into separate documents and provide multiple responses.)
\nThe allowed file formats are PDF, PNG, JPG & JPEG.
\nThe maximum file size allowed per API request is 50 MB, while you can upload files up to 256 MB via the web app.
\nFor information about allowed file formats and upload channels, please refer to the following Help Article: https://www.receipt-bot.com/blog/knowledge-base/upload-documents/
\nThis end-point requires the following data parameters;
\nModule ID can be any of the following.
\nDocument Type can be any of the following;
\nIf the request is successful, the endpoint returns a document ID in response. The document ID is a unique identifier for a document within a business in the Receipt Bot.
\nReceipt Bot will start the extraction process for your uploaded documents (provided you have an active subscription with a positive credit balance. You can find detailed information about credit utilization and billing in Receipt Bot here.)
\nReceipt Bot does not return the extracted data immediately in response. As the extraction process takes some time. There are following two ways to get the extracted data;
\nOption 1) Set up a webhook where Receipt Bot can drop the extracted data once it is available.
\nOption 2) Keep polling the get statement details API until you receive the output.
\nReceipt Bot will return extracted data via HTTP post on your provided Webhook URL. This approach is preferred because it reduces the workload on both systems.
\nYou can set up a Webhook from the integration page on the Receipt Bot web app. Please follow the below steps;
\nLogin to your Receipt Bot account.
(You must be an account owner to be able to set up a Webhook)
Navigate to the \"Integration\" page.
\nClick the \"Connect via API\" button.
\nProvide a friendly, short name for the integration.
\nClick the \"Save & Generate Keys\" button.
\nClick the \"Add Webhook\" button.
\nEnter a Webhook URL.
Note: You can also set up a basic authentication for your webhook URL.
Click the \"Save\" button.
\nYour webhook should now be set up in Receipt Bot. Now, you can export data from Receipt Bot to your application directly.
\nReceipt Bot supports multiple businesses under one account. If you have multiple businesses, you must perform the above action separately for each business.
\nAt present, the system exports data solely for documents within the bank/card statement module. Documents uploaded as Purchase, Sale, or Other will not have their data extracted and sent via webhook.
\nIf a document is deleted by Receipt Bot, its data is not sent over the Webhook.
\nThere are a few additional settings related to the setup of Webhook in Receipt Bot.
\nAuto Export: This setting controls whether the processed documents should be automatically pushed to the provided Webhook URL.
\nExport modified PDF file: The system can automatically split a document under certain conditions. When this occurs, the system returns the document's content as a base64-encoded string. Given the potential size of the data, which can be substantial, there is an option to manage whether the system should return the base64 encoded string.
\nYou must set a URL in your system that should accept a POST request. It should be provided to Receipt Bot as a Webhook URL.
\nYour webhook URL must return a 200-success response status code for incoming requests. If a success response is not returned, Receipt Bot will treat the export as failed and will resend the event up to three times, or until a success response is received.
\nThe data will be exported to the given webhook when extracted. All export attempts are recorded as events in the system. Below is a list of key export events;
\nThis event is generated when a bank/card statement is processed.
\nThe event content includes metadata for the file, extracted header and transaction details.
\nSample response attached with example \"Webhooks Response - Successful Response for Statement Data Export\".
\nThis event is generated when a document is exported from Receipt Bot as a result of a split or merge, creating a new file and document ID in Receipt Bot.
\nThe event content includes metadata & base 64 content for the new file created by Receipt Bot.
\nThis document and document ID would not exist in your system at this stage. The system will send both the document and the extracted data together in two different files as simultaneous events.
\nSample response attached with example \"Webhooks Response - Successful Response for File Export\".
\nReceipt Bot provides the following attributes when exporting the statement data;
\nReceipt Bot provides the following attributes when exporting statement files that were created in Receipt Bot as a result of the split or merge of uploaded documents;
\n","urlObject":{"protocol":"https","path":["FileUpload"],"host":["api","receipt-bot","com"],"query":[],"variable":[]}},"response":[{"id":"950c0cd7-b51c-40a7-b7a1-3628002254a9","name":"Successful Upload Example","originalRequest":{"method":"POST","header":[{"key":"APIKey","value":"ABC12345678","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"businessId\": \"ABC-1234-1234-1234-1234567\",\r\n \"moduleId\": 1,\r\n \"fileName\": \"Example.pdf\", \r\n \"fileContent\": \"The content of the file after converting into a base 64 encoding\",\r\n \"documentTypeId\": 2\r\n\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.receipt-bot.com/Fileupload"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Length","value":"153"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Server","value":"Microsoft-IIS/8.5"},{"key":"X-Rate-Limit-Limit","value":"5s"},{"key":"X-Rate-Limit-Remaining","value":"24"},{"key":"X-Rate-Limit-Reset","value":"2024-06-22T11:01:00.8925069Z"},{"key":"X-Powered-By","value":"ASP.NET"},{"key":"Date","value":"Sat, 22 Jun 2024 11:00:56 GMT"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 200,\n \"message\": \"Document Uploaded Successfully\",\n \"documentId\": \"4\",\n \"processingTime\": \"Expected Processing Time is 30 Minutes\",\n \"apiVersionKey\": \"V3\"\n}"},{"id":"a6427c29-607d-400a-8635-9ffc4a6c60f6","name":"Incorrect API or Business key Passed Example","originalRequest":{"method":"POST","header":[{"key":"APIKey","value":"Required","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"businessId\": \"Abc1234\",\r\n \"moduleId\": 1,\r\n \"fileName\": \"Example.pdf\", \r\n \"fileContent\": \"The content of the file after converting into a base 64 encoding\",\r\n \"documentTypeId\": 2\r\n\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.receipt-bot.com/FileUpload"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Length","value":"109"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Server","value":"Microsoft-IIS/10.0"},{"key":"X-Rate-Limit-Limit","value":"5s"},{"key":"X-Rate-Limit-Remaining","value":"24"},{"key":"X-Rate-Limit-Reset","value":"2024-08-13T14:47:16.5893445Z"},{"key":"X-Powered-By","value":"ASP.NET"},{"key":"Date","value":"Tue, 13 Aug 2024 14:47:11 GMT"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 400,\n \"message\": \"Authentication error, please verify the APIKey or BusinessID.\",\n \"apiVersionKey\": \"V3\"\n}"},{"id":"36fd94d2-7cb3-4f5c-a5d5-9a20cf2369cf","name":"Incorrect base64 string passed","originalRequest":{"method":"POST","header":[{"key":"APIKey","value":"ABC12345678","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"businessId\": \"Abc1234\",\r\n \"moduleId\": 1,\r\n \"fileName\": \"Example.pdf\", \r\n \"fileContent\": \"The content of the file after converting into a base 64 encoding\",\r\n \"documentTypeId\": 2\r\n\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.receipt-bot.com/FileUpload"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Length","value":"119"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Server","value":"Microsoft-IIS/10.0"},{"key":"X-Rate-Limit-Limit","value":"5s"},{"key":"X-Rate-Limit-Remaining","value":"24"},{"key":"X-Rate-Limit-Reset","value":"2024-08-13T15:34:37.5818309Z"},{"key":"X-Powered-By","value":"ASP.NET"},{"key":"Date","value":"Tue, 13 Aug 2024 15:34:32 GMT"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 400,\n \"message\": \"The provided extension does not match with base64 of the file provided.\",\n \"apiVersionKey\": \"V3\"\n}"},{"id":"e8ca53f1-f868-4f21-b988-24348999cfa0","name":"Incorrect Extension Passed Example","originalRequest":{"method":"POST","header":[{"key":"APIKey","value":"ABC12345678","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"businessId\": \"Abc1234\",\r\n \"moduleId\": 1,\r\n \"fileName\": \"Example.nofileextension\", \r\n \"fileContent\": \"@#$%^&abcdadakldl\",\r\n \"documentTypeId\": 2\r\n\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.receipt-bot.com/FileUpload"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Length","value":"79"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Server","value":"Microsoft-IIS/10.0"},{"key":"X-Rate-Limit-Limit","value":"5s"},{"key":"X-Rate-Limit-Remaining","value":"24"},{"key":"X-Rate-Limit-Reset","value":"2024-08-13T15:39:04.8812772Z"},{"key":"X-Powered-By","value":"ASP.NET"},{"key":"Date","value":"Tue, 13 Aug 2024 15:38:59 GMT"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 400,\n \"message\": \"File extension is not provided.\",\n \"apiVersionKey\": \"V3\"\n}"},{"id":"f44ebd55-9428-48d5-9553-89d8bcf29470","name":"Webhooks Response - Successful Response","originalRequest":{"method":"POST","header":[{"key":"APIKey","value":"ABC12345678","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"payload\": [\r\n {\r\n \"file\": {\r\n \"parentDocument\": {\r\n \"documentId\": null,\r\n \"fileName\": null,\r\n \"remainingResponses\": 0\r\n },\r\n \"documentId\": 1,\r\n \"uploadDate\": 1722000646,\r\n \"moduleName\": \"Bank Statement\",\r\n \"moduleId\": 3,\r\n \"fileName\": \"Example.pdf\",\r\n \"source\": \"Web\",\r\n \"uploadUserEmail\": \"Abc@example.com\"\r\n },\r\n \"statement\": {\r\n \"paymentMethod\": {\r\n \"paymentMethodId\": 123,\r\n \"bankName\": null,\r\n \"displayName\": \"None\",\r\n \"accountNumber\": null,\r\n \"paymentMode\": \"None\",\r\n \"currency\": null,\r\n \"bankAddress\": null,\r\n \"bankPhoneNumber\": null,\r\n \"customerName\": null,\r\n \"customerPhoneNumber\": null,\r\n \"customerAddress\": null\r\n },\r\n \"processingNotes\": [],\r\n \"transactions\": [\r\n {\r\n \"uniqueIdentifierId\": 239498,\r\n \"transactionId\": 1,\r\n \"lineId\": \"01566100001000023\",\r\n \"date\": 1640995200,\r\n \"description\": \"desc\",\r\n \"reference\": \"ref\",\r\n \"moneyOut\": 200,\r\n \"moneyIn\": 0,\r\n \"balance\": 0,\r\n \"subAccountReference\": null,\r\n \"memoAmount1\": 0,\r\n \"memoAmount2\": 0\r\n },\r\n {\r\n \"uniqueIdentifierId\": 239499,\r\n \"transactionId\": 2,\r\n \"lineId\": \"01566100002000023\",\r\n \"date\": 1641081600,\r\n \"description\": \"desc\",\r\n \"reference\": \"ref\",\r\n \"moneyOut\": 199,\r\n \"moneyIn\": 0,\r\n \"balance\": 0,\r\n \"subAccountReference\": null,\r\n \"memoAmount1\": 0,\r\n \"memoAmount2\": 0\r\n }\r\n ],\r\n \"closingBalance\": 1000,\r\n \"dateFrom\": 1640995200,\r\n \"dateTo\": 1670630400,\r\n \"recordAs\": null,\r\n \"openingBalance\": -29399,\r\n \"processStatus\": \"Exported\",\r\n \"title\": null,\r\n \"transactionsCount\": 2,\r\n \"chargeablePages\": 1\r\n },\r\n \"message\": \"Success\",\r\n \"apiVersionKey\": \"V2\",\r\n \"businessId\": \"ABC-1234-1234-1234-1234567\",\r\n \"businessName\": \"Demo Business\",\r\n \"eventId\": \"EV_0123\",\r\n \"eventType\": \"StatementDataExport\",\r\n \"occurredAt\": 1722000910,\r\n \"trigger\": null,\r\n \"webhookStatus\": \"Sent\"\r\n }\r\n ]\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.receipt-bot.com/FileUpload"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"Server","value":"Microsoft-IIS/10.0"},{"key":"X-Powered-By","value":"ASP.NET"},{"key":"Date","value":"Sat, 10 Aug 2024 15:13:19 GMT"},{"key":"Content-Length","value":"1245"}],"cookie":[],"responseTime":null,"body":"{}"},{"id":"2b00b60a-543d-4233-ab4d-c013e263b64d","name":"Webhooks Response - Successful Response for File Export","originalRequest":{"method":"POST","header":[{"key":"APIKey","value":"ABC12345678","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"payload\": [\r\n {\r\n \"file\": {\r\n \"parentDocument\": {\r\n \"documentId\": null,\r\n \"fileName\": null,\r\n \"remainingResponses\": 0\r\n },\r\n \"documentId\": 1,\r\n \"uploadDate\": 1724337771,\r\n \"documentTypeName\": null,\r\n \"documentTypeId\": 0,\r\n \"fileContent\": \"The content of the file is converted into a base 64 string\",\r\n \"fileName\": \"Example.pdf\",\r\n \"source\": \"Web\",\r\n \"uploadUserEmail\": \"Abc@example.com\"\r\n },\r\n \"businessId\": \"ABC-1234-1234-1234-1234567\",\r\n \"businessName\": \"Demo Business\",\r\n \"eventId\": \"EV_31957\",\r\n \"eventType\": \"StatementDataExport\",\r\n \"occurredAt\": 1724338171,\r\n \"trigger\": null,\r\n \"webhookStatus\": \"Sent\"\r\n }\r\n ]\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.receipt-bot.com/FileUpload"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"Server","value":"Microsoft-IIS/10.0"},{"key":"X-Powered-By","value":"ASP.NET"},{"key":"Date","value":"Fri, 16 Aug 2024 13:17:44 GMT"},{"key":"Content-Length","value":"1245"}],"cookie":[],"responseTime":null,"body":"{}"}],"_postman_id":"59894509-1946-43db-8299-ccf4a40a836a"},{"name":"Get Statement Details","id":"55fa7bdf-af97-434e-b092-ca8a19639244","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"APIKey","value":"Required","type":"text"}],"body":{"mode":"raw","raw":"{\r\n\"businessId\":\"ABC-1234-1234-1234-1234567\", \r\n\"documentId\":1 \r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.receipt-bot.com/StatementDetails","description":"This endpoint can be used to get the bank statement details.
\nNote: The data extraction process takes some time; therefore, avoid hitting the API immediately after uploading the document. It is recommended that you set up a webhook interface so that Receipt Bot automatically sends you extracted data on your endpoint once it is processed.
\nThis endpoint requires the following data parameters;
\nThe output will follow this structure.
\nIf the document ID passed in the input does not exist in the Receipt-Bot, you will get a message \"Document ID doesn't exist\".
\nIf any mandatory field is missed or passed with incorrect casing in the request, you will get a message: \"Invalid parameter keys, the keys and values are case sensitive.\"
\nIf the APIKey or BusinessID is passed incorrectly, the system will return a message: \"Authentication error, user or business key not found.\"
\nIf the document is currently in processing, the system will return a message key under the payload key with the value \"Document is currently queued to be processed\".
\nIf the document requested is not processed and the processing has been paused due to any reason, then you will receive a message \"Document processing paused; [reason for pause].\"
\nIf the document ID in the request was modified and split into multiple documents, the payload will return the list of all split documents.
\nEach item in the list will contain the same information received from the webhooks. The definition of keys is under the heading \"Event Details—Statement Data Export.\"
\nIf the document you uploaded has been modified and split into multiple files, you will receive data for all the split files created from this document under the payload key.
\n