# Quickstart

## 1. Create an API key

1. Sign in to banta as a user who is allowed to manage the organization's integrations.
2. Go to [Organization settings → Connections & technology → API Keys](https://app.banta.co.il/organization/settings?group=integrations&tab=api).
3. Create a new key, give it a name that describes its use (for example "Website lead form") and choose its permissions. Grant the minimum you need - see [Authentication & permissions](https://docs.banta.co.il/guides/authentication.md).
4. **Copy the key right away.** It is shown only once and cannot be retrieved later.

> Keep the key on the server side only (environment variables or a secrets vault). Never embed it in code that runs in a browser or a mobile app.

## 2. Your first call

Fetch the five most recent leads:

```bash
curl "https://app.banta.co.il/api-service/leads?limit=5" \
  -H "x-api-key: $BANTA_API_KEY"
```

List responses carry a total count:

```json
{
  "data": [
    {
      "id": "6f1c2a4e-0b7d-4b8e-9a51-2f6c3d8e9a10",
      "first_name": "Israel",
      "last_name": "Israeli",
      "phone": "050-0000000",
      "status": "new",
      "created_at": "2026-10-01T09:30:00+00:00"
    }
  ],
  "count": 128
}
```

`count` is the number of records that match the query - not just the ones on the current page. See [Pagination & search](https://docs.banta.co.il/guides/conventions.md).

## 3. Create a lead

```bash
curl -X POST "https://app.banta.co.il/api-service/leads" \
  -H "x-api-key: $BANTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Israel",
    "last_name": "Israeli",
    "phone": "050-0000000",
    "email": "israel@example.com",
    "source": "website"
  }'
```

A successful call returns `201 Created` with the full lead, including its new `id`.

## The same call in popular languages

**JavaScript (Node.js 18+, as an ES module - a `.mjs` file or `"type": "module"` in `package.json`):**

```js
const res = await fetch('https://app.banta.co.il/api-service/leads', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.BANTA_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Israel',
    last_name: 'Israeli',
    phone: '050-0000000',
    source: 'website',
  }),
})

if (!res.ok) {
  const err = await res.json()
  throw new Error(`banta API ${res.status}: ${err.error} ${err.details ?? ''}`)
}
const lead = await res.json()
```

**Python:**

```python
import os
import requests

res = requests.post(
    "https://app.banta.co.il/api-service/leads",
    headers={"x-api-key": os.environ["BANTA_API_KEY"]},
    json={
        "first_name": "Israel",
        "last_name": "Israeli",
        "phone": "050-0000000",
        "source": "website",
    },
    timeout=30,
)
if not res.ok:
    err = res.json()
    raise RuntimeError(f"banta API {res.status_code}: {err.get('error')} {err.get('details', '')}")
lead = res.json()
```

## Testing safely

There is no sandbox: every key works on your organization's live data, and so does the **Test Request** button on every endpoint in this reference. Those requests go straight from your browser to banta, with no intermediary server, and the key you enter is kept only in the open tab and cleared when you close it.

- Create a dedicated test key with only the permissions you are testing (for example `leads:read`, `leads:write` and `leads:delete`), and revoke it when you're done.
- Mark test records so they're easy to find, for example `"source": "api-test"` on a lead, and delete them when you're done (`DELETE /leads/{id}`).

## Postman, Insomnia and typed clients

There is no official SDK. The OpenAPI document is complete enough to generate one:

- **Postman / Insomnia** - import `https://docs.banta.co.il/openapi.json` and set the `x-api-key` header from a collection variable.
- **TypeScript** - generate types and use a typed fetch client:

  ```bash
  npx openapi-typescript https://docs.banta.co.il/openapi.json -o banta.d.ts
  npm install openapi-fetch
  ```

- **Python** - `openapi-python-client generate --url https://docs.banta.co.il/openapi.json`

## Next steps

- [Authentication & permissions](https://docs.banta.co.il/guides/authentication.md) - how to scope a key down.
- [Errors](https://docs.banta.co.il/guides/errors.md) and [Rate limits](https://docs.banta.co.il/guides/rate-limits.md) - how to handle failures.

---

Part of the banta API documentation. Full index: https://docs.banta.co.il/llms.txt