Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

For how leads relate to accounts, owners, and deals, see Spara Objects & Fields.

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:

Account & owner objects

A lead may also carry the company it belongs to and the rep who owns it. Both are returned as nested objects on the lead, and both are accepted on POST /leads and PATCH /leads/{id}:

The lead's owner is the rep assigned to that person; account.owner is the rep assigned to the company. They are often the same record.

  • crm_source accepts SALESFORCE, HUBSPOT, or MARKETO, and must be sent together with crm_id or the request fails with 422. Sending both lets Spara match an existing account or owner rather than creating a duplicate.

  • Any other key inside account or owner is treated as a custom field for that object and must already be defined in your Data Model, or the request fails with 422.

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 limits described in Rate Limiting.

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): Filter by lead created_at >= start — a static window over when the lead was first created.

  • end (epoch timestamp integer, optional): Filter by lead created_at <= end — same static window as start.

  • last_activity_from (epoch timestamp integer, optional): Filter by lead last_activity_at >= last_activity_from — a rolling window over the lead's most recent activity. A lead created months ago that engaged today will match a "today" filter; a lead with no activity since its creation will not.

  • last_activity_to (epoch timestamp integer, optional): Filter by lead last_activity_at <= last_activity_to — same rolling semantics as last_activity_from.

  • start_after_id (string, optional): Pagination cursor. The id of the last lead from the previous page; results begin after it.

All four time-based parameters accept Unix epoch seconds and are inclusive (>= / <=).

Pagination: Results are returned in pages of up to 1000 leads, ordered oldest-first. The response includes has_more (whether another page exists) and last_id (the id of the last lead in the page, or null if empty). To fetch the next page, repeat the request with start_after_id set to last_id, and keep going until has_more is false. All other query parameters must stay the same across pages.

Example Request & Success Response:

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:

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:

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:

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 you specify the phone number to call from — that number acts as the caller ID and determines which Voice agent places the call. Spara resolves the published Voice agent assigned to that phone number automatically.

Path Parameters:

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

Content-Type: application/json

Body:

  • from_number (string, required): The phone number to place the call from, in E.164 format (e.g. "+14155550123"). This number must be one you've configured in Spara, and it must have a published Voice agent assigned to it. Spara uses it as the caller ID and routes the call through that agent.

  • 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:

A success response returns 200. The response body includes the voice_agent_id Spara resolved from from_number, along with the call_id and initial status. 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: The lead has no phone number set, the lead's or the from_number value can't be parsed, or the from_number has no published Voice agent assigned.

  • 404 Not Found: The lead was not found, or the from_number is not a phone number configured in your account.

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.

Requests are limited to 10 per API key per minute. If you need higher throughput, spread work across multiple API keys or move to Webhooks for a continuous stream instead of polling. See https://docs.spara.com/guides/webhook-web-api-or-workflow-api-step.

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