Getting Started

Call evaluations are QA scorecards applied to calls — either automatically by AI or manually by a supervisor. Your customers configure their scorecards in Aircall; your integration receives the results through the API and decides how to surface them.

To learn more about how scorecards work from the product side — setup, question types, and the agent review experience — see the Call Scoring help center article.

With Aircall APIs you can use the QA evaluation data to enhance and enrich the other tools in your stack, such as CRM's, Helpdesk, and even other QA tools.

This guide helps you get started retrieving the data. We recommend you also review our API documentation for Call Evaluations and Conversation intelligence webhooks.

Before you start ensure you have:

An Aircall account with an AI Assist Pro license
A call that has been evaluated — either through automated AI scoring or a manual supervisor review.
A valid OAuth access token or Basic Auth credentials

If you are going to use this in an application or flow, the recommend approach is to first wait for the webhook call_evaluation.created to notify you that the evaluation results are ready. The notification will always be sent after the call but it can be ready sooner or later depending on different factors such as call length and so on.

Evaluations can also be updated by a user or supervisor so it's recommended that there is another webhook set for call_evaluation.updated

Walkthrough

Subscribe to the webhook event call_evaluation.created and call_evaluation.updated to react when evaluations are created or updated. If you are new to webhooks check our webhooks tutorial here.

Evaluation webhooks do not contan the full result data. They are just notifications so you know when it's ready. After you receive them you must retrieve the actual result using the REST API. Webhooks include the scorecard name, reviewee_user_id, reviewer_user_idand whether the evaluation was ai_generated , — but no scores, categories, or questions.

Use the call_id from the webhook to call GET /v1/calls/:call_id/evaluations for the complete breakdown. Below we add a basic example for setting it up:

Configure the webhooks

const createWebhook = async (accessToken) => {
   const response = await fetch('https://api.aircall.io/v1/webhooks', {
      method: 'POST',
      headers: {
         'Authorization': `Bearer ${accessToken}`,
         'Content-Type': 'application/json'
      },
      body: JSON.stringify({
         custom_name: 'YOUR_APP_NAME',
         url: 'https://your.server.com/aircall/webhook',
         events: ['call_evaluation.created', 'call_evaluation.updated']
      })
   });

   const data = await response.json();

   if (!response.ok) {
      throw new Error(data.message || 'Failed to create webhook');
   }

   const webhookToken = data.webhook.token;
   return webhookToken;
};

Setup a handler to retrieve call evaluations

const express = require('express');
const app = express();
app.use(express.json());

app.post('/aircall/webhook', async (req, res) => {
  res.sendStatus(200);

  const { event, data } = req.body;

  if (event === 'call_evaluation.created' || event === 'call_evaluation.updated') {
    const callId = data.call_id;

    const response = await fetch(
      `https://api.aircall.io/v1/calls/${data.call_id}/evaluations`,
      {
        headers: { 'Authorization': `Bearer ${process.env.AIRCALL_ACCESS_TOKEN}`}
      }
    );

    const result = await response.json();
    console.log(result);
  }
});

app.listen(3000);

Response

A successful request returns 200 OK with the evaluation object.

{
  "id": 3726831550,
  "call_id": 3726831550,
  "ai_generated": false,
  "created_at": "2026-04-30T12:35:48.169Z",
  "updated_at": "2026-04-30T12:35:48.169Z",
  "created_by": 1779744,
  "updated_by": 1779744,
  "reviewed_at": "2026-04-30T12:35:48.169Z",
  "evaluations": [
    {
      "scorecard": {
        "name": "Scorecard Demo",
        "description": "Lorem ipsum"
      },
      "feedback": "",
      "reviewee_user_id": 1779744,
      "reviewer_user_id": 1779744,
      "score": {
        "score_points": 27.5,
        "total_points": 30,
        "normalized_score": 91.666664
      },
      "categories": [
        {
          "name": "Start",
          "order": 0,
          "score": {
            "score_points": 27.5,
            "total_points": 30,
            "normalized_score": 91.666664
          },
          "questions": [
            {
              "text": "Did the team member introduce themselves and the company?",
              "type": "BINARY",
              "order": 0,
              "strictness": 0,
              "ai_enabled": true,
              "answer": "YES",
              "score": {
                "score_points": 10,
                "total_points": 10,
                "normalized_score": 100
              },
              "feedback": "Agent introduced themselves at the start of the call: “Hello. This is Bernard from Aircall.” That clearly states the agent's name and affiliation. Coaching note: Strong practice — continue to lead with a clear introduction..."
            },

            // ... additional questions in this category
          ]
        }
      ]
    }
  ]
}

QA & Call Evaluations

Getting Started

Walkthrough

Configure the webhooks

Setup a handler to retrieve call evaluations

Response

What’s Next