HumMatch Partner API

1. Get a sandbox key

No signup form, no approval wait — POST /api/v1/sandbox-key issues a key instantly. The full key is only ever shown in this one response, so save it right away.

curl -X POST https://hummatch.me/api/v1/sandbox-key \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","name":"Your Company"}'

Response:

{
  "apiKey": "hm_sandbox_3f9a1c2b7d8e4f5061a2b3c4d5e6f708",
  "keyPrefix": "hm_sandbox_3",
  "mode": "sandbox",
  "rateLimitPerMinute": 30
}

Every call below sends that key back as the X-API-Key header.

2. Normalize a vocal profile

POST /api/v1/vocal-profile turns a range (note names or MIDI numbers) into a normalized profile you can reuse in the next two calls.

curl -X POST https://hummatch.me/api/v1/vocal-profile \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"rangeLow":"D3","rangeHigh":"C5"}'

3. Score a specific song against that profile

GET /api/v1/songs/{slug}/fittakes a real catalog slug and a URL-encoded profile, and returns a real match score plus the same “why it fits” explanation HumMatch shows on the site. This example uses a real slug from the live catalog, love-is-a-game-adele.

curl -G https://hummatch.me/api/v1/songs/love-is-a-game-adele/fit \
  -H "X-API-Key: $API_KEY" \
  --data-urlencode 'profile={"rangeLow":"D3","rangeHigh":"C5"}'

4. Find shared-range songs for a group

POST /api/v1/group-fittakes 2+ profiles and returns the group’s shared vocal range plus ranked candidate songs — the same logic behind HumMatch’s SquadMatch feature, run entirely in-memory against the profiles you send. No group is created on our side.

curl -X POST https://hummatch.me/api/v1/group-fit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"profiles":[{"id":"singer-1","rangeLow":"C3","rangeHigh":"E4"},{"id":"singer-2","rangeLow":"A3","rangeHigh":"G5"}]}'