# Quickstart: your first API call

> Create an API key, check that it works, add a contact and read it back. About five minutes, with nothing to install.

You need a Broker & Agent workspace where you're an owner or admin, and a terminal. Every example uses `curl`, and every call goes to the same base URL:

```text
https://workspace.brokerandagent.com/api/public/v1
```

> [!TIP]
> Connecting Claude or ChatGPT? You don't need a key. Those apps sign in and ask for your approval instead. See [Connect an AI assistant](https://brokerandagent.com/developers/mcp).

## 1. Create a key

1. In Workspace, open **Settings → Integrations & API**.
2. Under **API keys**, choose **New key**.
3. Give it a name, like "Quickstart". Leave the access on **Custom**: **Contacts** starts at **Read and write**, which is all this walkthrough needs.
4. Choose **Create key**, then **Copy**.

The key starts with `bak_` and is shown once. Keep it somewhere safe, like a password manager. We store only a hash of it, so a lost key can be replaced but never recovered.

## 2. Check the key

`GET /me` confirms the key works, names the workspace it belongs to, and says what the key can do in each area.

```bash
curl https://workspace.brokerandagent.com/api/public/v1/me \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

```json
{
  "workspace": { "id": "tnt_…", "name": "Ridgeline Realty" },
  "plan": "pro",
  "website": "growth",
  "apiVersion": "v1",
  "access": { "contacts": "write", "deals": "read", "marketing": "off", "websites": "off", "automations": "off", "webhooks": "write" }
}
```

`plan` is the Workspace plan (`free` or `pro`) and `website` is the website plan (`none`, `launch` or `growth`).

## 3. Add a contact

```bash
curl -X POST https://workspace.brokerandagent.com/api/public/v1/contacts \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dana Reyes",
    "email": "dana@example.com",
    "phone": "(816) 555-0100",
    "intent": "buy",
    "tags": ["open house"]
  }'
```

A new contact answers `201` with `"matched": false`. Send the same request again and you get `200` with `"matched": true`: when the email or phone matches someone you can see, you get that contact back instead of a duplicate.

## 4. Read it back

```bash
curl "https://workspace.brokerandagent.com/api/public/v1/contacts?email=dana@example.com" \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

```json
{
  "contacts": [{ "id": "ct_…", "name": "Dana Reyes", "email": "dana@example.com", "intent": "buy" }],
  "nextCursor": null
}
```

A `null` `nextCursor` means there are no more pages.

## Next steps

- [Send leads](https://brokerandagent.com/developers/api/leads) through the full arrival path, so routing, source tags and your follow-up automation run.
- [Get webhooks](https://brokerandagent.com/developers/webhooks) when a lead lands or a deal moves.
- [Browse the API reference](https://brokerandagent.com/developers/api/reference/contacts) for every call and field.

---

Source: https://brokerandagent.com/developers/quickstart
