# Push data ### Create a new business linked To create a new business the usual authentication approach is followed except `uid`is not required. The `uid` along with an authentication token will be returned once the business is created. If the email supplied already has a stub account the account details will be returned in addition to the `uid` and token. ## POST /api/push/business > ```json {"openapi":"3.1.0","info":{"title":"stub Connect API","version":"1.0.1"},"servers":[{"url":"https://test.connect.stub.africa"}],"security":[{"ApiKeyAuth":[]},{"TokenAuth":[]},{"AppIdAuth":[]},{"OAuth2":["openid"]},{"OpenID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key needed to access the endpoints"},"TokenAuth":{"type":"apiKey","in":"header","name":"X-Token","description":"Token needed to access the endpoints"},"AppIdAuth":{"type":"apiKey","in":"header","name":"X-AppId","description":"AppId needed to access the endpoints"},"OpenID":{"type":"openIdConnect","openIdConnectUrl":"https://auth.stub.africa/.well-known/openid-configuration"}}},"paths":{"/api/push/business":{"post":{"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"required":["businessname","firstname","lastname","email"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["data"],"additionalProperties":false}},"application/transit+msgpack":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"required":["businessname","firstname","lastname","email"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["data"],"additionalProperties":false}},"application/transit+json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"required":["businessname","firstname","lastname","email"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["data"],"additionalProperties":false}},"application/edn":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"required":["businessname","firstname","lastname","email"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["data"],"additionalProperties":false}}}},"responses":{"200":{},"400":{},"401":{}},"tags":["Push data"]}}}} ``` *** ### Update business information Update the business data created by your app. ## POST /api/push/business/update > ```json {"openapi":"3.1.0","info":{"title":"stub Connect API","version":"1.0.1"},"servers":[{"url":"https://test.connect.stub.africa"}],"security":[{"ApiKeyAuth":[]},{"TokenAuth":[]},{"AppIdAuth":[]},{"OAuth2":["openid"]},{"OpenID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key needed to access the endpoints"},"TokenAuth":{"type":"apiKey","in":"header","name":"X-Token","description":"Token needed to access the endpoints"},"AppIdAuth":{"type":"apiKey","in":"header","name":"X-AppId","description":"AppId needed to access the endpoints"},"OpenID":{"type":"openIdConnect","openIdConnectUrl":"https://auth.stub.africa/.well-known/openid-configuration"}}},"paths":{"/api/push/business/update":{"post":{"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["uid","data"],"additionalProperties":false}},"application/transit+msgpack":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["uid","data"],"additionalProperties":false}},"application/transit+json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["uid","data"],"additionalProperties":false}},"application/edn":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"businessname":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"industry":{"type":"string"},"phone":{"type":"string"},"vatregistered":{"type":"boolean"},"region":{"type":"string"},"email":{"type":"string"}},"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["uid","data"],"additionalProperties":false}}}},"responses":{"200":{},"400":{},"401":{}},"tags":["Push data"]}}}} ``` *** ### Asynchronously record income Record income and send it to the account of the business specified by the `uid` {% openapi src="/files/i28ZJB6aUpE9wfIzCdVJ" path="/api/push/income" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} *** ### Asynchronously record an expense Create an expense and send it to the account of the business specified by the `uid` {% openapi src="/files/i28ZJB6aUpE9wfIzCdVJ" path="/api/push/expense" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} *** ### Asynchronously record a sale Record a sale and send it to the account of the business specified by the `uid` {% openapi src="/files/i28ZJB6aUpE9wfIzCdVJ" path="/api/push/sale" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} *** ### Asynchronously record multiple income and expenses Push a batch of income and expenses for a specific user. {% openapi src="/files/i28ZJB6aUpE9wfIzCdVJ" path="/api/push/many" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} *** ### Asynchronously push settlement data Push settlement data including income records, expense records, and optional settlement summary. This endpoint creating new records or updating existing ones based on the provided ID. Income and expenses in the same batch are typically paid out together in a single bank deposit or settlement. \ ## POST /api/push/settlement > ```json {"openapi":"3.1.0","info":{"title":"stub Connect API","version":"1.0.1"},"servers":[{"url":"https://test.connect.stub.africa"}],"security":[{"ApiKeyAuth":[]},{"TokenAuth":[]},{"AppIdAuth":[]},{"OAuth2":["openid"]},{"OpenID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key needed to access the endpoints"},"TokenAuth":{"type":"apiKey","in":"header","name":"X-Token","description":"Token needed to access the endpoints"},"AppIdAuth":{"type":"apiKey","in":"header","name":"X-AppId","description":"AppId needed to access the endpoints"},"OpenID":{"type":"openIdConnect","openIdConnectUrl":"https://auth.stub.africa/.well-known/openid-configuration"}}},"paths":{"/api/push/settlement":{"post":{"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"income":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"},"productid":{"type":"string"}},"required":["id"],"additionalProperties":false}},"expenses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"}},"required":["id"],"additionalProperties":false}},"settlement":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"date":{"type":"string"}},"required":["id"],"additionalProperties":false}},"additionalProperties":false}},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}},"application/transit+msgpack":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"income":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"},"productid":{"type":"string"}},"required":["id"],"additionalProperties":false}},"expenses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"}},"required":["id"],"additionalProperties":false}},"settlement":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"date":{"type":"string"}},"required":["id"],"additionalProperties":false}},"additionalProperties":false}},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}},"application/transit+json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"income":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"},"productid":{"type":"string"}},"required":["id"],"additionalProperties":false}},"expenses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"}},"required":["id"],"additionalProperties":false}},"settlement":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"date":{"type":"string"}},"required":["id"],"additionalProperties":false}},"additionalProperties":false}},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}},"application/edn":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"income":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"},"productid":{"type":"string"}},"required":["id"],"additionalProperties":false}},"expenses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"name":{"type":"string"},"accountid":{"type":"string"},"notes":{"type":"string"},"currency":{"type":"string","enum":["ZAR","USD","EUR","GBP"]},"amount":{"type":"number"},"vat":{"type":"number"}},"required":["id"],"additionalProperties":false}},"settlement":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"fee":{"type":"number"},"date":{"type":"string"}},"required":["id"],"additionalProperties":false}},"additionalProperties":false}},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}}}},"responses":{"200":{},"400":{},"401":{}},"tags":["Push data"]}}}} ``` *** ### Asynchronously push settlement data using a file This endpoint is complementary to the one above. Instead of send the data in the body of the payload. The path to file uploaded on s3 is included. \ \ File url must be one retrieved from [Pull data](/api-documentation/pull-data.md#generate-upload-s3-url) It is **STRONGLY** advised that a web hook is provided so that error can be received. Both success and errors will be sent to the URL provided. ## POST /api/push/settlement-file > ```json {"openapi":"3.1.0","info":{"title":"stub Connect API","version":"1.0.1"},"servers":[{"url":"https://test.connect.stub.africa"}],"security":[{"ApiKeyAuth":[]},{"TokenAuth":[]},{"AppIdAuth":[]},{"OAuth2":["openid"]},{"OpenID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key needed to access the endpoints"},"TokenAuth":{"type":"apiKey","in":"header","name":"X-Token","description":"Token needed to access the endpoints"},"AppIdAuth":{"type":"apiKey","in":"header","name":"X-AppId","description":"AppId needed to access the endpoints"},"OpenID":{"type":"openIdConnect","openIdConnectUrl":"https://auth.stub.africa/.well-known/openid-configuration"}}},"paths":{"/api/push/settlement-file":{"post":{"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"url":{"type":"string"},"date":{"type":"string"}},"required":["url","date"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}},"application/transit+msgpack":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"url":{"type":"string"},"date":{"type":"string"}},"required":["url","date"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}},"application/transit+json":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"url":{"type":"string"},"date":{"type":"string"}},"required":["url","date"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}},"application/edn":{"schema":{"type":"object","properties":{"apikey":{"type":"string"},"appid":{"type":"string"},"uid":{"type":"string"},"data":{"type":"object","properties":{"url":{"type":"string"},"date":{"type":"string"}},"required":["url","date"],"additionalProperties":false},"webhook":{"type":"string"},"signature":{"type":"string"}},"required":["apikey","appid","uid","data"],"additionalProperties":false}}}},"responses":{"200":{},"400":{},"401":{}},"tags":["Push data"]}}}} ``` #### Web hook responses on settlements There are 3 states post the processing of a settlement. 1. When all the settlements are ingested successfully. ```json { ... "response": { "id": "user_abc123xyz", "error": false, "processed": 150 }, ... } ``` When no settlements are ingested successfully. i.e. total failure ```json { ... "response": { "error": true, "message": "e.g. Error processing s3 file" }, ... } ``` When there is a partial failure ```json { ... "response": { "id": "user_abc123xyz", "error": true, "message": "Processed 20 settlements: 15 successful, 5 failed", "errors": [ { "batch": 2, "settlements": 5, "settlement-ids": [ "settlement_016", "settlement_017", "settlement_018", "settlement_019", "settlement_020" ], "error": "Transaction failed: Invalid date format for settlement date" } ] }, ... } ``` *** ### Asynchronously continue a subscription Notify us that a subscription you are collecting on our behalf has been paid. This entitles the user to another month of access to stub premium. {% openapi src="/files/i28ZJB6aUpE9wfIzCdVJ" path="/api/push/subscription" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} ### Asynchronously cancel a subscription Notify us that a subscription you are collecting on our behalf has been cancelled. This entitles the user to stub premium until the end of the current billing period. Please note that this doesn't cancel subscriptions set up from within stub. {% openapi src="/files/i28ZJB6aUpE9wfIzCdVJ" path="/api/push/cancellation" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} ### Reset all transactional test data This allows you to clear all the data in a test account except the basic account info and subscription status. {% openapi src="/files/i28ZJB6aUpE9wfIzCdVJ" path="/api/push/reset" method="post" expanded="true" %} [stubapi.json](https://4021917470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnpZtVLrUwNfGfPLu2CDM%2Fuploads%2FeByKftwIoFnhQDFwm1Jq%2Fstubapi.json?alt=media\&token=403ccabe-676a-4f26-92d5-c6516301d7e2) {% endopenapi %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.stub.africa/api-documentation/push-data.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.