> For the complete documentation index, see [llms.txt](https://developers.stub.africa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.stub.africa/api-basics.md).

# API basics

The stub Connect API is a RESTful API that allows you to push income, sales, and expense data into a user's stub account.

### Requests and responses

The majority of requests in the stub Connect API are POST requests. The payloads you send are queued and processed asynchronously. A successfully queued payload returns the response below.

```json
// Example response
{
    "error": false,
    "message": "Here's looking at you, kid."
}
```

If the request was unsuccessful or malformed, `error` will be `true` with a reason, when available, contained in the `message`.

### Webhooks

When pushing data asynchronously into stub the result of push will be returned to the specified webhook URL when completed. For data pushes the webhook is optional.

When pulling data asynchronously from stub data will be returned to the specified webhook URL when ready. For data pull the webhook is mandatory.

```json
// Example asynchronous request
{
  "apikey": "sk_test_xxxxxxx",
  "appid": "my-cool-app",
  "uid": "uuid-uuid-uuid",
  "webhook": "https://your.web.hook.com",
  "signature": "string" // an identifier to verify the response is from stub
}
```

### Retries

Webhooks will be retried 4 times using an exponential back-off algorithm in the following time intervals:

1. 10 seconds later
2. 2.5 minutes later
3. 30 minutes later
4. 6 hours later

After the fourth retry the data is discarded.