Truffle's REST API lets you build custom integrations. Manage positions, invite candidates, pull interview results, and subscribe to webhooks that fire when candidates complete interviews. To use the API, create an API key in Company Settings → API & Integrations, pick a permission level (Read, Write, or Admin), and send the key in the X-API-Key header with every request to https://api.hiretruffle.com. The full endpoint reference is at app.hiretruffle.com/docs. Paid plans only.

How to create an API key

To create an API key, open Company Settings and switch to the API & Integrations tab.

Open Company Settings from the sidebar.
Click the API & Integrations tab.
Click the API Keys sub-tab.
Click Create API Key.
Give it a name and short description so you remember what it's for.
Choose a permission level (below).
Copy the key immediately. It's shown only once.

You can create multiple keys (one per integration, for example). Regenerate or delete any key from the same page.

Permission levels

Pick the narrowest permission level your integration needs. You can always create a new key with broader permissions later.

Read — pull candidate data, pull position data, pull interview responses and transcripts. Cannot change anything.
Write — everything in Read, plus invite candidates, create positions, and update candidate status. Cannot change account-level settings.
Admin — everything in Write, plus manage webhooks and account-level settings. Only use for integrations that genuinely need admin access.

Authentication and base URL

All requests go to https://api.hiretruffle.com. Pass your API key in the X-API-Key header:

curl https://api.hiretruffle.com/v1/jobs -H "X-API-Key: <your-api-key>"

Every request needs this header. Requests without a valid key return 401 Unauthorized.

Tip: To verify your key works, call GET /v1/test/auth. To verify connectivity without a key, call GET /v1/test/public.

What you can do with the API

The API covers positions (called jobs in the API), candidate invitations, interviews, and webhooks. The complete reference, including request and response schemas, is at app.hiretruffle.com/docs.

Jobs — list, create, fetch, update, and delete positions (/v1/jobs and /v1/jobs/{job_sid})
Invite candidates — invite up to 50 candidates per request to a position (POST /v1/jobs/{job_sid}/invite); only an email address is required per candidate
Interviews — list, fetch, update, and delete interviews (/v1/interviews and /v1/interviews/{interview_sid})
Webhooks — create and manage webhooks programmatically (/v1/webhooks), or use the in-app Webhooks tab described below

Webhooks

Webhooks are HTTP callbacks Truffle sends to a URL you control. Configure them from Company Settings → API & Integrations → Webhooks.

Supported events

interview.completed — fires when a candidate finishes their interview (all responses submitted).
candidate.applied — fires when a candidate is invited to a position.
job.created — fires when a position is activated.

Setting up a webhook

Open the Webhooks tab under API & Integrations.
Click Add Webhook.
Enter a name and the target URL.
Select the events you want to subscribe to.
Save.

Once a webhook is saved, use its menu (⋮) to send a test event, edit it, or delete it.

Delivery history

Every webhook has a delivery history page showing every attempt, the response code your endpoint returned, and any retries. Truffle retries failed deliveries automatically; each webhook has configurable timeout and retry settings.

How do I connect Truffle to other tools?. Zapier is often simpler than the API for common integrations.
What plans does Truffle offer and how does billing work?. API access is a paid-plan feature.

How do I use the Truffle API?