Quickstart

This guide takes you from no key to your first real data. You need a client account on the Enterprise or Custom plan, and a terminal with curl or Node 18 or later.

1. Make an API key

1. Sign in to the HILLS web app and open Developers in the sidebar (/dashboard/developers).
2. Choose New API key.
3. Give it a name that says where it runs, for example ERP sync.
4. Pick its scopes. The defaults are members:read, catalog:read, earnings:read, payouts:read and links:read. Add ddex:write, ddex:validate or the webhook scopes only if you need them.
5. Pick when it expires, or leave it with no expiry.
6. Copy the key from the Copy your API key now dialog. It is shown once. After that, the list shows only its prefix.

You see Developers if you are the account owner, or if your team role has the API keys permission. If the button is greyed out, your plan doesn’t include the API: ask your HILLS Music contact.

Keep the key on your server. Put it in an environment variable, never in a web page or an app people download.

export HILLS_API_KEY="hm_live_…"

2. Check the key

GET /me answers with the account behind the key, the key’s name, its scopes and its expiry. It needs no particular scope.

curl "https://api.hillsmusic.com/v1/me" \
  -H "Authorization: Bearer $HILLS_API_KEY"

const res = await fetch("https://api.hillsmusic.com/v1/me", {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
console.log(res.status, await res.json());

A working key answers 200:

{
  "partner": { "id": 12, "name": "Nova Records", "email": "ops@novarecords.com" },
  "environment": "production",
  "key": {
    "id": 3,
    "name": "ERP sync",
    "prefix": "hm_live_ab12cd34",
    "environment": "production",
    "scopes": ["catalog:read", "earnings:read"],
    "expires_at": null,
    "created_at": "2026-10-01T09:00:00Z"
  }
}

environment is always production. There is one kind of key. If you get 401 or 403 instead, the code in the answer says why. See Errors.

GET /ping is another check. It also returns your plan and how many requests you have left this minute. See Account.

3. List your releases

GET /releases needs catalog:read. It returns your artists’ and labels’ releases, newest first, 50 per page.

curl "https://api.hillsmusic.com/v1/releases?limit=10" \
  -H "Authorization: Bearer $HILLS_API_KEY"

const res = await fetch("https://api.hillsmusic.com/v1/releases?limit=10", {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
const { data, next_cursor } = await res.json();
for (const r of data) console.log(r.id, r.title, r.release_status, r.delivery_state);

Each release has release_status (where it is in review) and delivery_state (where it is in the stores). The values are on Statuses. When next_cursor is not null, there are more pages. See Pagination.

To narrow the list, add status, member_id, upc or q. To get one release with its tracks and store-by-store status, call GET /releases/{id}. See Releases.

4. Read your earnings

GET /earnings needs earnings:read. It sums revenue from committed store statements, in USD.

curl "https://api.hillsmusic.com/v1/earnings?by=store&months=6" \
  -H "Authorization: Bearer $HILLS_API_KEY"

const url = new URL("https://api.hillsmusic.com/v1/earnings");
url.searchParams.set("by", "store"); // month (default), release or store
url.searchParams.set("months", "6"); // 1–60, default 12
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
console.log(await res.json());

{
  "by": "store",
  "months": 6,
  "currency": "USD",
  "data": [
    { "key": "Spotify", "label": "Spotify", "amount_usd": 1520.42, "member_share_usd": 1064.29, "units": 412003 }
  ]
}

amount_usd is your total. member_share_usd is the part your revenue splits give your artists and labels. See Earnings.

Next steps

• Authentication: scopes, expiry, rotating and revoking keys.
• DDEX delivery: releases come into HILLS as DDEX ERN batches. The API doesn’t create or edit single releases.
• Webhooks: get told when a release is approved, goes live or a statement is published.
• Rate limits: 120 requests a minute per key on Enterprise.