Account Management and Metrics APIs (Enterprise)
note
These APIs are available to Enterprise users, along with features like passive ("No-CAPTCHA") modes, bot scores, custom threat models, and more. Details on hCaptcha Enterprise (BotStop) are available at BotStop.com.
Some features of your hCaptcha account can be programmatically managed. This includes creating new "site keys" to segregate traffic from different web properties or parts of the same site, e.g. login vs. signup.
You might want to do this in order to separately track how different sites you operate are doing, to change the difficulty level on particular parts of your site(s) to be appropriate for the interactions on that page, or to control your custom threat models on a granular basis.
Getting your API key#
To get an API key, you'll need to do the following:
Go to your dashboard and visit the settings page to get your API Key. Be sure to use your API KEY not your account secret key.
Authenticating against the API#
All of the endpoints described here are protected by an API key that you can obtain by following instructions in the section above.
For testing purposes, simply append this API key to any of the endpoint URLs in this document like so:
However, in production you should use a header-based authentication method. We support two options. The first is to send the "x-api-key" header with your raw API key.
An alternative method to authenticate is to provide your API key via an authorization header in the format of Authorization: Basic [base64-encoded-apikey] like so:
Adding New Site Keys#
To add a new sitekey, POST to https://accounts.hcaptcha.com/dashboard/sitekey
Arguments#
The below arguments can be passed into the POST request body in JSON format
| Parameter | Value | Description |
|---|---|---|
| hostnames | [ "host1.com", "host2.com" ] | Optional. The hostnames where you will use this sitekey. All hostnames must resolve. Format: array of strings. |
| difficulty | (integer) | Optional. The difficulty level for this sitekey. 1: Easy, 2: Moderate, 3: Difficult, 4: Always On. Defaults to 2. Format: integer 1-N. Enterprise users: please see Understanding Scores and Modes for additional details. |
| interests | [ 1, 2, 3 ] | Optional. Set sitekey audience interests. May be used to filter captchas shown for relevance to audience. See Table of Interests below. Up to 3 values allowed. Format: array of integers.. |
Example (curl)#
Response#
You should receive a JSON response similar to the one below, including your new "sitekey" value.
Updating an existing sitekey#
To update a field in an existing sitekey, perform a PATCH against
Arguments#
See the table above for the arguments that can be passed into this endpoint as the JSON body
Example (curl)#
Response#
Table of Interests#
You can specify up to three interests to help target hCaptchas shown to your visitors, referenced by their integer value in the table below.
| Interest Category | Value |
|---|---|
| Business and industry | 1 |
| Cryptocurrencies | 2 |
| Games and entertainment | 3 |
| Family and relationships | 4 |
| Fitness and wellness | 5 |
| Food and drink | 6 |
| Hobbies and activities | 7 |
| News and current events | 8 |
| Shopping and fashion | 9 |
| Sports and outdoors | 10 |
| Technology | 11 |
Fetching Statistics#
The statistics endpoints allow you to check how each of your sitekeys is doing.
To get real-time and timeseries data for a sitekey, GET:
Example (curl):#
Response:#
You should receive a JSON response similar to the one below, which may include daily, weekly, monthly, and yearly fields under the "timeseries" key depending on your sitekey's activity. This information can be up to 24 hours old. The "realtime" key contains the latest statistics.
If no activity at all has occurred, the endpoint will return only the "realtime" key.