---
key: make-your-first-api-request
title: Make your first API request
audience: developer
section: api/getting-started
routes: []
since: 0.0.1
updated: 0.0.1
status: published
summary: "Create an API key in Nova, call the API from the command line, read the response, and know what to try next. Ten minutes, no OAuth."
keywords: [quickstart, getting started, curl, api key, first request, hello world, integration]
related: [api-authentication, choose-an-api-key-or-a-connected-app, api-conventions, api-errors, find-what-to-call, api-reference]
---

The fastest way into the Nova API is an organization API key. It is a bearer
token your own software sends on every call, it works for one organization,
and an admin can revoke it at any time. This walk-through uses `curl`; any
HTTP client works the same way.

## 1. Create a key

An admin opens **Administration › Integrations & API › API & Connected
Apps**, stays on the **API keys** tab and presses **Create API key**. Give it
a name, choose what it may do (start with read-only), choose an expiry, and
copy the key. Nova shows the key once. The staff article is
[[create-an-api-key-for-your-own-software]].

Keys look like `nova_live_…`. Treat one like a password: keep it in your
software's secret store, never in source or a URL.

## 2. Find out who you are

```bash
export NOVA_KEY="nova_live_…"
curl -s https://app.novabmp.com/v1/organizations/me/ \
  -H "Authorization: Bearer $NOVA_KEY" \
  -H "Accept: application/json"
```

The response is your organization: its `uid`, name and branches. If you get
`401`, the key was revoked, expired or mistyped. If you get `403`, the key
does not have the `organization:read` scope.

## 3. List some customers

```bash
curl -s "https://app.novabmp.com/v1/crm/accounts/?query=smith&page_size=5" \
  -H "Authorization: Bearer $NOVA_KEY" \
  -H "Accept: application/json"
```

```json
{
  "data": [
    {
      "uid": "acct_5f1c2a9e7b3d4c10",
      "account_number": "ACC-000042",
      "display_name": "Smith Household",
      "account_type": "household",
      "lifecycle_status": "Active",
      "contact_count": 2
    }
  ],
  "total": 1
}
```

Every record has a `uid`. That is the only identifier you send back to Nova:
`GET /v1/crm/accounts/acct_5f1c2a9e7b3d4c10/`. Record numbers such as
`ACC-000042` are for people; integer ids never appear.

## 4. Change something

Writing needs a `:write` scope on the key. This creates a task:

```bash
curl -s -X POST https://app.novabmp.com/v1/tasks \
  -H "Authorization: Bearer $NOVA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title": "Call Smith about the furnace filter", "account_id": "acct_5f1c2a9e7b3d4c10"}'
```

`account_id` takes the account's `uid`; the response is the new task with
its own `uid` and `status`.

Creating a task takes an `Idempotency-Key`, so a retried request never makes
a duplicate; the reference shows which other operations take one. Errors come
back in one envelope with a stable `error.code` you can switch on; see
[[api-errors]].

## What limits a key

A key can be given anything the organization can do, up to what the admin
creating it can do themselves. The admin can also:

- list actions that wait for a person to approve them each time
  ([[wait-for-a-person-to-approve]]);
- set a daily cap on changes, allowed addresses, branches and an expiry
  ([[api-limits]]).

Beyond the documented operations, the key can call anything it has the
permissions for; [[find-what-to-call]] lists every operation.

## Next

- Browse the documented operations in the [[api-reference]], and every
  operation in the index: [[find-what-to-call]].
- Get told when records change instead of polling: [[api-webhooks]].
- Let an assistant such as Claude or ChatGPT use the same API: [[connect-an-ai-agent]].