Receipt-Bot API provides a collection of end-points that can be used for uploading documents and associated metadata for data extraction. It is a SOAP-based service that authenticates requests using the API keys.
\nThe extracted data is returned to a webhook provided by you.
\nOur API uses resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
\n![](\"https://www.receipt-bot.com/assets/images/mian-img-final.jpg\")
\n\nThe base URL for the API is following; https://api.receipt-bot.com/
\nThe Receipt Bot API uses API keys to authenticate each request. API key is generated for each user and business. You can generate API keys using Integration Data page in the web app.
\nTo get your API key;
\n* Register an account with Receipt Bot
* Navigate to integration data screen and click on the show keys button.
Please keep your API key secure and do not share on publicly accessible locations on your website or on GitHub, and client-side code etc.
\nYour API key is linked with your user account password, changing your password updates your API keys as well. So if you need to change the key at any time, simply change the account password. \nSimilarly, when changing user account password, please also remember to update your keys in the API authentication setup at your end.
\nReceipt Bot API uses standard REST response codes for indicating the API response, such success or failure for an API request.
\nIn general;
\n* Codes in the 2xx range indicate success.
* Codes in the 4xx range indicate an error that failed given the information provided. (e.g. a required parameter was omitted, a charge failed, etc.).
* Codes in the 5xx range indicate an error from our servers (Please report these error at hello@receipt-bot.com, if any identified).
Receipt Bot limits the number of requests that can be received within a minute to maximum of 60.
If you send more than 60 requests within a minute, then the system will return an error with status code 429.
This end-point is used to upload a new file to Receipt-Bot a base64 string for data extraction.
\n* The end-point only accepts one file per request. (Please create separate requests if you want to upload multiple files or merge documents in a single PDF file to upload document in a single request.)
* The allowed file formats are PDF, PNG, JPG & JPEG.
* The maximum file size allowed per request from API is 50 MB while you can upload files up to 256 MB via web app.
For 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/
This end-point requires the following data parameters;
\nDocument Type can be following;
\n* Pass \"0\" to upload a \"Purchase Invoice\"
* Pass \"1\" to upload an \"Other\" document
* Pass \"2\" to upload a \"Statement\"
* Pass \"3\" to upload a \"Sale Invoice\"
In case of success, the end-point returns a document ID in response. The document ID is a unique identifier of a document within a business in Receipt Bot.
\nReceipt Bot will extract data for your uploaded documents, (provided you have an active subscription with a positive credits balance.) You can find detailed information about credits utilization and billing in Receipt Bot here.
\nReceipt Bot will return extracted data via HTTP post on your provided Webhook URL. You can set up the integration and provide webhook and authentication details on the integration data page in the Receipt Bot web app.
\nYou can find out more about API integration on the following help article: configuring a Webhook URL here. (Article Coming Soon :)
\nWhen the data has been extracted and gone through the validations, it will be exported to the given webhook. All export attempts are recorded as events in the system. Below is a list of key export events;
\nStatement Data Export
* This event is generated when a statement is processed.
* The event content includes metadata for the file and extracted statement details.
* Sample response attached with example \"W5 - Webhooks Response - Successful Response for Statement Data Export\".
File Export
* This event is generated when a document is exported from Receipt Bot as a result of split or merge, creating a new file and document ID in Receipt Bot.
* The event content includes metadata & base 64 content for the new file created by Receipt Bot.
* This 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.
* Sample response attached with example \"W6 - Webhooks Response - Successful Response for File Export\".
Note: If you do not return a 200 success event for any specific response then the system will continue to send that event for up to three times until a success is received.
\nReceipt Bot provides the following attributes when exporting the statements data;
\nBusinessID
* Definition: Receipt Bot generated unique business/entity identifier.
* Data type: String
BusinessName
* Definition: Business name as provided by you for business setup.
* Data type: String
EventID
* Definition: Unique ID assigned for each export attempt by Receipt Bot to your provided webhook.
* Data type: String
EventType
* Definition: Type of events initiated by Receipt Bot for exporting data to your webhooks.
* Allowed values: FileExport, StatementDataExport
* Data type: String
Trigger
* Definition: The trigger which initiaed this event.
* Allowed values: AutoExport, ManualExport
* Data type: String
WebhookStatus
* Allowed values: Scheduled, Succeeded, Re-scheduled, Failed
* Data type: String
OccurredAt
* Definition: Date time when the event occurred.
* Data type: Integer
DocumentID
* Definition: Receipt Bot generated unique document identifier for each business.
* Data type: Integer
UploadDate
* Definition: Date time when the Receipt Bot received your document.
* Data type: Integer
DocumentTypeName
* Definition: Document type identified by the system.
* Allowed values: Invoice or Receipt, Other Document, Bank or Card Statement
* Data type: String
DocumentTypeID
* Definition: Document type identified for the system.
* Allowed values: 0, 1, 2
* Integer
FileName
* Definition: Original file name provided when uploading a document.
* Data type: String
Source
* Definition: The source from which a document is received.
* Allowed values: Web, Mobile, Email, System, API
* Data type: String
UploadUserEmail
* Definition: The user email who uploaded the document.
* Data type: String
DocumentID
* Definition: The unique identifier for the source document from which the current document has been generated.
* Data type: Integer
FileName
* Definition: The name of the source document that was passed on document upload.
* Data type: String
RemainingResponses
* Definition: This shows the count of responses that you will further receive for the source document. If a single document contains multiple bank statements then the system splits the data by header and provide you with a separate response for each file.
* Data type: Integer
ClosingBalance
* Definition: Closing balances as extracted from the statement. Positive integer for an account credit balance (a deposit that is an accounting asset) and a negative integer for an account debit balance (a loan or credit card payable amount, that is an accounting liability.)
* Data type: Integer
OpeningBalance
* Definition: Opening balances as extracted from the statement. Positive integer for an account credit balance (a deposit that is an accounting asset) and a negative integer for an account debit balance (a loan or credit card payable amount, that is an accounting liability.)
* Data type: Integer
DateFrom
* Definition: Start date of the period for statement.
* Data type: Integer
DateTo
* Definition: End date of the period for statement.
* Data type: Integer
DocumentSubType
* Definition: The subtype for the document classify documents into different groups requiring different data handling.
* Allowed values: Bank Statement, Credit Card Statement, Loan/Mortgage Statement, Merchant Account Statement, PayPal Statement, Duplicate Document, Processing Error. You can further read about what each document sub-type represents from the following help article: Review and download bank statements
* Data type: String
ProcessStatus
* Definition: The status of the document in the processing cycle.
* Allowed values: Processing, Processed, Paused, Exported.
* Data type: String
Title
* Definition: Title as extracted from the bank statement.
* Data type: String
ProcessingNotes
* Definition: Processing Notes are added in case of validation failures or errors during the processing of a document. For example, the line balances did not reconcile with the header balances or the document was identified as duplicate. Processing notes are not errors and do not appear as error messages.
* Data type: List (String)
PaymentMethodID
* Definition: Unique ID assigned to each payment method.
* Data type: Integer
BankName
* Definition: Bank name as extracted from the statement.
* Data type: String
DisplayName
* Definition: Unique name assigned to each account by Receipt Bot or by the user.
* Data type: String
AccountNumber
* Definition: Last four digits of the account number as extracted by the system.
* Data type: String
PaymentMode
* Definition: Type of bank account like Bank, Credit Card or PayPal.
* Allowed values: Bank, Credit Card, PayPal, None
* Data type: String
Currency
* Definition: Default currency for the payment method.
* Data type: String
TransactionID
* Definition: ID refers to the sequence of rows in a statement.
* Data type: Integer
Date
* Description: Transaction Date; as extracted from the statement and standardised to address any gaps. Note: If there are multiple columns for dates in a statement, Receipt Bot only considers the date at which the transaction impacted the statement balance. Example; Some credit cards have a transaction date (when the payment occurred) and a value date (when the payment got approved by the financial institution and increased the payables. Receipt Bot will extract the value date)
* Data type: Integer
Description
* Definition: It is the particulars or narration extracted for a transaction.
* Data type: String
Reference
* Definition: This includes the extracted reference or transaction type.
* Data type: String
MoneyOut
* Definition: Money Out; is the amount paid out from the account.
* Data type: Integer
MoneyIn
* Definition: Money In; is the amount received into the account.
Note: Even if the money in and money out amounts are in a single column in the uploaded document, in the export file, the amounts are mapped to the relevant columns.
* Data type: Integer
Balance
* Definition: Balance includes the extracted running balance amounts from the statement. The balance column will be included in the output if it was available in the uploaded statements and it can blank.
* Data type: Integer
SubAccountReference
* Definition: If the statement has multiple accounts, then the account reference is added against each transaction to indicate which account/card this transaction relates to.
* Data type: String
MemoAmount1
* Definition: If there are additional columns in a statement that do not impact the balance and are only included as transaction detail, e.g. charges, fee, interest etc, those columns are extracted as memo amount. The data extraction validations do not cover the memo amount columns
* Data type: Integer
MemoAmount2
* Definition: Additional extracted data, similar to memo amount 1.
* Data type: Integer
Receipt Bot provides the following attributes when export statement files that were created in Receipt Bot as a result of split or merge of uploaded documents;
\nDocumentID
* Definition: Receipt Bot generated unique document identifier.
* Data type: Integer
UploadDate
* Definition: Date time when the Receipt Bot received your document.
* Data type: Integer
DocumentTypeName
* Definition: Document type identified for the system.
* Allowed values: Invoice or Receipt, Other Document, Bank or Card Statement
* Data type: String
DocumentTypeID
* Definition: Document type identified for the system.
* Allowed values: 0, 1, 2
* Integer
FileName
* Definition: File name assigned by Receipt Bot when the document was created.
* Data type: String
FileContent
* Definition: File content converted to a base64 string.
* Data type: String
Source
* Definition: The source from which a document is received. In the case of a document created by Receipt Bot, the source is, \"System\".
* Allowed values: Web, Mobile, Email, System, API
* Data type: String
UploadUserEmail
* Definition: The user email who uploaded the document.
* Data type: String
DocumentID
* Definition: The unique identifier for the source document from which the current document has been generated.
* Data type: Integer
FileName
* Definition: The name of the source document that was passed on document upload.
* Data type: String
RemainingResponses
* Definition: This shows the count of responses that you will further receive for the source document. If a single document contains multiple bank statements then the system splits the data by header and provide you with a separate response for each file.
* Data type: Integer
This end-point can be used to get the extracted bank statement data.
\nNote: The data extraction process takes some time therefore avoid hitting the API immediately after uploading the document. It is recommended to setup a webhook interface so that Receipt Bot automatically send you extracted data on your endpoint once it is processed.
\nThis end-point requires the following data parameters;
\nThe system will return a payload that will contain the extracted statements data.
\nThe output will contain the following keys;
\nAPIVersionKey
* This key will return the webhooks version setup for your business.
Message
* This key will return a detailed message if any error occurs in the request. If no error occurs and the request is completed successfully then system will return \"success\".
* The list of possible values are mentioned below.
Payload
* This key will return a list of documents. In most cases, you will receive only one item in the payload list that will be based on the document ID that is passed in the request body.
* If the document ID in request was modified and split into multiple documents, this key will return the list of all split documents.
* Each item in the list will contain the same asreceived from the webhooks. You can read the definition of keys under the heading of \"Event Details - Statement Data Export\".
If the document you uploaded has been modified and split into multiple files then you will receive data for all the split files that are created from this document under the payload key.
\n","urlObject":{"path":["StatementDetails"],"host":["https://api.receipt-bot.com/BankStatementService","svc"],"query":[],"variable":[]}},"response":[{"id":"eeacd323-087e-4430-b47d-ccbf365fd66b","name":"Success Response","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n\t\"APIKey\":\"\",\r\n\t\"BusinessID\":\"\",\r\n\t\"DocumentID\":\"\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.receipt-bot.com/BankStatementService.svc/StatementDetails"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Cache-Control","value":"private"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Server","value":"Microsoft-IIS/10.0"},{"key":"X-AspNet-Version","value":"4.0.30319"},{"key":"X-Powered-By","value":"ASP.NET"},{"key":"Date","value":"Fri, 10 Feb 2023 14:48:06 GMT"}],"cookie":[],"responseTime":null,"body":"{\n \"APIVersionKey\": \"V2\",\n \"Message\": \"success\",\n \"Payload\": [\n {\n \"BusinessID\": \"vZU3K933W7r7lqDaRO8DDw==\",\n \"BusinessName\": \"Brilliant Business\",\n \"EventID\": \"EV_306991\",\n \"EventType\": \"GetStatementData\",\n \"File\": {\n \"DocumentID\": 76,\n \"DocumentTypeID\": 2,\n \"DocumentTypeName\": \"Bank Statement\",\n \"FileName\": \"DocID74_P2.pdf\",\n \"ParentDocument\": {\n \"DocumentID\": 74,\n \"FileName\": \"March April 2022.pdf\"\n },\n \"Source\": \"System\",\n \"UploadDate\": 1669292307,\n \"UploadUserEmail\": \"demo@receipt-bot.com\"\n },\n \"OccurredAt\": 1680005361,\n \"Statement\": {\n \"ChargeablePages\": 1,\n \"ClosingBalance\": -61.15,\n \"DateFrom\": 1646092800,\n \"DateTo\": 1648598400,\n \"DocumentSubType\": \"Bank Statement\",\n \"OpeningBalance\": -30.00,\n \"PaymentMethod\": {\n \"AccountNumber\": \"0000\",\n \"BankAddress\": null,\n \"BankName\": \"Standard Bank\",\n \"BankPhoneNumber\": null,\n \"Currency\": \"GBP\",\n \"CustomerAddress\": null,\n \"CustomerName\": null,\n \"CustomerPhoneNumber\": null,\n \"DisplayName\": \"Standard Bank-0000\",\n \"PaymentMethodID\": 37553,\n \"PaymentMode\": \"Bank\"\n },\n \"ProcessStatus\": \"Exported\",\n \"ProcessingNotes\": [],\n \"Title\": \"XYZ (PTY) LTD\",\n \"Transactions\": [\n {\n \"Balance\": -180.00,\n \"Date\": 1646179200,\n \"Description\": \"BANK CHARGES\\n!CARD REPLACEM4278193441522307\",\n \"LineID\": \"00706100001000076\",\n \"MemoAmount1\": 0,\n \"MemoAmount2\": 0,\n \"MoneyIn\": 0,\n \"MoneyOut\": 150.00,\n \"Reference\": \"\",\n \"SubAccountReference\": \"\",\n \"TransactionID\": 1,\n \"UniqueIdentifierID\": 5725377\n },\n {\n \"Balance\": -30.00,\n \"Date\": 1646956800,\n \"Description\": \"TRANSACTION REVERSAL\\nCARD REPLACEMENT FEE\",\n \"LineID\": \"00706100002000076\",\n \"MemoAmount1\": 0,\n \"MemoAmount2\": 0,\n \"MoneyIn\": 150.00,\n \"MoneyOut\": 0,\n \"Reference\": \"\",\n \"SubAccountReference\": \"\",\n \"TransactionID\": 2,\n \"UniqueIdentifierID\": 5725378\n },\n {\n \"Balance\": -31.15,\n \"Date\": 1648166400,\n \"Description\": \"EXCESS INTEREST\",\n \"LineID\": \"00706100003000076\",\n \"MemoAmount1\": 0,\n \"MemoAmount2\": 0,\n \"MoneyIn\": 0,\n \"MoneyOut\": 1.15,\n \"Reference\": \"\",\n \"SubAccountReference\": \"\",\n \"TransactionID\": 3,\n \"UniqueIdentifierID\": 5725379\n },\n {\n \"Balance\": -61.15,\n \"Date\": 1648598400,\n \"Description\": \"MEMBERSHIP FEE\\nUCOUNT\",\n \"LineID\": \"00706100004000076\",\n \"MemoAmount1\": 0,\n \"MemoAmount2\": 0,\n \"MoneyIn\": 0,\n \"MoneyOut\": 30.00,\n \"Reference\": \"\",\n \"SubAccountReference\": \"\",\n \"TransactionID\": 4,\n \"UniqueIdentifierID\": 5725380\n }\n ],\n \"TransactionsCount\": 4\n },\n \"WebhookStatus\": \"Sent\"\n }\n ]\n}"}],"_postman_id":"8e81a760-5f2f-4328-9a36-aab73e15aed2"}],"event":[{"listen":"prerequest","script":{"id":"cc31fe5b-d1a8-4114-b62d-235665eff401","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"8117cf5c-fb3d-4197-82ae-e5f191aaefc9","type":"text/javascript","exec":[""]}}],"variable":[{"key":"base_url","value":"https://api.receipt-bot.com/"},{"key":"api_key","value":""},{"key":"business_id","value":""},{"key":"file_name","value":""},{"key":"DocumentTypeId","value":"1"},{"key":"document_id","value":"","type":"string"},{"key":"file_content_base64","value":""}]}