How to use the API keys page in Credibled
The API Keys page lets you connect your own application or ATS to Credibled, set up a sandbox environment for safe testing, configure webhooks, and access the full API documentation. This guide walks you through every section.
Who this is for: Account admins and developers. Regular user accounts do not have access to the API Keys page.
In this article 1. How to access the API Keys page 3. Setting up your sandbox environment |
1. How to access the API Keys page
The API Keys page is only accessible from the admin portal. If you have not accessed the admin portal before, see our article: How to access the admin portal in Credibled.
1 | Open the account menu Click your name in the top-right corner of the screen (shown as Hi, [Your Name]). A dropdown appears with three options: Profile, Admin portal, and Log out. |
2 | Click "Admin portal" Select Admin portal from the dropdown. This opens the admin area with an expanded left navigation, including Billing, Settings, and API Keys. |
3 | Click "API Keys" in the left menu In the left sidebar, select API Keys. This is where you manage everything related to your API integration. |
2. Overview of each section
The API Keys page is divided into four main sections.
| Section | What it does |
| API Documentation | Opens the full API reference in a new tab, including all endpoints, request formats, and authentication details. |
| Your API Keys | Create and manage API keys for your sandbox or production environment. You can hold up to 10 keys per account. |
| Webhook Configuration | Configure a URL to receive real-time push notifications when a check's status changes. Optional: you can poll the API instead. |
| Sandbox Environment | A safe testing space that returns dummy results. No checks run here are billed. |
| Rate limit: The API supports up to 500 requests per second per API key. |
3. Setting up your sandbox environment
The sandbox lets you test your integration fully without affecting your live account or incurring any charges.
| Important: All check results returned in the sandbox are dummy data. Criminal record results, credit checks, and all other check types return randomised test values. None of these results are real. |
| Checks run through the sandbox are never billed. You can run as many test checks as you need at no cost. |
1 | Create the sandbox Scroll to the Sandbox Environment section at the bottom of the page. Click + Create Sandbox. This creates an isolated test environment linked to your account. |
2 | Sync your settings Once the sandbox is created, click Sync Settings. This copies your production configuration into the sandbox: branding colours, logo, app title, domain, white-label settings, and country and address information. We strongly recommend doing this before running any tests so your test environment matches your live setup. |
3 | Confirm the sandbox is active After creation, the sandbox status shows Active. You will also see a usage counter showing how many test applications have been run this hour (limit: 100 per hour). A yellow banner at the top of the screen confirms: "You're testing in a sandbox. Changes you make here don't affect your live account." |
4 | Create your sandbox API key You are now ready to create an API key for the sandbox. See Section 4 below for instructions. |
4. Creating your API key
You need an API key to authenticate every request sent to the Credibled API. Keys are environment-specific: create one in the sandbox for testing, and a separate one in production when you go live.
1 | Click "Create API Key" Click the + Create API Key button at the top right of the API Keys page. Give your key a clear, descriptive name such as "Sandbox test" or "Production integration". |
2 | Copy and store your key securely Your API key is shown only once at the time of creation. Copy it immediately and store it securely in your environment variables or a secret manager. Do not hardcode it directly in your application code. |
3 | Include the key in your requests Pass your API key in the curl -X GET "https://api.credibled.com/auth/endpoint" \ -H "X-API-Key: YOUR_API_KEY_HERE" \ -H "Content-Type: application/json" |
5. Accessing the API documentation
The full API reference covers all available endpoints, request and response formats, authentication details, and example calls.
1 | Click "API Documentation" At the top of the API Keys page, click the API Documentation button. This opens the full reference in a new tab. The documentation is available from both the sandbox and the production view at any time, even before you create a key. |
6. Configuring webhooks
Webhooks allow Credibled to automatically notify your application when a check's status changes, so your system can react in real time rather than polling the API on a schedule.
| Webhooks are optional. If you only need to pull results by calling the API directly, you do not need to configure a webhook. |
1 | Locate the Webhook Configuration section On the API Keys page, scroll down to the Webhook Configuration section. The toggle will show as Disabled by default. |
2 | Enter your webhook URL In the Webhook URL field, paste the endpoint URL from your application. This is the URL Credibled will send a POST request to whenever a check's status changes. The endpoint must be publicly accessible over HTTPS. |
3 | Enable the webhook Toggle the Webhook Active switch to enable it. Once active, Credibled will start sending notifications to your URL as checks move through their statuses. |
When webhooks fire
Background-check webhooks fire on provider status updates, not only when a check finishes. You will receive a notification when a check moves into any of the following:
| Status | What it means |
| In Progress | The candidate has submitted their application and the check is running. |
| Action Required | Something is needed before the check can continue. |
| Cancelled | The application was reported as cancelled, unresponsive, or expired. |
| In Dispute | The result is being disputed. |
| Complete | The check has finished and a result is available. |
Handling the notification
Notifications are sent as a JSON POST carrying data_type: "background_check", along with an X-HMAC-Signature header you can verify to confirm the request came from Credibled. Your endpoint should:
| Return a 200 OK promptly. Verify the X-HMAC-Signature header before trusting the payload. Treat payloads as idempotent, since the same status may arrive more than once. |
Failed deliveries are not retried. If your endpoint is unreachable, times out, or returns an error, the failure is logged and the notification is not sent again. If you need guaranteed status updates, poll the status endpoint rather than relying on webhooks alone:GET /api/external/v1/background-checks/{uuid}/status/ |
| Tip: Configure and test your webhook in the sandbox environment first. Webhook settings are environment-specific, so you will need to configure the production webhook separately when you go live. |
7. Moving to production
Once your integration is tested and working in the sandbox, follow these steps to switch to your live environment.
1 | Switch to the production environment Click the Switch to Production button in the top-right corner of the screen. This exits the sandbox view and returns you to your live account. You can move back and forth between the two environments at any time. |
2 | Create a production API key On the production API Keys page, click + Create API Key to generate your live key. This is a separate key from your sandbox key. |
3 | Configure your production webhook If you are using webhooks, set up the Webhook URL again in the production environment. Webhook settings do not carry over from the sandbox. |
4 | Update your application Replace the sandbox API key in your integration with your new production key. All checks run with the production key are real, and standard billing applies. |
| Never use your sandbox key in a production environment. Sandbox results are dummy data and will not reflect real background check outcomes. |
Still need help? Contact our support team at support@credibled.com or reach out through the chat widget inside your account. |