Skip to main content

How do I use the Truffle API?

Create API keys in Company Settings → API & Integrations. Three permission levels. Read, Write, Admin. Webhooks fire on interview.completed, candidate.applied, and job.created. Paid plans only.

Updated today

For developers building custom integrations on Truffle.


​

Truffle's REST API lets you build custom integrations. Pull candidate data into internal dashboards, push candidates in from your own tooling, 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 call the API with the key in the Authorization header. Paid plans only.


​

How to create an API key

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


​

  1. Open Company Settings from the sidebar.

  2. Click the API & Integrations tab.

  3. Click the API Keys sub-tab.

  4. Click Create API Key.

  5. Give it a name and short description so you remember what it's for.

  6. Choose a permission level (below).

  7. 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.


​

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

  1. Open the Webhooks tab under API & Integrations.

  2. Click Create webhook.

  3. Enter the target URL and a friendly name.

  4. Select the events you want to subscribe to.

  5. Click Test webhook to verify your endpoint responds.

  6. Save.


​

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 with exponential backoff; after 24 hours of failed retries the delivery is marked as failed and stops retrying.


​

Authentication

Pass your API key as a bearer token in the Authorization header:


​

Authorization: Bearer <your-api-key>


​

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


​

Rate limits

The API is rate-limited per key. Standard limits are generous enough for normal integration workloads; high-volume use cases should batch requests and respect the X-RateLimit-Remaining response header.


​

Related

Did this answer your question?