# verbit Documentation > Documentation for verbit ## Guides - [Getting Started with Verbit](https://verbit.readme.io/docs/getting-started.md) - [Insights API (Gen V)](https://verbit.readme.io/docs/insights-gen-ai.md) - [Live Booking API](https://verbit.readme.io/docs/live-booking-api.md): Verbit allows you to have live transcription and translation during your events. - [Book with WebSocket](https://verbit.readme.io/docs/book-with-websocket.md) - [Book with RTMP](https://verbit.readme.io/docs/book-with-rtmp.md) - [Book with Zoom](https://verbit.readme.io/docs/book-with-zoom.md) - [Book with MS Teams](https://verbit.readme.io/docs/book-with-teams.md) - [Book with live translation](https://verbit.readme.io/docs/book-with-live-translation.md): You can also book live translation for your order! - [Book with Embedded Captions](https://verbit.readme.io/docs/book-with-embedded-captions.md) - [Live Sessions](https://verbit.readme.io/docs/live-api.md): Verbit allows you to have live transcription and translation during your events. - [Orders Overview](https://verbit.readme.io/docs/order-object.md): Important info to know about orders through the API - [Create an order (explained)](https://verbit.readme.io/docs/create-an-order-explained.md) - [What am I allowed to book](https://verbit.readme.io/docs/what-am-i-allowed-to-book.md) - [Streaming Media](https://verbit.readme.io/docs/streaming.md) - [WebSocket - Connection](https://verbit.readme.io/docs/websocket-protocol.md) - [WebSocket - Responses](https://verbit.readme.io/docs/websocket-responses.md) - [Post-Production API](https://verbit.readme.io/docs/post-production-api.md) - [Recipes](https://verbit.readme.io/docs/recipes.md) - [Errors Explanation](https://verbit.readme.io/docs/errors-explanation.md) - [Verbit Transcript JSON format](https://verbit.readme.io/docs/verbit-transcript-json-format.md) - [Caption Control API](https://verbit.readme.io/docs/caption-control-api.md) - [Get Session](https://verbit.readme.io/docs/get-session.md) - [Set Upstream](https://verbit.readme.io/docs/set-upstream.md): Block or pass real-time captions generated by Verbit's AI. - [Set Caption Placement](https://verbit.readme.io/docs/set-caption-placement.md): Specify the screen position of captions to customize their appearance. - [Extend Session Duration](https://verbit.readme.io/docs/extend-session-duration.md): Extend the duration of an existing session. - [Get Max Extend Time](https://verbit.readme.io/docs/get-max-extend-time.md): Returns the maximum extend time for the session. - [End Session](https://verbit.readme.io/docs/end-session.md): Immediately end a session. - [Change Connection Plan](https://verbit.readme.io/docs/change-connection-plan.md): Change the connection plan for a specific session. - [Authentication](https://verbit.readme.io/docs/authentication.md) - [Get an API Token](https://verbit.readme.io/docs/api-token.md) ## API Reference - [Get Insights](https://verbit.readme.io/reference/get_insights_api_v2_insights_get.md): The Verbit Insights API provides access to insights generated by the Verbit AI engine. It supports insights for both live sessions and post-production jobs. [Learn more about the Insights API guide here](https://verbit.readme.io/docs/insights-gen-ai). - [Generate Now](https://verbit.readme.io/reference/generate_now_api_v2_insights_generate_post.md): Generate insights for a job. The insights are generated based on the insights configuration of the job. [Learn more about the Insights API guide here](https://verbit.readme.io/docs/insights-gen-ai). - [List orders](https://verbit.readme.io/reference/ordersrouterget_orders.md): ***Retrieves a list of orders in the Verbit system, filtered by various criteria*** You can filter my many different fields, including the order id, the recurrence id, free text and more! - [Create Order](https://verbit.readme.io/reference/ordersroutercreate_order.md): ***Book a new live order in the Verbit system***. **Important Notes:** * The order schedule (start time) must be set for a **future** date and time. * Once an order is created, the status of the order is automatically set to: **created**. * **Validation Rules:** * **Start Time:** Must be at least one minute in the future. * **Contact Details:** Either a name or a contact method (phone or email) is required. **Delivery Selection:** The delivery is where you want to get your transcript sent to. We could send it using websocket, deliver directly to zoom for zoom ordders, and more. If you don't choose a delivery yourself we would choose for you depending on your input type (media source). * See the delivery types in the *output* section for more details. - [Update Orders Bulk](https://verbit.readme.io/reference/ordersrouterupdate_orders_bulk.md): ***Updates details of multiple existing orders simultaneously.*** **Important Notes:** * **Update Restrictions:** Order update deadlines vary based on service tier: * Captivate/Captivate basic: At least 5 hours before the event start. * Human tier orders: At least 24 hours before the event start. * **Status Updates:** The status of an order can only be updated to **canceled**. * **Glossary Updates:** The input glossary can be modified at any time. * **Change Notifications:** Update will trigger a notification to event contact person(s). * **Late Updates and Cancellations:** * Orders may be updated at later stages, based on the contract with the client. * Canceled events may still incur charges. - [Get Order](https://verbit.readme.io/reference/ordersrouterget_order.md): ***Retrieves a single order based on a specified **order id** parameter.*** - [Update Order](https://verbit.readme.io/reference/ordersrouterupdate_order.md): ***Updates details of an existing order based on a specified **order id** parameter.*** **Important Notes:** * **Update Restrictions:** Order update deadlines vary based on service tier: * Captivate/Captivate basic: At least 5 hours before the event start. * Human: At least 24 hours before the event start. * **Status Updates:** The status of an order can only be updated to **canceled**. * **Glossary Updates:** The input glossary can be modified at any time. * **Change Notifications:** Update will trigger a notification to event contact person(s). * **Late Updates and Cancelations:** * Orders may be updated at later stages, based on the contract with the client. * Canceled events may still incur charges. - [Get Order Transcript](https://verbit.readme.io/reference/ordersrouterget_order_transcript.md): ***Returns a link to order's transcript based on a specified **order id** parameter.*** - [Cancel Order](https://verbit.readme.io/reference/ordersrouterupdate_order_status.md): ***Updates the status of an existing order. Currently, only supports cancelation.*** **Important Notes:** * **Cancelation Restrictions:** Orders can only be canceled while in the following statuses: * created * pending_approval * pending_execution * ready_to_connect * execution_error * **Important:** Attempting to cancel an order in any other status will have no effect. The order status will remain unchanged. * **Cancelation Deadlines:** Order status update deadlines vary based on service tier: * Captivate/Captivate basic: At least 5 hours before the event start. * Human: At least 24 hours before the event start. * **Late Cancelations:** * Orders may be canceled at later stages, based on the contract with the client. * The order may still be charged, depending on the contract with the customer. - [Update Recurrence Order](https://verbit.readme.io/reference/ordersrouterupdate_recurrence_orders.md): ***Updates details of a single or multiple orders belonging to a recurring event series.*** **Required Roles: (one of the following)** * customer_admin * customer_content_manager **The following details filters can be applied to the request:** * **Recurrence id (recurrence_id):** The ID of the specific recurrence event to update. * **Order id (order_id):** The ID of the order from which all future orders will be updated. This field is required when the recurrence param is `future`. * **Recurrence (recurrence):** Optional parameter to control if the update should be applied to: * future (default): Current and all future occurrences in the series. Order ID is required with this option. * unfinished: Only orders in updatable statuses (created, pending_approval, pending_execution, execution_error, ready_to_connect, declined, returned). - [Cancel Orders By Recurrence](https://verbit.readme.io/reference/ordersrouterupdate_recurrence_order_statuses.md): ***Updates the status of an existing order belonging to a recurring event series. Currently, only supports cancelation.*** **Required Roles: (one of the following)** * customer_admin * customer_content_manager **Important Notes:** * **Cancelation Restrictions:** Orders can only be canceled while in the following statuses: * created * pending_approval * pending_execution * ready_to_connect * execution_error * **Important:** Attempting to cancel an order in any other status will have no effect, and the order status will remain unchanged. * **Cancelation Deadlines:** Order status update deadlines vary based on service tier: * Automatic/ASR Only: At least 5 hours before the event start. * Pro & Elite: At least 24 hours before the event start. * **Late Cancelations:** * Orders may be canceled at a later stage before the event, but **the event will still be charged for**. * Orders may be canceled at later stages, potentially within an hourly timeframe based on the contract with the client. - [Create Download](https://verbit.readme.io/reference/deliveriesroutercreate_delivery.md): ***Prepare the captioning/transcription of the order to be downloaded.*** **Required Roles: (one of the following)** * customer_admin * customer_content_manager **The following details can be specified in the request body:** 1. **Order IDs (order_ids)** - List of order IDs for which the download request is created. 2. **File Format (formats)** - List of file types to include in the requested download. **Supported formats:** *(vtt, srt, sami, scc, dfxp, pdf, docx, rtf, txt, mdb, json, oip)* 3. **Languages (languages)** - (Optional) - List of languages for the downloaded captioning/transcription files. **Important Notes:** * Once the download request is created, the status of the request is automatically set to: **pending**. - [Get Download](https://verbit.readme.io/reference/deliveriesrouterget_delivery.md): ***Retrieve information for a single requested download based on a specified download id parameter.*** **Required Roles: (one of the following)** * customer_admin * customer_content_manager * CART participant - [Get Download Status](https://verbit.readme.io/reference/deliveriesrouterget_delivery_status.md): ***Retrieve the status of a download request based on a specified download id parameter received from calling `POST /` .*** **Required Roles: (one of the following)** * customer_admin * customer_content_manager * CART participant - [Get pre-signed post url for attachments upload](https://verbit.readme.io/reference/presignedurlrouterget_post_presigned_url_for_attachments.md): ***Get pre-signed post url for attachments upload.*** **Required Roles: (one of the following)** * customer_admin * customer_content_manager * CART participant - [Get job list](https://verbit.readme.io/reference/get_jobs.md): Retrieve list of created jobs. - [Create new job](https://verbit.readme.io/reference/post_job-new.md): Creates a new transcription job on Verbit's server. ## Basic Usage 1. Create job with this endpoint 2. Upload media via `POST /job/add_media` 3. Start processing via `POST /job/perform_transcription` ## Key Parameters - `job_name`: Human-readable identifier (typically filename) - `external_id`: Your reference ID (e.g., database ID) - `profile`: Processing configuration to use (required) ## Translation Support If translation is enabled in the profile: 1. Specify target languages in `translation_languages` 2. Configure translation settings: - Use `translation_profile` to select language profile - Default profile used if not specified - Set `translation_processing_mode` for rush/standard processing ## Important Notes - While `GET` is supported for backwards compatibility, always use `POST` with JSON body - At least one profile must be specified - Translation features require profile support - [Add asset](https://verbit.readme.io/reference/post_job-add-asset.md): Generates a pre-signed URL for uploading media or attachment content. Used for local file uploads. ## Upload Process 1. Call this endpoint with either: - `file_name` for local file upload - `asset_url` for remote file reference 2. Receive `asset_id` and optional `upload_url` 3. If `upload_url` provided, `PUT` your content to that URL 4. Use the `asset_id` with one of: - `POST /job/add_media` for media files - `POST /job/add_backup_record` for backup recordings - `POST /job/add_notes_attachments` for supporting documents ## Important Timing Notes - Upload URL expires in **24 hours** - Must use asset within 24 hours of upload - Unused uploaded files are automatically deleted ## Requirements - Must provide either `file_name` or `asset_url` - Cannot provide both parameters - URLs must be GET-accessible - Avoid one-time or short-lived URLs - [Add media](https://verbit.readme.io/reference/post_job-add-media.md): Adds media file(s) to a new job. This endpoint can only be called once per job. ## Usage Options 1. **Direct URL**: - Provide `media_url` for online-accessible files - URL must be GET-accessible - Avoid one-time/short-lived URLs 2. **Local File Upload**: - First use `POST /job/add_asset` to get upload URL - Then reference via `asset_ids` parameter 3. **File Merging** (available for certain profiles, ask support for access): - Upload multiple files via `POST /job/add_asset` - Pass all `asset_ids` in order of desired merging - Set `merge_assets: true` ## Next Steps After adding media, call `POST /job/perform_transcription` to start processing ## Important Notes - Can only be called once per job - URLs must be directly accessible - For merging, minimum 2 asset_ids required - Merging order follows asset_ids order - [Add backup record](https://verbit.readme.io/reference/post_job-add-backup-record.md): Add secondary audio/video sources to ensure transcription quality. ## Use Cases - Multiple recording devices used - Different audio capture methods - Backup recordings for critical content - Alternative angles/sources ## Upload Process 1. Upload backup file via `POST /job/add_asset` 2. Pass received `asset_id` to this endpoint 3. Repeat for additional backup sources if needed ## Prerequisites - Job must be in "Pending" status - Asset must be a valid media file - Original media must be added first ## Important Notes - Add all backups before starting transcription - Cannot add backups to in-progress jobs - Helps transcribers verify unclear sections - Available for certain profiles only, check with support - [Add attachment notes](https://verbit.readme.io/reference/post_job-add-notes-attachments.md): Attach reference materials to help transcribers understand context and terminology. ## Use Cases - Meeting agendas - Technical glossaries - Related documents - Presentation slides - Speaker biographies ## Upload Methods Choose one of: 1. **Direct URL**: - Provide `notes_attachment_url` - URL must be publicly accessible - Avoid expiring/one-time URLs 2. **Local File Upload**: - First use `POST /job/add_asset` - Then provide `asset_ids` array - Can upload multiple files ## Important Notes - Must use exactly one upload method - Cannot mix URL and asset_id methods - Add before starting transcription - Helps ensure accurate terminology - [Add transcription](https://verbit.readme.io/reference/post_job-add-transcription.md): Upload an existing transcription for professional editing, caption formatting, translation, etc ## Prerequisites - Job must be created but not started - Job profile must allow custom transcription uploads - Transcription must be in plain text or SRT format ## Upload Methods Choose one of: 1. **Direct Text**: - Use `transcription_text` parameter - Provide complete transcription text 2. **URL Reference**: - Use `transcription_url` parameter - URL must be publicly GET-accessible - Must return plain text or SRT content and correct Content-Type HTTP header ## Important Notes - Available for jobs with certain profiles only - Cannot use both upload methods simultaneously - Supports both plain text and SRT formats - [Start processing](https://verbit.readme.io/reference/post_job-perform-transcription.md): Initiates the transcription process for a job. Processing steps are determined by the job's profile and may include: - ASR (Automatic Speech Recognition) - Professional human editing - Speaker name assignment - Closed caption formatting ## Prerequisites - At least one media file must be uploaded (`POST /job/add_media`) - Job must be in "Pending" status - Required metadata must be set ## Monitoring Progress Two options for tracking job status: 1. **Polling**: - Periodically call `GET /job/info` - Check `job_status` field - Download results when status is "Completed" 2. **Webhook**: - Configure webhook URL in profile or per-job - Receive automatic notification on completion - See Webhook section for setup details ## Sandbox Testing In sandbox mode: - No real processing occurs - Job stays "In Progress" by default - Use `finish_in` parameter to simulate completion - Use `finish_with_error` to simulate failures - [Get job information](https://verbit.readme.io/reference/get_job-info.md): Returns comprehensive information about a job including its current status, metadata, and processing details. ## Response Content - Basic job information (ID, name, profile) - Current processing status - Certification details (if applicable) - Error information (if any) ## Job Status Values | Status | Description | Next Steps | |--------|-------------|------------| | `Pending` | Job created but not started | Add media and other files and call `POST /job/perform_transcription` | | `In Progress` | Currently being processed | Continue polling this endpoint | | `Completed` | Processing finished successfully | Use `GET /job/get_caption` to download | | `Canceled` | Processing was canceled | Create new job if needed | | `Failure` | Processing failed | Check `errors` field for details | ## Important Notes - Poll this endpoint to monitor job progress - Certified transcriber details include signature (valid for 12 hours) - For failed jobs, check the `errors` array for failure details - [Download draft transcription](https://verbit.readme.io/reference/get_job-draft.md): Download the latest available transcription before job completion. ## Use Cases - Access to machine-generated captions while waiting for professional review - Early content preview ## Availability Check 1. **Polling**: - Check `draft_ready` field in `/job/info` response - `true` indicates draft is available - `false` means no draft yet - Updates throughout processing 2. **Webhook**: - Receive a webhook notification with `draft_ready: true` ## Output Options - Same formats as `/job/get_caption` - All language options supported - Timecode features available - Multiple file formats ## Important Notes - Content may be incomplete - Subject to further editing - Not final transcription - Updates periodically - [Download transcription](https://verbit.readme.io/reference/get_job-get-caption.md): Download the completed transcription/caption file in your preferred format. ## Prerequisites - Job must be completed (`GET /job/info` status = "Completed") - Valid caption format must be specified - Language code must be valid if requesting translation ## Output Format Options Specify format using `caption_format` parameter: ### Common Caption/Subtitle Formats - `vtt`, `web_vtt`: WebVTT captions for HTML5 video - `srt`: SubRip subtitle format - `sami`: Windows Media Player captions - `scc`: Scenarist Closed Captions - `dfxp`: DFXP Timed Text with begin/end tags ### Document/Text Formats - `txt`: Plain text transcript - `docx`: Microsoft Word document - `rtf`: Rich Text Format document - `pdf`: PDF document - `json`: Verbit Transcript JSON format ### Audio Description Formats - `ad.vtt`: Audio Description WebVTT - `ad.html`: Audio Description HTML - `ad.txt`: Audio Description text - `sm.txt`: Speaker Marked text - `ad.mp3`: Audio Description MP3 ### Media/Video Formats (for closed captions, dubbing, etc) - `mov`: QuickTime video with captions - `mp4`: MP4 video with embedded captions - `mxf`: Material Exchange Format - `mpg`: MPEG video format ### Other Formats - `oip`: Offline Interactive Player archive ## Language Support - Default: Original job language - Translations: Use `language` parameter with RFC 5646 code - Example codes: `en-US`, `fr-FR`, `de-DE` - Must be previously requested via `translation_languages` ## Important Notes - Returns file content, not JSON - Follow HTTP redirects for media formats, like closed captions MP4 - Timecode options available for text formats - [Get job keywords](https://verbit.readme.io/reference/get_job-get-keywords.md): Get the most frequently used words from a transcription job. ## Response Details - Returns top 35 words - Sorted by frequency of use - Excludes common stop words - Case-insensitive matching - Includes compound terms ## Use Cases - Content summarization - Topic identification - SEO optimization - Analytics and reporting - Content categorization ## Important Notes - Only available for completed jobs - Updates with each revision - Reflects final transcription - Useful for content indexing - Only available for certain profiles, check with support - [Embeddable widget code](https://verbit.readme.io/reference/get_job-get-widget-code.md): Get embeddable HTML code for Verbit's interactive transcript widget. ## Features - Synchronized text highlighting with media playback - Full-text search capabilities - Click-to-seek navigation - Responsive design - Customizable appearance (through JS and CSS tweaks) ## Integration Options 1. **Use Existing Player**: - Provide your player's (video/audio element) HTML ID - Widget syncs with your player - Maintains your player's styling 2. **Built-in Player**: - Provide media URL - Widget includes its own player (basic HTML5 video/audio element) - Consistent playback experience ## Important Notes - Must choose exactly one integration option - Player ID and media URL are mutually exclusive - Original media available via `original` URL value - Widget title defaults to job name - [Offline widget](https://verbit.readme.io/reference/get_job-get-offline-widget.md): Download a self-contained version of Verbit's interactive transcript widget. ## Features - Works without internet connection - Includes all required assets - Same functionality as online widget - Downloadable as ZIP archive ## Package Contents - HTML widget code - Required JavaScript files - CSS stylesheets - Media player (default HTML5 element) - Transcription data ## Important Notes - Download URL expires in **24 hours** - Extract all files to same directory - Maintain file structure when deploying - Test offline functionality before distributing - Some media files may not work locally depending on browser, installed codecs, etc. - [Request review](https://verbit.readme.io/reference/post_job-request-review.md): Request a professional review of a completed transcription job. ## Prerequisites - Job must be in "Completed" status - Cannot request review for jobs in other states - Original transcription must be preserved ## Review Process 1. Submit review request with optional comment 2. Verbit's team reviews the transcription 3. Makes necessary improvements if needed 4. Updates job with reviewed content ## Usage Notes - Use comments to highlight specific concerns - Provide clear instructions for reviewers - Original job remains accessible during review - [Request direct upload URL](https://verbit.readme.io/reference/post_job-request-upload-url.md): **Deprecated since v4. Use `POST /job/add_asset` instead.** Generates special expirable URL for direct media content upload. Use this endpoint when you need to upload local files. Otherwise (for media available online) consider using `/job/add_media`. After calling this endpoint you should PUT your content to URL returned, and then call `POST /job/perform_transcription` for processing to start. URL will expire in 24 hours. - [Create Smart Player for job](https://verbit.readme.io/reference/post_job-smart-player.md): Generate an accessible video player with interactive transcripts and captions. ## Features - Interactive transcript navigation - Synchronized captions - Audio description support - Keyboard accessibility - Screen reader compatibility ## Configuration Options - Custom video source - Player title and description - Thumbnail image - Credits information - Custom favicon ## Important Notes - Job must be completed - Media URL must be accessible - Title is required - All URLs must be public - [Get job Smart Player](https://verbit.readme.io/reference/get_job-smart-player.md): Retrieve the URL and configuration for an existing Smart Player instance. ## Response Content - Smart Player access URL - Video source configuration - Player metadata - Visual customization settings ## Use Cases - Embed player in web pages - Share accessible content - Check player settings before update ## Important Notes - Job must be completed - Smart Player must exist - URLs must be accessible - Configuration is read-only - [Update Smart Player for job](https://verbit.readme.io/reference/put_job-smart-player.md): Modify an existing Smart Player's configuration and appearance. ## Configurable Elements - Video source URL - Player title/description - Favicon - Thumbnail image - Player credits ## Update Process 1. Provide new configuration 2. Validate media accessibility 3. Apply changes immediately 4. Return updated player URL ## Important Notes - Job must be completed - All URLs must be accessible - Title remains required - Previous config preserved if unchanged - [List profiles](https://verbit.readme.io/reference/get_profiles.md): Returns a list of all available transcription/captioning profiles for your organization. ## Profile Overview - Each profile defines specific processing settings - Determines turnaround time and service level - Controls features like speaker identification - Affects pricing and delivery timeline ## Response Details - `name`: Unique descriptive profile name used in job creation - `turnaround`: Expected completion time in hours ## Usage 1. List profiles to see available options 2. Use profile name in `POST /job/new` requests 3. Match profile to content requirements - [List](https://verbit.readme.io/reference/get_users.md): Returns a list of all users in your organization along with their roles and permissions. ## Response Details - `id`: Unique identifier for the user - `email`: User's email address - `roles`: Array of assigned roles determining user permissions ## Basic Roles - `admin`: Full administrative access - `editor`: Content editing privileges - [Get by ID](https://verbit.readme.io/reference/get_users-id.md): Retrieve detailed information about a specific user by their ID. ## Response Format Returns the same user object format as the list endpoint: - User ID - Email address - Assigned roles - [Find user by email](https://verbit.readme.io/reference/get_users-find.md): Find a specific user in your organization using their email address. ## Search Behavior - Case-sensitive email matching - Must provide complete email address - [Get Session Info](https://verbit.readme.io/reference/get_session_details_api_v1_session__order_id__get.md): ***Retrieve the full details of a specific session.*** This includes information such as the session ID, name, status, customer details, user details, scheduling information, the current state of the session and more. - [Set upstream state](https://verbit.readme.io/reference/upstream_api_v1_session__order_id__upstream_post.md): ***Controls the upstream state for a specific session.*** **Functionality:** The upstream state determines whether captions are being sent or blocked: * **Blocked:** The upstream is blocked so Verbit captions are allowed and actively being sent. * **Passed:** The upstream is passed so Verbit captions are blocked and not sent. - [Set caption placement](https://verbit.readme.io/reference/set_placement_api_v1_session__order_id__caption_placement_post.md): ***Sets the caption placement for the session*** - [End session](https://verbit.readme.io/reference/end_api_v1_session__order_id__end_post.md): ***Ends the session*** - [Get max extend time](https://verbit.readme.io/reference/max_extend_api_v1_session__order_id__extend_get.md): ***Returns the maximum extend time for the session*** - [Extend session](https://verbit.readme.io/reference/extend_api_v1_session__order_id__extend_post.md): ***Extends the session to the requested end time*** - [Change connection plan template](https://verbit.readme.io/reference/change_cpt_api_v1_session__order_id__connection_plan_post.md): ***Changes the connection plan template for the session*** ## Changelog - [Welcome to verbit](https://verbit.readme.io/changelog/welcome-to-verbit.md)