Web API

Spara's Web API supports completely customizable configurations.

The Spara platform offers powerful integration capabilities through a suite of web API endpoints. Webhooks provide real-time notifications of lead events via POST requests to a customer-defined endpoint, enabling automated workflows, external system synchronization, and timely responses to key updates. APIs allow customers to update and enrich lead data, manage user information, and influence the behavior of our AI engine - supporting deep, flexible integrations. All API interactions must be conducted over HTTPS to ensure secure communication.

Both webhooks and API support basic data types via JSON. These types are not explicitly identified in request values.

string, ex. "John Doe"
integer, ex. 100
boolean, i.e. true or false

Malformed values will be rejected, ex. John Doe. Take care to not cast integer or boolean values as strings, ex. "100".

Important: Spara does not support using this API AND a native CRM integration together, as this may result in data conflicts or unexpected behavior.

For example, Spara does not support using both the API and native Salesforce integration together.

Schema

Spara models leads as a single object with any number of arbitrary fields. For example, if you configure Spara to ask your leads the question "What industry is your company in?" you may decide to name that field industry.

The following fields are standard for all leads:

# Info about the lead.
email(string)
company_name (string)
first_name (string)
last_name (string)
phone_number (string)
job_title (string)
num_employees (integer)

In addition, some leads may have an assigned sales rep in Salesforce:

# Info about Salesforce objects connected to the lead. All fields are strings.
sales_rep_name
salesforce_account_id- The unique identifier of the Salesforce account
salesforce_account_name - The name of the Salesforce account which usually represents the company name
salesforce_account_owner_email - The email address of the Salesforce account owner (account's default sales rep)
salesforce_account_owner_id - The unique identifier of the Salesforce account owner
salesforce_account_owner_name - The first & last names of the Salesforce account owner
salesforce_account_website - The website URL associated with the Salesforce account
salesforce_assigned_sales_rep_email - The email address of the lead's assigned sales rep
salesforce_assigned_sales_rep_id - The unique identifier of the lead's assigned sales rep
salesforce_assigned_sales_rep_name

Authentication

The base URL for all API requests is: https://api.spara.co/v1/

All requests to the API must be authenticated using a Bearer Token in the Authorization header. Each customer can generate one or more API Keys via the user dashboard.

Header Example:

Authorization: Bearer YOUR_API_KEY

Error Responses

400 Bad Request: The request body is malformed JSON or contains invalid data for the metadata fields (e.g., wrong data type). The response body will provide details on the specific error.
401 Unauthorized: Missing or invalid API key.
403 Forbidden: API key does not have access to the specified lead.
404 Not Found: Lead with the provided id does not exist.
422 Unprocessable Entity: The request was well-formed, but semantic validation failed (e.g., attempting to set a field to a value that is logically impossible or not allowed, attempting to update read-only fields (e.g., ip_address)).
429 Too Many Requests: The number of requests has exceeded the rate limits.

Resource: Leads

The primary resource for this API is leads.

Search Leads (GET)

This endpoint allows you to search for leads by their email address. The response will include a unique identifier (id) for each lead, and all known fields about the lead. Zero (no lead found), one (only one lead found), or multiple leads (if there are multiple leads with the same email address) could be returned from this endpoint.

Endpoint: /leads/search

Method: GET

Description: Retrieves the full details of the leads that match the search criteria, including their current fields. If no query parameters are provided, then all leads will be returned.

Query Parameters:

email (string, optional): Email for the lead you wish to retrieve (case insensitive)
start (epoch timestamp integer, optional)
end (epoch timestamp integer, optional)

Note: start and end are inclusive (i.e >= and <=) within a 1 second resolution.

Example Request & Success Response:

GET https://api.spara.co/v1/leads/[email protected]&start=1749470400&end=1749492000
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json


Example Success Response (HTTP 200 OK):

{
  "object": "list",
  "data": [
    {
      "object": "lead",
      "id": "ABC12345",
      "created_at": "2025-06-09T12:00:00Z",
      "updated_at": "2025-06-09T15:15:00Z",
      "url": "https://app.spara.co/conversations/ABC12345",
      "data": {
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Doe",
        "employee_count": "50",
        "is_customer": "false"
      },
      "conversation": {
        "created_at": "2025-06-09T12:00:00Z",
        "initial_url": "https://www.my-site.co/chat/jJyVt7TQ5",
        "messages": []
      },
      "calls": [
          {
            "started_at": "2025-12-12T16:56:47Z",
            "ended_at": "2025-12-12T16:59:30Z",
            "summary": "The lead called interested in purchasing...",
            "events": []
          }
        ]
      }
    }
  ]
}

Get Lead (GET)

This endpoint allows you to retrieve the current state of the lead's fields. This is useful for understanding the existing data before performing an update.

Endpoint: /leads/{id}

Method: GET

Description: Retrieves the full details of a specific lead, including their current fields.

Path Parameters:

id (string, required): The unique identifier for the lead you wish to retrieve.

Example Request & Success Response:

GET https://api.spara.co/v1/leads/ABC12345
Authorization: Bearer YOUR_API_KEY


Example Success Response (HTTP 200 OK):

{
  "object": "lead",
  "id": "ABC12345",
  "created_at": "2025-06-09T12:00:00Z",
  "updated_at": "2025-06-09T15:15:00Z",
  "url": "https://app.spara.co/conversations/ABC12345", // link to conversation
  "data": {
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "employee_count": 50,
    "is_customer": false
  },
    "conversation": {
    "created_at": "2025-06-09T12:00:00Z",
    "initial_url": "https://www.my-site.co/chat/jJyVt7TQ5",
    "messages": []
  },      
  "calls": [
    {
      "started_at": "2025-12-12T16:56:47Z",
      "ended_at": "2025-12-12T16:59:30Z",
      "summary": "The lead called interested in purchasing...",
      "events": []
    }
  ]
}

Create Lead (POST)

This endpoint allows you to create a new lead with or without pre-existing fields that you may have collected externally (e.g., from your CRM).

Endpoint: /leads

Method: POST

Description: Create a new lead

Content-Type: application/json

Body: A JSON object containing the fields you wish to create for the lead

Example Request & Success Response:

POST https://api.spara.co/v1/leads
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "first_name": "Jane",
  "last_name": "Doe",
  "num_employees": 53
}


Example Success Response (HTTP 200 OK):
{
  "object": "lead",
  "id": "ABC12345",
  "created_at": "2025-06-09T12:00:00Z",
  "updated_at": "2025-06-09T15:15:00Z",
  "url": "https://app.spara.co/conversations/ABC12345", // link to conversation
  "data": {
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "employee_count": 50,
    "is_customer": false
  },
    "conversation": {
    "created_at": "2025-06-09T12:00:00Z",
    "initial_url": "https://www.my-site.co/chat/jJyVt7TQ5",
    "messages": []
  },      
  "calls": [
    {
      "started_at": "2025-12-12T16:56:47Z",
      "ended_at": "2025-12-12T16:59:30Z",
      "summary": "The lead called interested in purchasing...",
      "events": []
    }
  ]
}

Update Lead (PATCH)

This endpoint allows you to enrich the lead by providing pre-existing fields that you may have collected externally (e.g., from your CRM).

Endpoint: /leads/{id}

Method: PATCH

Description: Update information on the lead

Path Parameters:

id (string, required): The unique identifier for the lead you wish to update.

Content-Type: application/json

Body: A JSON object containing the fields you wish to update.

Example Request:

PATCH https://api.spara.co/v1/leads/ABC12345
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json


{
  "first_name": "Jane",
  "last_name": "Doe",
  "num_employees": 53
}

A success response will return 200 without any additional data.

Call Lead (POST)

This endpoint triggers an outbound voice call to an existing lead using your Voice agent.

Endpoint: /leads/{id}/call

Method: POST

Description: Initiates an outbound call to the lead's phone number. The lead must have a phone number on record, and the Voice agent must be published with a phone number configured.

Path Parameters:

id (string, required): The unique identifier for the lead to call.

Content-Type: application/json

Body:

voice_agent_id (string, required): The UUID of the Voice agent that should place the call. The agent must be published and must have a phone number assigned on its Configuration tab — that phone number is used as the caller ID.
call_mode (string, optional): Either "live" (default) for a real call to the lead's phone, or "qa" for a test call. Use "qa" to dry-run the integration without dialing the lead's phone number.

Example Request:

POST https://api.spara.co/v1/leads/ABC12345/call
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "voice_agent_id": "AGENT_UUID"
}

A success response returns 200. The response is returned as soon as the call is queued — the actual call is placed asynchronously. To receive the call result (transcript, summary, recording, outcome), subscribe to the Voice Call Ended event on your webhook endpoint. See Webhooks for the event schema.

Error responses specific to this endpoint:

400 Bad Request: Lead has no phone number, no Voice agent found, or the agent has no phone number configured.
404 Not Found: Lead or specified Voice agent not found in your organization.

Concurrency limit. Outbound calls are subject to a cap of 5 calls per second. A dedicated per-account version of this cap ships by June 2026. For most use cases this is well above your actual call rate. If you anticipate bursty or high-volume dialing (large batch sends, telemarketing-style campaigns), contact your Spara representative ahead of time so we can confirm headroom.

Do not orchestrate the same Voice agent through both this API and a Spara Workflow simultaneously. Pick one system to own the call cadence — splitting workflow logic across both creates coordination overhead and makes call behavior hard to reason about. If your external workflow tool drives the cadence, use this API and disable any equivalent Call Phone step in Spara Workflows.

Rate Limiting

To ensure fair usage and system stability, API requests are subject to rate limits. If you exceed the allocated rate limits, your requests will be temporarily blocked, and you will receive an HTTP 429 Too Many Requests status code.

Responses are limited to a maximum of 1,000 leads per request. In order to get more than 1,000 leads, you will need to make multiple requests.

Outbound calls placed via Call Lead (POST) are subject to a separate concurrency cap of 5 calls per second. A dedicated per-account version of this cap ships by June 2026.

Last updated 6 days ago