# Web API 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"`. {% hint style="danger" %} 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. {% endhint %} ### 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](#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) * `end` (epoch timestamp integer, optional) Note: `start` and `end` are inclusive (i.e `>=` and `<=)` within a 1 second resolution. Example Request & Success Response: ```json GET https://api.spara.co/v1/leads/search?email=jane.doe@test.com&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": "jane.doe@test.com", "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: ```json 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": "jane.doe@test.com", "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: ```json 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": "jane.doe@test.com", "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: ```json 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: ```json 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](/developers/spara-api/webhooks.md) 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. {% hint style="info" %} **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. {% endhint %} {% hint style="warning" %} 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](https://docs.spara.com/agents/workflows/call-phone) step in Spara Workflows. {% endhint %} ### 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](#call-lead-post "mention") are subject to a separate concurrency cap of **5 calls per second**. A dedicated per-account version of this cap ships by June 2026. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.spara.com/developers/spara-api/web-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.