Nova Help

Make your first API request

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.

Updated in release 0.0.1

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

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

curl -s "https://app.novabmp.com/v1/crm/accounts/?query=smith&page_size=5" \
  -H "Authorization: Bearer $NOVA_KEY" \
  -H "Accept: application/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:

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 Errors and how to recover.

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:

Beyond the documented operations, the key can call anything it has the permissions for; Find the operation to call lists every operation.

Next

Was this helpful?