Retell AI API Integration: Automate Calls and CRM Workflows

A sales conversation becomes more useful when its outcome reaches the right business system. Retell AI provides APIs for building voice agents, managing calls, and retrieving conversation data that other applications can use.

Listed in G2's AI Voice Agent Platform Software category, Retell supports voice automation across sales, customer service, and business operations.

This article explains its integration methods, examines G2 reviewer experiences, and demonstrates a Retell-to-HubSpot workflow with Node.js code examples.

What can you do with Retell AI API integration?

Retell AI API integration allows developers to connect voice conversations with business workflows, including lead qualification, appointment scheduling, customer support, and call analytics.

The implementation depends on whether an agent needs information during a call or another application must process the outcome afterward.

Custom integrations are particularly useful when businesses need control over call triggers, data mapping, or follow-up actions. For standard workflows, an existing connector may reduce development requirements.

Which Retell AI integration method should you use?

Use a native integration when it supports your required application and workflow. Choose Retell's REST API or SDK for custom call management, custom functions for actions during conversations, and webhooks for event-driven automation.

The key distinction is timing: Custom functions allow agents to interact with external services during conversations, while webhooks notify applications when call events occur.

What do G2 users say about Retell AI API integrations?

G2 reviewers highlight Retell AI's accessible APIs, external connectivity, and support for automated business workflows. Some also identify opportunities for more detailed advanced documentation, easier troubleshooting, and additional native integrations.

What works well for Retell AI integrations?

Reviewers particularly value straightforward API access and the ability to connect voice agents with existing business applications.

One G2 reviewer describes Retell's API as easy to integrate and well-documented for developers. Another reviewer highlights the ease of incorporating Retell into an existing product.

A more detailed example comes from a reviewer building customer support agents, who describes using custom tools to query databases, create support tickets, and trigger workflows during live conversations. This illustrates how an agent can interact with business systems instead of relying entirely on information contained in its initial instructions.

Post-call automation is another use case. A reviewer deploying outbound voice agents describes extracting booking status, objections, and other structured results and passing them to a CRM through webhooks.

These experiences help distinguish two common requirements: accessing information while a conversation is happening and processing its outcome afterward.

Where do users see opportunities for improvement?

Some reviewers suggest expanding the advanced implementation guidance and simplifying the connections to specific applications.

A G2 reviewer describes experimenting with post-call webhooks and custom analysis schemas, while suggesting more detailed troubleshooting information for unsuccessful calls.

Another reviewer specifically suggests more extensive documentation for tool calling.

Native connectivity is another area reviewers have discussed. A reviewer using Retell for sales automation valued custom functions and webhooks but wanted a more direct GoHighLevel integration. Retell now documents a native GoHighLevel connection, so this feedback describes the reviewer's experience at the time rather than a confirmed current integration gap.

These suggestions reflect individual experiences during the research period, not limitations necessarily affecting every Retell user or remaining unresolved in the current product.

How do I connect Retell AI to HubSpot to initiate calls and record call outcomes?

A custom Retell-to-HubSpot integration involves initiating a call, associating it with a CRM contact, receiving the analyzed outcome through a verified webhook, and updating the appropriate HubSpot record.

The following steps include Node.js code for initiating calls, verifying Retell webhooks, and updating HubSpot contacts. The examples illustrate the core operations; the production queue and deployment infrastructure are not included.

Note: The steps and code examples have been checked against Retell AI's and HubSpot's official documentation as of November 2026 but have not been independently tested with live credentials. The example webhook handler is educational; production use requires durable job storage, retry handling, and deployment security.

Step 1: Configure a voice agent

Sign in to the Retell AI dashboard and create a voice agent.

For a lead qualification workflow, configure it to collect relevant information, such as the prospect's requirements and interest in a follow-up.

In the agent editor, open Post Call Extraction and configure custom Boolean fields such as:

• lead_qualified: Indicates whether the prospect meets the qualification criteria.
• followup_needed: Indicates whether additional contact is required.

These fields are examples that you must configure yourself. The integration below uses lead_qualified; additional fields such as followup_needed require their own CRM mapping.

Test the agent's conversation behavior and assign a compatible outbound phone number to the intended agent.

Refer to Retell's agent configuration documentation and Post Call Extraction documentation.

Step 2: Generate API credentials

Create a Retell API key in the dashboard for initiating calls. Identify the Retell API key marked with the webhook verification badge. Retell designates this key for verifying webhook signatures.

For this custom server-to-server HubSpot integration, create a Service Key under Settings > Integrations > Service Keys and grant the crm.objects.contacts.write scope. You need appropriate Developer Tools access and permissions to create a Service Key. Service Keys provide scoped API access without requiring a new legacy private app.

HubSpot disabled creation of new legacy private apps for existing accounts on October 26, 2026. Existing legacy private app credentials remain usable during their supported lifecycle. A valid OAuth access token is another option when an application uses OAuth.

Important: HubSpot Service Keys do not support HubSpot's own app webhook features. That limitation does not prevent this example from receiving Retell webhooks on an independently hosted endpoint and using a Service Key to update HubSpot contacts.

You'll also need a test contact and two custom contact properties, which are described in Step 6.

Store the following credentials and configuration values in a .env file:

• RETELL_API_KEY: Your Retell API key.
• RETELL_WEBHOOK_API_KEY: The API key designated for webhook verification.
• RETELL_FROM_NUMBER: Your configured outbound phone number.
• TEST_TO_NUMBER: Your authorized test number.
• PORT: The local port used by the example webhook server (such as 3000).
• WEBHOOK_BODY_LIMIT: The maximum accepted Retell webhook body size. For example, add WEBHOOK_BODY_LIMIT=2mb to your .env file as an illustrative starting value; adjust it to expected payloads and enforce a reasonable upper bound.
• HUBSPOT_ACCESS_TOKEN: Your HubSpot Service Key or another authorized bearer token.
• HUBSPOT_CONTACT_ID: The ID of your test contact.

Use E.164 international formatting for phone numbers, such as +14155550123.

Keep credentials on your backend and exclude .env from version control. The two Retell API key variables may contain the same value if your designated webhook key is also used to initiate calls.

The example below does not retry outbound call creation automatically. Retrying a request without a supported and correctly configured idempotency mechanism could place a second call.

See Retell's API key documentation and HubSpot's Service Key guidance.

Step 3: Install the Node.js SDK

Initialize a Node.js project and install Retell's SDK, Express, and dotenv:

npm init -y
npm install retell-sdk express dotenv

Configure the project's package.json with "type": "module" to enable JavaScript module syntax.

Use a supported Node.js LTS release, such as Node.js 24 or 26. Both include the built-in fetch() API for the HubSpot request.

Step 4: Initiate a call and identify the CRM contact

To initiate an outbound phone call using the Retell AI API, create a file named create-call.js and initialize Retell's official SDK using your API key:

import 'dotenv/config';
import Retell from 'retell-sdk';

const retell = new Retell({
  apiKey: process.env.RETELL_API_KEY
});

const call = await retell.call.createPhoneCall({
  from_number: process.env.RETELL_FROM_NUMBER,
  to_number: process.env.TEST_TO_NUMBER,
  metadata: {
    hubspot_contact_id: process.env.HUBSPOT_CONTACT_ID
  }
});

console.log('Retell call ID:', call.call_id);

Use the SDK's call.createPhoneCall() method to initiate an outbound call. The request should include:

• from_number: The configured outbound phone number.
• to_number: The authorized destination number.
• metadata: An object containing hubspot_contact_id.

Before placing a call, complete Steps 5 and 6, start the webhook listener with node server.js, expose its /webhook route through a public HTTPS endpoint, and register that URL in Retell. Once the listener is ready, run node create-call.js. A successful request returns a call_id.

Why include the contact ID? It enables the backend to identify which CRM record should receive the call outcome when the webhook arrives.

Retell metadata stores this identifier with the call, but does not automatically make CRM information available to the voice agent during its conversation. If the agent needs contact details while speaking, configure appropriate dynamic variables or external-data access separately.

Retell's Create Phone Call API also documents an optional idempotency_key to help prevent duplicate calls when retrying the same request within one hour. This minimal example omits the field; confirm support in your installed SDK version before adding automatic retries.

Check phone number restrictions: Both numbers must use E.164 formatting. Retell's Create Phone Call API currently limits Retell-purchased phone numbers to US destinations. Other telephony configurations may have different restrictions.

Use only authorized test numbers. Real calls may incur charges and are subject to applicable calling, consent, and do-not-call requirements.

See Retell's Create Phone Call API reference.

Step 5: Receive and verify the analyzed call outcome

To receive call transcripts and post-call analysis through Retell AI webhooks, configure a publicly accessible HTTPS endpoint and register its URL in Retell. Enable the call_analyzed event to receive completed analysis and available transcript data. You can configure an account-level or agent-level webhook. When an agent-level webhook URL is configured, Retell uses it instead of the account-level URL for that agent.

Why use call_analyzed? It is triggered when post-call analysis is complete and includes the call_analysis object. The earlier call_ended event does not include that object.

Before processing an event, verify its authenticity using the original request body.

Retell provides Retell.verify() for checking the X-Retell-Signature header against the raw request body. Use the designated webhook verification API key. The following example lives in server.js and imports the updateContact function from Step 6:

import 'dotenv/config';
import express from 'express';
import Retell from 'retell-sdk';
import { updateContact } from './hubspot.js';

const app = express();
const processedEvents = new Set(); // Demo only: not durable.

app.use('/webhook', express.raw({
  type: 'application/json',
  limit: process.env.WEBHOOK_BODY_LIMIT || '2mb'
}));

app.post('/webhook', async (req, res) => {
  if (!Buffer.isBuffer(req.body)) {
    return res.sendStatus(415);
  }

  const rawBody = req.body.toString('utf8');
  const signature = req.headers['x-retell-signature'];

  if (
    typeof signature !== 'string' ||
    !(await Retell.verify(
      rawBody,
      process.env.RETELL_WEBHOOK_API_KEY,
      signature
    ))
  ) {
    return res.sendStatus(401);
  }

  let payload;

  try {
    payload = JSON.parse(rawBody);
  } catch {
    return res.sendStatus(400);
  }

  if (!payload || typeof payload !== 'object') {
    return res.sendStatus(400);
  }

  const { event, call } = payload;

  if (event !== 'call_analyzed') {
    return res.sendStatus(204);
  }

  if (!call?.call_id) {
    return res.sendStatus(400);
  }

  const eventKey = `${event}:${call.call_id}`;

  if (processedEvents.has(eventKey)) {
    return res.sendStatus(204);
  }

  const contactId = call.metadata?.hubspot_contact_id;
  const summary = call.call_analysis?.call_summary;
  const qualified =
    call.call_analysis?.custom_analysis_data?.lead_qualified;

  // Conservative lead-qualification allowlist.
  // Transfers and other endings need separate review.
  const allowedReasons = new Set([
    'agent_hangup',
    'user_hangup'
  ]);

  if (
    !contactId ||
    call.call_status !== 'ended' ||
    !allowedReasons.has(call.disconnection_reason) ||
    call.call_analysis?.in_voicemail !== false
  ) {
    return res.sendStatus(204);
  }

  if (
    (typeof summary !== 'string' || !summary.trim()) &&
    typeof qualified !== 'boolean'
  ) {
    return res.sendStatus(204);
  }

  try {
    await updateContact(contactId, summary, qualified);
    processedEvents.add(eventKey);
    return res.sendStatus(204);
  } catch (error) {
    console.error('CRM update failed:', error);
    return res.sendStatus(500); // Retell may retry.
  }
});

app.listen(
  Number(process.env.PORT || 3000),
  () => console.log('Webhook server listening')
);

If verification fails, the webhook handler should return an HTTP 401 Unauthorized response.

Plan for oversized webhook events: Large call_analyzed payloads may exceed the server's request-body limit and receive HTTP 413 before the handler runs. The WEBHOOK_BODY_LIMIT setting makes that limit configurable; 2mb is an example, not a guaranteed maximum. Monitor actual payload sizes and align any reverse-proxy limits without removing sensible resource protections. If delivery fails, investigate the rejected event and reconcile the call using Retell's Get Call API when its call ID is known and the required data remains available under your retention settings. Retrieving a call is a recovery step, not an automatic webhook replay.

Do not verify a re-serialized JSON object. Use the raw request body because changes to formatting or key order can invalidate the signature. If using Express, configure raw-body handling for the webhook route before JSON body parsing.

After successful verification, the handler parses the JSON, filters for call_analyzed, checks for non-conversation outcomes, and extracts the CRM contact and analysis fields. After creating hubspot.js in Step 6, start server.js and register its public HTTPS endpoint in Retell before running create-call.js.

For a call_analyzed event, retrieve:

• Contact ID: call.metadata.hubspot_contact_id
• Call summary: call.call_analysis.call_summary
• Qualification result: call.call_analysis.custom_analysis_data.lead_qualified
• Event identifier: A combination of the event name and call.call_id

Before updating HubSpot, check the call outcome and confirm that the required information is available.

Why check the call outcome? Retell can deliver call_analyzed even when an outbound call never connects. Outcomes such as dial_failed, dial_no_answer, and dial_busy should not automatically be classified as unqualified leads.

This conservative example accepts only calls ending with agent_hangup or user_hangup, excludes voicemail, and checks for a contact ID plus a usable summary or Boolean qualification result. Transfers, timeouts, and other endings are intentionally excluded until their handling has been tested.

Missing voicemail analysis also skips the update: The condition in_voicemail !== false requires Retell to explicitly return in_voicemail: false. Calls where Retell omits this field are excluded even if the conversation otherwise completed successfully. Test this conservative behavior against representative calls before using it in production.

Adapt this conservative filter to the business workflow and validate its effect on completed calls.

How reliable is AI-generated lead qualification? Post-call qualification values are AI-generated assessments. Test the configured extraction criteria against representative conversations before using them to trigger automated sales actions.

Protect webhook data: Retell documents that transcripts and recordings may remain accessible through webhook delivery even when post-call storage is disabled. Treat webhook payloads as sensitive; retain only required data and apply access and retention controls.

See Retell's webhook overview and webhook security documentation.

Step 6: Update the HubSpot contact

The CRM update should happen only after webhook authentication and call-data validation. This educational example updates HubSpot directly from server.js; it does not store an update job. Production applications should persist events and use a dedicated worker.

First, create two custom contact properties in HubSpot:

• retell_call_summary: A multi-line text property for the call summary.
• retell_lead_qualified: A single-checkbox property that stores Boolean values using true and false.

These are example internal property names. They are not automatically created by Retell or HubSpot. Confirm that the properties exist and are writable before running the integration.

Create hubspot.js with a function that sends a PATCH request to the HubSpot 2026-09 Contacts endpoint. The property names are the custom fields described above:

export async function updateContact(
  contactId,
  summary,
  qualified
) {
  const properties = {};

  if (typeof summary === 'string' && summary.trim()) {
    properties.retell_call_summary = summary;
  }

  if (typeof qualified === 'boolean') {
    properties.retell_lead_qualified = String(qualified);
  }

  if (Object.keys(properties).length === 0) {
    return;
  }

  const url =
    `https://api.hubapi.com/crm/objects/2026-09/contacts/${encodeURIComponent(contactId)}`;

  const response = await fetch(url, {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${process.env.HUBSPOT_ACCESS_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ properties })
  });

  if (!response.ok) {
    throw new Error(
      `HUBSPOT_UPDATE_FAILED (HTTP ${response.status})`
    );
  }
}

Authenticate using the HubSpot Service Key or another authorized bearer token and submit the modified fields in the JSON properties object.

For the qualification property, convert the Boolean result into the string "true" or "false", as required by the example single-checkbox configuration.

Important: The update assumes the custom properties exist and accept the supplied values. A different property type or configuration may require a different value format.

Omit the summary when it is empty or missing, and omit the qualification property when the result is not a Boolean. This helps prevent incomplete call analysis from overwriting existing CRM values.

HubSpot's 2026-09 APIs enforce applicable account-configured CRM write-validation rules. Invalid requests may be rejected. Correct the submitted data before retrying a validation failure instead of repeatedly submitting the same invalid request. The example reports only a controlled error identifier and HTTP status rather than logging the full HubSpot response body, which could contain CRM-related details.

For implementation details, refer to HubSpot's CRM Objects API documentation, date-based API migration guidance, and CRM write-validation documentation.

Production consideration: The demonstration connects hubspot.js to server.js through an import and calls HubSpot during the webhook request. Its in-memory event tracking does not guarantee exactly-once processing or prevent simultaneous requests from updating the same contact twice. Before deployment, use durable event storage, atomic deduplication, and a separate processing worker. Do not wait for a potentially slow HubSpot request before acknowledging a safely persisted webhook event.

The intended workflow is:

HubSpot contact → Retell phone call → Post-call analysis → Verified webhook → HubSpot contact update

Step 7: Test the complete workflow

Before deployment, use authorized phone numbers and test CRM records to verify the workflow.

Check that:

• The intended voice agent handles the call.
• The outbound phone number supports the selected destination.
• The call metadata contains the correct HubSpot contact ID.
• Outbound call requests are not automatically retried, and repeated execution is tested carefully to avoid duplicate calls.
• Retell delivers call_analyzed with the configured analysis fields.
• The webhook signature is verified using the designated API key and original request body.
• Invalid webhook signatures receive an HTTP 401 response.
• Only allowlisted call endings are eligible for qualification updates; failed, unanswered, voicemail, and unreviewed call endings are excluded.
• The webhook handler invokes the HubSpot update function successfully.
• The correct HubSpot contact receives the expected summary and qualification values.
• Duplicate deliveries are tested, noting that in-memory deduplication does not prevent concurrent or post-restart duplicate updates.
• Missing analysis values are skipped; HubSpot errors return a failure response, and production retry behavior is tested separately.

Before production deployment, replace the demonstration's in-memory deduplication with persistent event storage and a separate processing worker, then test the complete workflow.

What should you consider before deploying Retell AI API integration?

Before deployment, verify agent configuration, call-event timing, webhook security, CRM data mapping, and telephony requirements.

FAQs about Retell AI API integration

Got more questions? Find answers below.

Q1. Can Retell AI access external APIs during a live call?

Yes. Retell supports custom functions that allow agents to interact with external services during conversations. An agent can retrieve appointment availability, access authorized customer information, or trigger a supported action in another application.

Q2. How do you retrieve call transcripts and analysis through the Retell API?

Use Retell's Get Call API with a call ID to retrieve available transcripts, summaries, and post-call analysis. For automated workflows, the call_analyzed webhook delivers completed analysis. Data availability depends on the agent's storage and retention settings.

Q3. Can Retell AI integrate with n8n or Make?

Yes. Retell can connect with automation platforms through supported integrations, APIs, and webhooks. A G2 reviewer specifically describes integration with n8n and Make.com for complex automation workflows. The available setup depends on the platform and the actions you want to automate.

Q4. Can Retell AI automate voice, SMS, and chat conversations?

Retell supports voice agents, chat capabilities, and documented SMS functionality. However, the available API operations and setup requirements differ by channel. Businesses planning multichannel automation should verify supported capabilities and events for each workflow.

Q5. Can developers choose the language model used by Retell AI?

Retell provides language-model configuration options and supports custom LLM approaches for applicable agent setups. The available choices depend on the agent type and response engine, so developers should verify model compatibility for their specific configuration.

Q6. When should you use a native Retell AI CRM integration instead of a custom API integration?

Use a native integration when it supports the required CRM, data fields, and workflow. Choose a custom integration when you need more control over call initiation, record mapping, event processing, or actions that the native connector does not support.

Q7. Is Retell AI API integration free?

Retell AI includes API and webhook access in its pay-as-you-go offering, but using voice agents is not necessarily free. Charges depend on usage, selected models, telephony, and other applicable services. Check Retell AI's current pricing before deployment.

How can you get more value from Retell AI integrations?

Retell AI API integration helps businesses move beyond automated conversations by connecting voice agents with the systems that support sales, customer service, and daily operations. Whether you're updating CRM records, scheduling appointments, or triggering follow-ups, the right integration depends on the data your agents need and the actions you want to automate.

Start with a clearly defined workflow, choose between native connectors and custom APIs, and validate the complete process before deployment.

Exploring other AI-powered voice tools? Read G2's best AI voice assistants listicle to compare capabilities and real user experiences.