Démarrage rapide

Ce guide vous mène de l’absence de clé à vos premières données réelles. Il vous faut un compte client sur l’offre Enterprise ou Custom, et un terminal avec curl ou Node 18 ou plus récent.

1. Créer une clé d’API

1. Connectez-vous à l’application web HILLS et ouvrez Developers dans la barre latérale (/dashboard/developers).
2. Choisissez New API key.
3. Donnez-lui un nom qui indique où elle sera utilisée, par exemple ERP sync.
4. Choisissez ses scopes. Par défaut : members:read, catalog:read, earnings:read, payouts:read et links:read. N’ajoutez ddex:write, ddex:validate ou les scopes webhook que si vous en avez besoin.
5. Choisissez sa date d’expiration, ou laissez-la sans expiration.
6. Copiez la clé depuis la fenêtre Copy your API key now. Elle n’est affichée qu’une fois. Ensuite, la liste n’en montre que le préfixe.

La page Developers s’affiche si vous êtes le propriétaire du compte, ou si votre rôle dans l’équipe dispose de la permission API keys. Si le bouton est grisé, votre offre n’inclut pas l’API : adressez-vous à votre interlocuteur HILLS Music.

Gardez la clé sur votre serveur. Placez-la dans une variable d’environnement, jamais dans une page web ou une application que l’on télécharge.

export HILLS_API_KEY="hm_live_…"

2. Vérifier la clé

GET /me renvoie le compte auquel appartient la clé, le nom de la clé, ses scopes et son expiration. Aucun scope particulier n’est nécessaire.

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());

Une clé valide renvoie 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 vaut toujours production : il n’existe qu’un seul type de clé. Si vous obtenez plutôt 401 ou 403, le code de la réponse en donne la raison. Voir Erreurs.

GET /ping est une autre façon de vérifier. Il renvoie aussi votre offre et le nombre de requêtes qu’il vous reste pour la minute en cours. Voir Compte.

3. Lister vos sorties

GET /releases nécessite catalog:read. Il renvoie les sorties de vos artistes et labels, de la plus récente à la plus ancienne, 50 par 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);

Chaque sortie a un release_status (où elle en est dans la vérification) et un delivery_state (où elle en est sur les plateformes). Les valeurs possibles figurent sur la page Statuts. Tant que next_cursor ne vaut pas null, il reste des pages. Voir Pagination.

Pour affiner la liste, ajoutez status, member_id, upc ou q. Pour obtenir une sortie avec ses titres et son statut plateforme par plateforme, appelez GET /releases/{id}. Voir Sorties.

4. Consulter vos revenus

GET /earnings nécessite earnings:read. Il totalise les revenus issus des relevés de plateformes comptabilisés, en 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 est votre total. member_share_usd est la part que vos répartitions de revenus attribuent à vos artistes et labels. Voir Revenus.

Étapes suivantes

• Authentification : scopes, expiration, rotation et révocation des clés.
• Livraison DDEX : les sorties entrent dans HILLS sous forme de lots DDEX ERN. L’API ne crée ni ne modifie de sorties à l’unité.
• Webhooks : soyez prévenu quand une sortie est approuvée, passe en ligne ou qu’un relevé est publié.
• Limites de débit : 120 requêtes par minute et par clé sur Enterprise.