Skip to main content
Most Sela integrations have four parts:
  1. Sending leads to Sela
  2. Handling live transfers
  3. Letting Sela know when to stop calling
  4. Receiving call and lead updates
This guide covers each part in the order most integrations build them, focusing on the main decisions rather than field-by-field details. Full request and response definitions are available in the API Reference. Sela provides an API token during setup. Include it in the Authorization header of every API request unless Sela has explicitly configured an unauthenticated endpoint for your integration.

​
Sending Leads to Sela

​
Lead types

Every lead sent to Sela belongs to a lead type—commonly called a campaign. The lead type determines how Sela handles the lead, including which configuration applies and which talk track the agent follows. During setup, Sela creates a lead type for each of your use cases and gives you its ID. You can see all lead types available to your account with GET /api/lead-types/. To see what metadata a specific lead type accepts, call GET /api/lead-types/{id}/. The response describes the metadata fields configured for that lead type, including each field’s name, purpose, and expected format. These fields feed directly into the conversation. A talk track may reference the lead’s name, property information, loan details, or other customer-specific data, so providing more complete information allows for a more personalized call.

​
Creating leads

Sela prefers a flat JSON payload, with standard and customer-specific fields sent together as top-level keys. This keeps the request simple and lets most CRMs and lead providers send data to Sela without restructuring it. You are not limited to the fields in the lead type definition. Additional fields can support routing, scheduling, transfers, customer-specific integrations, and other functionality outside the talk track. Send all useful context you have when creating the lead. Better source data helps the Sela agent personalize the conversation and avoid asking for information you already know. The default way to send a lead is POST /api/leads/. Use this endpoint whenever your system can format its request using Sela’s standard lead fields and the custom fields configured for your lead type. The response includes the Sela lead ID. Store this ID—it identifies the lead in future updates, including requests to stop calling. Some lead sources cannot change the structure or destination format of their requests. In those cases, Sela can optionally configure a customer-specific lead-ingest endpoint that accepts the existing payload and transforms it into the format Sela needs. Use lead ingest when the standard endpoint is not practical. Authentication can be optional for this endpoint, allowing you to share its unique URL with a third-party lead provider without also sharing your Sela API token.

​
How Sela determines the lead’s state and timezone

Before calling, Sela determines the lead’s location and local time so it knows when a call is allowed. It first looks for the lead’s state in us_state, then state, and then property_state. If none is available, it derives the state from zip and then property_zip. For the timezone, Sela uses an explicit timezone when you provide one. Otherwise, it checks the contact ZIP code, contact state, property ZIP code, property state, and available IP location information, in that order. If none of those identifies the location, Sela uses a configured safe default timezone and calling window. Once Sela knows the lead’s local time, it applies the relevant federal, state-specific, and account-level calling restrictions. Because inference is a fallback, provide accurate state and ZIP information whenever possible.

​
Live Transfer Flow

Live transfer functionality is optional and should be configured when your workflow requires Sela to connect borrowers with a person during the call. There are two ways to make this connection: a warm transfer, where Sela brings a loan officer onto the call, and an escalation, where the call is forwarded directly.

​
Warm transfer

During a warm transfer, the main Sela agent stays on the line with the borrower—the borrower is never left waiting alone. In parallel, Sela creates a transfer sub-agent that places a separate call, called the transfer leg, to your transfer destination and works to get a loan officer on the line. Once an officer is available, the transfer leg is joined with the borrower’s call, bringing the loan officer, borrower, and main Sela agent together for the handoff. The main agent then leaves so the borrower and loan officer can continue speaking directly.

​
Receiving queue and IVR behavior

How your receiving queue handles the transfer leg can make or break a warm transfer. After the leg is answered, the line should remain silent while a loan officer is located. Recorded messages, repeated announcements, or other unexpected audio can interfere with the flow. How long the queue should hold the transfer leg open depends on whether a loan officer can realistically join:
  • If an officer may become available within the next few minutes, keep the transfer leg open for up to three minutes.
  • If there is no chance an officer will answer—for example, because no one is signed in—hang up immediately or do not ring at all. This lets Sela return to the borrower and continue with the configured unavailable-transfer flow.
The rule of thumb is simple: give viable transfers enough time, and end impossible transfers quickly. Holding the line open when no one can answer only wastes the borrower’s time.

​
Escalation

Escalation is a more direct path to a person than a warm transfer. It is generally triggered when a borrower asks to speak with someone, says they do not want to continue with the AI, or meets another customer-defined condition. There is no transfer sub-agent or availability check; the call routes directly to the escalation destination. That destination may differ from the loan-officer transfer queue, allowing escalations to reach another team, such as customer support. Decide during setup where escalations should go and what should happen if the destination does not answer.

​
Receiving live lead updates

During the conversation, Sela may collect additional information from the borrower. Optionally subscribe to the LEAD_UPDATED webhook to receive that information while the call is still in progress. These updates let your system refresh the lead record in real time, making the latest details available to the loan officer before or during the handoff. The fields included depend on what the configured talk track collects.

​
Calendar Bookings (Optional)

Live transfers only work when someone is available immediately. Calendar integration provides an optional fallback and is particularly useful when leads belong to specific loan officers rather than whoever is next in a shared queue. If the assigned officer misses a call or cannot join a live transfer, Sela can offer the borrower an available meeting time and book it directly on that officer’s calendar. The borrower leaves the call with a confirmed follow-up, and the lead stays with its owner. Two things must be in place:
  1. The lead-to-loan-officer assignment must be visible to Sela so the correct calendar is used. Confirm during setup which lead field identifies the assigned officer.
  2. The officer’s connected calendar must accurately reflect working hours, existing meetings, time off, and other unavailable periods.
If you enable calendar booking, decide during setup when Sela should offer it: after the assigned officer does not answer, after a warm transfer cannot be completed, or when the borrower asks to speak at another time.

​
Telling Sela to Stop Calling a Lead

Your CRM may learn that Sela should no longer call a lead—for example, because the borrower converted through another channel or the file was withdrawn. Decide which conditions in your workflow should stop Sela calls, and configure your CRM to update Sela whenever one occurs. When one of those conditions occurs, send PATCH /api/leads/{sela_lead_id}/ using the Sela lead ID returned when the lead was created, and set the lead’s status to CANCELLED. This is a simple stop instruction; your CRM can retain the detailed reason without translating it into a Sela status. DNC requests are distinct from cancellation. If a lead revokes consent to be contacted—through your team, your CRM, or another channel—update the Sela lead with that DNC information rather than only cancelling it. This ensures Sela records the consent revocation and does not contact someone who has withdrawn consent. For the full set, see the Lead Statuses and Call Outcomes pages in the Documentation tab.

​
Receiving Updates from Sela

Sela sends updates to your systems through webhooks. Decide early how you want to track Sela lead status in your systems: which statuses matter, where they are stored, and what they should trigger. That decision determines which events to subscribe to. DNC events should be part of every integration. Beyond that, the main choice is between receiving an update after every call and receiving updates only when a lead reaches a terminal status. See Webhook Responses for payload structure and authentication options.

​
Receiving DNC updates

Subscribe to CALL_DNC when a lead requests no further calls and SMS_DNC when a lead requests no further text messages. When either event arrives, record and enforce the preference in your systems. DNC status is also included in every webhook payload, so events such as CALL_COMPLETE or LEAD_LOST capture it as well. Call and SMS preferences are independent, so a DNC request on one channel applies only to that channel.

​
Option 1: Receive every completed call

Subscribe to CALL_COMPLETE to receive a webhook after each completed Sela call, including calls that do not produce a final lead outcome. Choose this option when you want call-by-call activity in your CRM or want the lead record updated throughout the Sela calling process. A single lead may produce many CALL_COMPLETE events over its lifetime.

​
Option 2: Receive terminal lead status changes

If you only need to know the final outcome for each lead, subscribe to the terminal lead status events:
  • LEAD_CLOSED
  • LEAD_CLOSED_INCOMPLETE
  • LEAD_LOST
  • LEAD_SCHEDULE_COMPLETED
  • LEAD_BAD_NUMBER
  • LEAD_OUT_OF_TERRITORY
The last two events correspond to the terminal lead statuses BAD_NUMBER and OUT_OF_TERRITORY. This option produces far fewer updates than CALL_COMPLETE, typically one final outcome per lead lifecycle. Choose between these options with Sela during integration setup.

​
Testing webhooks without placing a call

After configuring your webhook subscriptions, you can test them without placing another call by using: POST /api/agents/webhooks/replay-recent-chat/ Provide the Sela lead IDs and webhook triggers you want to test:
Sela builds the webhook payload from each lead’s most recent completed call and sends it to the subscriptions configured for the requested triggers. The lead must belong to the authenticated API user and have at least one completed Sela call. The endpoint queues delivery asynchronously and returns 202 Accepted; this confirms that the replay was queued, not that your destination successfully processed it. Verify receipt, authentication, field mapping, and idempotent handling in your system. Replaying a webhook does not place a new call or change the lead’s status.

​
When a Newer Lead Replaces an Older One

Sometimes a lead already sent to Sela arrives again as a newer version—for example, when the same person fills out another form. Sela calls this reengagement. Rather than creating a second lead, Sela keeps the existing lead record and overwrites its data with the newer metadata. This can replace the lead’s external_id, which is its ID in your CRM. Future updates are then associated with the newer CRM lead ID, and the older record stops receiving updates. If your CRM needs to know before this happens, subscribe to LEAD_BEFORE_REENGAGEMENT. This event fires before the overwrite and identifies the older CRM lead that is about to stop being called and updated. Use it to close the old record, link it to the newer one, or otherwise preserve your internal lead history. This subscription is recommended when you need to track newer duplicates replacing older CRM leads.

​
Testing the Integration

  • Create a lead and confirm that it is connected to the correct campaign with the expected metadata.
  • If warm transfers are enabled, run a transfer with a loan officer available. Confirm that the transfer sub-agent reaches the officer and that the participants are joined correctly.
  • If warm transfers are enabled, run the flow with no loan officers available. Confirm that Sela follows the configured unavailable-transfer behavior.
  • If calendar booking is enabled, confirm that Sela offers valid times from the correct officer’s calendar and creates the booking successfully.
  • Send a CANCELLED update using the Sela lead ID. Confirm Sela stops calling the lead.
  • Trigger CALL_DNC and SMS_DNC separately. Confirm that each event updates the correct channel in your systems.
  • Use the webhook replay endpoint to test each configured subscription and trigger without placing another call.
  • Verify that information gathered during a call is communicated correctly back into your CRM.