# InstaView API - [Welcome to InstaView API](https://docs.instaview.sk/introduction.md): Build AI-run phone and web conversations on the InstaView API - [Quickstart](https://docs.instaview.sk/quickstart.md): Make your first API call to InstaView in under 5 minutes - [Authentication](https://docs.instaview.sk/authentication.md): Learn how to authenticate with the InstaView API using API keys - [API Keys](https://docs.instaview.sk/guides/api-keys.md): Complete guide to managing InstaView API keys - [Scopes and Permissions](https://docs.instaview.sk/guides/scopes-and-permissions.md): Understanding scope-based access control in the InstaView API - [Rate Limiting](https://docs.instaview.sk/guides/rate-limiting.md): Rate limiting for the InstaView API - [Error Handling](https://docs.instaview.sk/guides/error-handling.md): Learn how to handle errors and exceptions in the InstaView API - [Pagination](https://docs.instaview.sk/guides/pagination.md): Learn how to efficiently paginate through large result sets - [Jobs](https://docs.instaview.sk/guides/resources/jobs.md): Manage job postings and position requirements with the Jobs API - [Contacts](https://docs.instaview.sk/guides/resources/contacts.md): Manage the people your agents call, with the Contacts API - [Conversations](https://docs.instaview.sk/guides/resources/conversations.md): Schedule and manage AI-run calls with the Conversations API - [Runs](https://docs.instaview.sk/guides/resources/runs.md): Monitor a batch of AI-run calls with the Runs API - [Agents](https://docs.instaview.sk/guides/resources/agents.md): Configure the agents that run your calls - [Companies](https://docs.instaview.sk/guides/resources/companies.md): Manage company profiles and settings - [Billing & Usage](https://docs.instaview.sk/guides/resources/billing.md): Monitor usage and track call minutes or credits - [Webhooks](https://docs.instaview.sk/guides/resources/webhooks.md): Configure and manage webhook endpoints for real-time event notifications - [Sourcing](https://docs.instaview.sk/guides/resources/sourcing.md): AI-powered asynchronous candidate sourcing and enrichment via the Public API - [ATS Integration](https://docs.instaview.sk/guides/ats-integration.md): Build multi-tenant ATS integrations with InstaView - [Webhooks](https://docs.instaview.sk/guides/webhooks.md): Real-time notifications for events in your InstaView account - [Best Practices](https://docs.instaview.sk/guides/best-practices.md): Production-ready patterns for InstaView API integration - [API Reference](https://docs.instaview.sk/api-reference/introduction.md): Complete API reference for the InstaView API - [List Agents](https://docs.instaview.sk/api-reference/agents/list-agents.md): Lists agents for the API key's company with pagination. - [Design an Agent](https://docs.instaview.sk/api-reference/agents/compose-agent.md): Designs a complete custom agent from a plain-language brief and returns it as a preview, together with a session you can keep refining. **No agent is created.** Nothing appears in your agent list until you post the returned `agent` (or `{ "composerSessionId": … }`) to `POST /agents` — the `201` here… - [Refine a Composed Agent](https://docs.instaview.sk/api-reference/agents/refine-agent.md): Applies one plain-language change to the session's agent — "also ask about relocation", "make it Slovak", "drop the salary question" — and returns the updated preview. Still creates nothing. - [Get a Composer Session](https://docs.instaview.sk/api-reference/agents/get-composer-session.md): The session's current preview and its conversation, newest first. Use it to pick a session back up, or to show someone how the agent was designed. - [Create Agent](https://docs.instaview.sk/api-reference/agents/create-agent.md): Creates a new agent scoped to the API key's company. Send a `flow` (with optional `guardrails` and `contextConfig`) to create a custom agent — its focus is then derived and must not be sent; otherwise pick a template `focus`. - [Get Agent](https://docs.instaview.sk/api-reference/agents/get-agent.md): Returns a single agent, ensuring it belongs to the API key's company. - [Update Agent](https://docs.instaview.sk/api-reference/agents/update-agent.md): Updates an existing agent scoped to the API key's company. Sending a `flow` makes the agent custom; clearing the flow of a custom agent, or changing its focus, is rejected. - [Delete Agent](https://docs.instaview.sk/api-reference/agents/delete-agent.md): Permanently deletes an agent that belongs to the API key's company. This action cannot be undone, and the delete cascades to every conversation the agent ran. - [List Knowledge Documents](https://docs.instaview.sk/api-reference/agents/knowledge/list-knowledge.md): Lists every document attached to the agent's knowledge base, including ones whose upload has not been completed yet (`status: PENDING`). - [Start Knowledge Upload](https://docs.instaview.sk/api-reference/agents/knowledge/start-upload.md): Reserves a document slot on the agent and returns a presigned URL to upload the file to. The file never passes through this API. - [Complete Knowledge Upload](https://docs.instaview.sk/api-reference/agents/knowledge/complete-upload.md): Confirms the file was uploaded to the presigned URL. The stored object is verified — it must exist, be within the size limit, and carry the content type the URL was issued for — and only then does the document become usable on calls. Safe to retry: completing an already-completed document returns it… - [Update Knowledge Document](https://docs.instaview.sk/api-reference/agents/knowledge/update-knowledge.md): Activates or deactivates a document. Deactivating keeps the document but stops it being attached to new calls. Only completed (`READY`) documents can be toggled. - [Delete Knowledge Document](https://docs.instaview.sk/api-reference/agents/knowledge/delete-knowledge.md): Permanently deletes the document, the stored file and the copy held by the voice provider. This cannot be undone. - [List Jobs](https://docs.instaview.sk/api-reference/jobs/list-jobs.md): Lists jobs for the API key's company with pagination. - [Create Job](https://docs.instaview.sk/api-reference/jobs/create-job.md): Creates a new job scoped to the API key's company. - [Create Job from URL](https://docs.instaview.sk/api-reference/jobs/create-job-from-url.md): Scrapes the provided job posting URL and extracts structured data. By default, creates a job entity from the extracted data. Set createJob to false to only extract data without persisting a job. - [Get Job](https://docs.instaview.sk/api-reference/jobs/get-job.md): Returns a single job, ensuring it belongs to the API key's company. - [Update Job](https://docs.instaview.sk/api-reference/jobs/update-job.md): Updates an existing job scoped to the API key's company. - [Delete Job](https://docs.instaview.sk/api-reference/jobs/delete-job.md): Permanently deletes a job that belongs to the API key's company. This action cannot be undone, and the delete cascades: the job's contacts and their conversations are deleted with it, not just the assignments between them. Set status to CLOSED instead to retire a job without losing data. - [List Contacts](https://docs.instaview.sk/api-reference/contacts/list-contacts.md): Lists the contacts that belong to the API key's company, whether or not they hold job assignments. - [Create Contact](https://docs.instaview.sk/api-reference/contacts/create-contact.md): Creates a contact (optionally associated with one or more jobs) in the API key's company. - [Get Contact](https://docs.instaview.sk/api-reference/contacts/get-contact.md): Returns a single contact, ensuring the contact (and any job associations) belong to the API key's company. - [Update Contact](https://docs.instaview.sk/api-reference/contacts/update-contact.md): Updates a contact that belongs to the API key's company. Only basic profile, reachability and status fields are supported. - [Delete Contact](https://docs.instaview.sk/api-reference/contacts/delete-contact.md): Permanently deletes a contact that belongs to the API key's company, whether or not it holds job assignments. The delete cascades: every conversation the contact had, with its transcripts, recordings and analyses, is deleted too. This cannot be undone. - [List Contact Documents](https://docs.instaview.sk/api-reference/contacts/documents/list-documents.md): Lists every document on the contact: the processed CV (`source: CV`), completed uploads, and uploads that have not been completed yet (`status: PENDING`). - [Start Contact Document Upload](https://docs.instaview.sk/api-reference/contacts/documents/start-upload.md): Reserves a document slot on the contact — and the declared bytes against your company's contact-document storage — and returns a presigned URL to upload the file to. The file never passes through this API. - [Complete Contact Document Upload](https://docs.instaview.sk/api-reference/contacts/documents/complete-upload.md): Confirms the file was uploaded to the presigned URL. The stored object is verified — it must exist, be within the size limit, be no larger than the size declared when the upload was started, and carry the content type the URL was issued for — and only then does the document become usable on calls. A… - [Update Contact Document](https://docs.instaview.sk/api-reference/contacts/documents/update-document.md): Renames a document and/or activates or deactivates it. Deactivating keeps the document but stops it being attached to new calls — it is also the way to keep a contact's CV out of calls. Only completed (`READY`) documents can be toggled, and the `CV` document cannot be renamed. At least one of `title… - [Delete Contact Document](https://docs.instaview.sk/api-reference/contacts/documents/delete-document.md): Permanently deletes an uploaded document, the stored file and the copy held by the voice provider. This cannot be undone. - [List Contact Fields](https://docs.instaview.sk/api-reference/contact-fields/list-contact-fields.md): Every field your contacts can carry: the platform's seeded fields merged with your own, which shadow a seeded field of the same key. Read this to learn which keys `fields` accepts on `POST /contacts` and `PATCH /contacts/{id}`, and what each one expects. - [Create Contact Field](https://docs.instaview.sk/api-reference/contact-fields/create-contact-field.md): Creates a field for your company. A key matching a seeded field shadows it for you alone; a key the platform reserves for itself is refused. A company may define at most 50 fields. - [Update Contact Field](https://docs.instaview.sk/api-reference/contact-fields/update-contact-field.md): Changes one of your own fields. Everything is editable except the key, which is fixed once the field exists. Seeded fields cannot be edited at all. - [Delete Contact Field](https://docs.instaview.sk/api-reference/contact-fields/delete-contact-field.md): Removes the definition. The values already stored on your contacts are LEFT IN PLACE and simply stop being returned, so nothing is irreversibly lost — define the key again and they reappear. What the delete does break is any agent flow still using `{{contact.}}`: the token resolves to an empty… - [List Companies](https://docs.instaview.sk/api-reference/companies/list-companies.md): For direct client API keys, returns the single associated company. For ATS keys, returns companies created by this API key. - [Create Company](https://docs.instaview.sk/api-reference/companies/create-company.md): Creates a new company using an ATS API key. Direct client keys cannot create companies via this endpoint. - [Get Company](https://docs.instaview.sk/api-reference/companies/get-company.md): Returns a single company. Direct client keys can only access their own company; ATS keys can only access companies they created. - [Update Company](https://docs.instaview.sk/api-reference/companies/update-company.md): Updates company details. ATS keys can update companies they created; direct client keys can update their own company. - [Delete Company](https://docs.instaview.sk/api-reference/companies/delete-company.md): Permanently deletes a company. This action is irreversible. ATS keys can delete companies they created; direct client keys can delete their own company. - [List Conversations](https://docs.instaview.sk/api-reference/conversations/list-conversations.md): Lists conversations within the API key's company. Every filter is optional: pass `contactId` to narrow the page to one contact (`candidateId` is accepted as its legacy alias), and omit it to list all of them. - [Create Conversation](https://docs.instaview.sk/api-reference/conversations/create-conversation.md): Creates a conversation with a contact, using an existing or inline contact/agent/job, scoped to the API key's company. Respects company billing limits and subscription plans. Set isTest=true to create a test conversation that completes immediately without consuming billing minutes. - [Get Conversation](https://docs.instaview.sk/api-reference/conversations/get-conversation.md): Returns a single conversation, ensuring it belongs to the API key's company. - [Get Conversation Analysis PDF](https://docs.instaview.sk/api-reference/conversations/get-conversation-analysis-pdf.md): Returns the Base64-encoded PDF report of a conversation's analysis. The conversation must have a completed analysis for the PDF to be available. - [Invoke New Call Attempt](https://docs.instaview.sk/api-reference/conversations/invoke-call-attempt.md): Creates a new call attempt on a conversation. Optionally schedules it for a future time. Individual call attempt management is forbidden for ONLINE conversations. - [Reschedule Call Attempt](https://docs.instaview.sk/api-reference/conversations/reschedule-call-attempt.md): Reschedules an existing call attempt to a future time. Only call attempts in SCHEDULED status can be rescheduled. Blocked for ONLINE conversations. - [Delete Call Attempt](https://docs.instaview.sk/api-reference/conversations/delete-call-attempt.md): Cancels and deletes a specific call attempt. Blocked for ONLINE conversations. - [Delete Conversation](https://docs.instaview.sk/api-reference/conversations/delete-conversation.md): Permanently deletes a conversation and all associated data (transcripts, recordings, and analyses). This action is irreversible. A scheduled conversation is removed from the processing queue. For one already in progress, the active call continues to its natural end, but all post-call processing is s… - [Create Run](https://docs.instaview.sk/api-reference/runs/create-run.md): Creates an empty draft run for a custom agent. A draft dials nothing: attach contacts, then launch. Contacts are deliberately not accepted here - a retried create would otherwise leave a second draft holding the same list, and that draft is exactly the thing someone launches later 'to be safe'. - [Get Run](https://docs.instaview.sk/api-reference/runs/get-run.md): Returns one run with its lifecycle status and aggregate progress, ensuring it belongs to the API key's company. A run batches conversations rather than replacing them: it mints one conversation per contact, and `progress` counts those. For the per-contact detail behind the aggregate, use `GET /runs/… - [List Run Conversations](https://docs.instaview.sk/api-reference/runs/list-run-conversations.md): Pages through the conversations a run has produced — one per contact it has dispatched, in the same shape `GET /conversations` returns. A run that has not been launched has none yet. Requires `read:runs` and `read:conversations`. - [Attach Contacts](https://docs.instaview.sk/api-reference/runs/attach-run-contacts.md): Attaches existing contacts to a run. Idempotent - an id already on the run is skipped, so a repeated or overlapping batch attaches nothing twice. Allowed in every status except CANCELLED. On an already-launched run the new contacts are dispatched immediately and a COMPLETED run reopens to RUNNING; o… - [Detach Contact](https://docs.instaview.sk/api-reference/runs/detach-run-contact.md): Removes a contact from a run that has not launched. Draft only: after launch the contact's conversation exists and may already have been called, so removing the link would be a half-truth. Cancel the run instead. - [Launch Run](https://docs.instaview.sk/api-reference/runs/launch-run.md): Fans the draft out into one conversation per contact and moves it DRAFT to RUNNING. Queued, not dialled: a 2xx means the conversations are on the dispatch queue, and each contact's outcome arrives as a conversation.* webhook rather than in this response. All-or-nothing - the whole batch is admitted… - [Pause Run](https://docs.instaview.sk/api-reference/runs/pause-run.md): Stops the run dialling. Calls already queued are withdrawn, and anything the dispatcher had already picked up is refused before it is placed. The work is held rather than discarded: resume puts back exactly what pause held, and a contact already reached is not called again. - [Resume Run](https://docs.instaview.sk/api-reference/runs/resume-run.md): Puts the run's held calls back on the dispatch queue and returns it to RUNNING. - [Cancel Run](https://docs.instaview.sk/api-reference/runs/cancel-run.md): Stops the run for good and closes out its un-dialled conversations. Terminal - there is no resume. A call already connected is left to finish; its retry is refused rather than rescheduled. - [Delete Run](https://docs.instaview.sk/api-reference/runs/delete-run.md): Soft-deletes a run that is no longer active. Allowed from DRAFT, COMPLETED and CANCELLED; SCHEDULED, RUNNING and PAUSED return 422 - cancel it first, because a delete must not silently terminate live phone calls. The conversations the run produced survive as separate resources, still readable with t… - [Get Usage Statistics](https://docs.instaview.sk/api-reference/billing/get-usage.md): For direct client keys, returns usage for the associated company. For ATS keys, returns aggregated usage across ATS-managed companies. Test conversations (created with isTest=true) are excluded from billing and usage summaries. - [Generate Audio](https://docs.instaview.sk/api-reference/voice/generate-audio.md): Converts text to speech using AI-powered voices. Returns an audio stream in MP3 format. - [List Webhooks](https://docs.instaview.sk/api-reference/webhooks/list-webhooks.md) - [Create Webhook](https://docs.instaview.sk/api-reference/webhooks/create-webhook.md) - [Get Webhook](https://docs.instaview.sk/api-reference/webhooks/get-webhook.md) - [Update Webhook](https://docs.instaview.sk/api-reference/webhooks/update-webhook.md) - [Delete Webhook](https://docs.instaview.sk/api-reference/webhooks/delete-webhook.md) - [Test Webhook](https://docs.instaview.sk/api-reference/webhooks/test-webhook.md) - [Reset Circuit Breaker](https://docs.instaview.sk/api-reference/webhooks/reset-circuit.md) - [Initiate Sourcing Run](https://docs.instaview.sk/api-reference/sourcing/initiate-sourcing.md): Starts an asynchronous AI-powered candidate sourcing pipeline. Returns immediately with a requestId and status 'processing'. Results are delivered via webhook or by polling GET /sourcing/{id}/results. - [Initiate Sourcing Preview Run](https://docs.instaview.sk/api-reference/sourcing/initiate-sourcing-preview.md): Starts an asynchronous candidate sourcing preview run. Returns immediately with a requestId and status 'processing'. Results are delivered via webhook (SOURCING_COMPLETED / SOURCING_FAILED) or by polling GET /sourcing/preview/{id}/results. - [Get Sourcing Preview Results](https://docs.instaview.sk/api-reference/sourcing/get-sourcing-preview-results.md): Returns the current state of a candidate sourcing preview run. Responds with 202 and status 'processing' while in progress, or 200 with the full candidate list (or error details) when completed. - [Patch Sourcing Run](https://docs.instaview.sk/api-reference/sourcing/patch-sourcing.md): Patches the reasoning context and/or candidate limit of an existing sourcing session and triggers a new background run. Returns 409 if a run is already in progress. At least one of query or limit must be provided. - [Get Sourcing Results](https://docs.instaview.sk/api-reference/sourcing/get-sourcing-results.md): Returns the current state of a sourcing run. Responds with 202 and status 'processing' while in progress, or 200 with the full ranked candidate list (or error details) when completed. - [Initiate Enrichment Run](https://docs.instaview.sk/api-reference/sourcing/initiate-enrichment.md): Submits a batch of candidate profile IDs for deep background enrichment. Returns immediately with a requestId and status 'processing'. Results are delivered via webhook (ENRICH_COMPLETED / ENRICH_FAILED) or polled at GET /sourcing/enrich/{id}/results. Consumes 1 credit per successfully enriched prof… - [Get Enrichment Results](https://docs.instaview.sk/api-reference/sourcing/get-enrich-results.md): Returns the current state of an enrichment run. Responds with 202 and status 'processing' while the run is in progress, or 200 with full per-profile results when it has completed. - [Render HTML Candidate Cards](https://docs.instaview.sk/api-reference/sourcing/render-html.md): Generates self-contained HTML/CSS candidate profile cards for up to 10 profile IDs. Synchronous — returns immediately with rendered card snippets. Supports 'dark' (default) and 'light' themes. - [List Phone Numbers](https://docs.instaview.sk/api-reference/phone-numbers/list-phone-numbers.md): Lists active phone numbers assigned to the API key's company. Use the returned `id` when referencing a phone number in an agent configuration. ATS keys must supply the `companyId` query parameter. - [Changelog](https://docs.instaview.sk/changelog/introduction.md): Track all changes, updates, and improvements to the InstaView API - [September 2026](https://docs.instaview.sk/changelog/2026-09.md): Changelog entries for September 2026 - [August 2026](https://docs.instaview.sk/changelog/2026-08.md): Changelog entries for August 2026 - [July 2026](https://docs.instaview.sk/changelog/2026-07.md): Changelog entries for July 2026 - [June 2026](https://docs.instaview.sk/changelog/2026-06.md): Changelog entries for June 2026 - [May 2026](https://docs.instaview.sk/changelog/2026-05.md): Changelog entries for May 2026 - [April 2026](https://docs.instaview.sk/changelog/2026-04.md): Changelog entries for April 2026 - [March 2026](https://docs.instaview.sk/changelog/2026-03.md): Changelog entries for March 2026 - [February 2026](https://docs.instaview.sk/changelog/2026-02.md): Changelog entries for February 2026 - [January 2026](https://docs.instaview.sk/changelog/2026-01.md): Changelog entries for January 2026 - [December 2025](https://docs.instaview.sk/changelog/2025-12.md): Changelog entries for December 2025 - [November 2025](https://docs.instaview.sk/changelog/2025-11.md): Changelog entries for November 2025 ## OpenAPI Specs - [openapi](/api-reference/openapi.json)