📘
All Verbit APIs use OAuth2.0 authentication. This will require a bearer token to be generated and passed through the Authorization header. Refer to the documentation for details on how to get an API token.

Orders API Overview

The Verbit Orders API allows the user to provide captioning, translations and transcription for their live sessions, which can be booked in advance.

Here are some of the major features provided by the Orders API:

Can connect to a variety of data inputs (Encoders, Web URLs, Dial-In, etc.)
Translation services
Transcription in both English and popular Non-English languages (Spanish, French, Chinese, Arabic, and Hebrew)
Speaker sensitivity
Profanity filter
Allow Pick a specific ASR Domain Model
Establish reoccurring booking events like classes or a webinar series.

Learn more about the Booking API data here in the API Reference.

Creating An Order

Creating an order allows a user to schedule a live session with any of the Verbit services (captions, transcription, translations) that are required for the event. This order can from an array of sources, everything from a Zoom meeting to decoder device.

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.

In the POST below is a detail of all the properties:


curl --request POST \
     --url https://orders.verbit.co/api/v2/orders \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <BEARER-TOKEN>' \
     --header 'content-type: application/json' \
     --data '{
    "name": "Example Microsoft Teams Session",
    "client_transaction_id": "81190fa2-93c3-4e67-867a-7668cd8eac51",
    "input": {
        "language": "en-US",
        "schedule": {
            "start_at": "2024-08-01T12:30:00+00:00",
            "max_duration": 900
        },
        "glossary": [
            "Speaker name",
            "Company Name",
            "Specific Terminology"
        ]
         "connection_plan": {
            "facility_id": 11,
            "vchip_rating_code": 1111
        },
        "type": "web_url",
        "external_urls": [
     				 "http://encoder"
    		]
        "notes": null
        "url_type": "teams",
        "connection_params": {
            "url": "https://my-company.zoom.us/j/4383414521",
            "free_text": null,
            "settings": {
              "passcode": null,
              "phone_number": null,
              "phone_number_passcode": null,
              "captioner_url": null,
              "conference_phone_number": null,
              "conference_phone_country_code": null,
              "conference_access_code": null
            }
        }
    },
    "output": [
        {
            "product": {
                "type": "captions",
                "tier": "automatic",
                "target_languages": [
                    "en-US"
                ]
            },
            "delivery": [
              {
                "type": "websocket",
                "language": "123"
              }
            ],
            "discard_transcript": "media"
        },
    ],
    "po_number": "1111",
    "settings": {
      "asr": {
        "profanity_filter": true,
        "domain": "Education"
      },
      "captions_placement": {
      	"id": 1
   	 }
  },
  "cost_center": null,
  "contact_details": {
    "email": "[email protected]",
    "phone_number": "555-555-5555",
    "phone_country_code": "01",
    "first_name": "Bob",
    "last_name": "Barker",
    "cc_email_addresses": [
    "[email protected]"
    ],
    "order_contact_person_email": "[email protected]",
    "order_contact_person_first_name": "Sidney",
    "order_contact_person_last_name": "Sparks"
  }
    
}'

name: Specify an order name (max length 200 characters)
client_transaction_id: Unique transaction id which will be assigned to an order and used for tracing. (unique, max length: 50 characters). The user will need to generate custom GUID for this property.
input: This object holds all the key values of the order details:
- language: The language of the input of the audio/video source.
- schedule: The date and time the order is scheduled to start.
  - start_at: The start time uses at UTC Format YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00).
  - max_duration: This is the duration of the session in seconds. In this example 900 seconds would be 15 minutes.
- glossary: any words added to the glossary that might appear in the audio highly affect the quality of the output.
- connection_plan: Connection plans are for TV encoder based orders that go through the VITAC flow.
  - Facility_id: This is an ID assigned by the VITAC team.
  - vchip_rating_code: This is determined by the environment VITAC environment.
- type: The type of the media source, where the audio would come from. Here are the following values:
  - web_url: Audio/Video source coming from a web URL like in this example Teams or a Zoom call,
  - websocket: Audio/Video source coming from a WebSocket address.
  - rtmp_push: Audio/Video source coming from an RTMP server streaming that is delivered from the encoder.
  - rtmp_pull: Audio/Video source coming from an RTMP server streaming that can be retrieved from the encoder for playback.
  - onsite: Audio/Video that is coming from an onsite encoder.
  - icap: Audio/Video that is coming from an iCap device.
  - dial_in: Audio/Video coming from a source via telephone.
  - decoder: Audio/Video coming from a captioning decoder device.
- external_urls: This property is used for pull audio source from encoders.
- notes: This attaches notes to the job to give details.
- url_type: This property specifies what is the specific Audio/Vided origination source of the URL (E.g. Zoom, Teams, GotoMeeting).
- connection_params: This object holds all the properties needed for connecting to the event:
- free_text:
- url: This is the URL source of the Audio/Video origination.
- settings: This object holds all the settings that are required for the source that is needed for access:
  - passcode: Some platforms require a passcode value.
  - phone_number: This would be the number needed to access the audio device.
  - phone_number_passcode: Some platforms may require a passcode. This code is used to grant access to a meeting via phone.
  - captioner_url: This is url that receives the captions on some platforms.
  - conference_phone_number: This would be the number needed to access the audio via conference platform.
  - conference_phone_country_code: This takes a country code that the conference phone number originates (E.g. US country code is "01).
  - conference_access_codeThis is typically a passcode for the conference.
output: This object holds the parameters of the delivery of the order:
- product: This object holds all the product parameter data:
  - type: This property indicates the type of product (Captions, Translations. Transcriptions).
  - tier": This determines the service level for the order (Automatic, Elite, Professional).
  - target_languages: This determines the specific language of the product.
- delivery: This object determines the delivery of the order.
  - type: This determines the type of delivery (delivery) (websocket, rtmp_push, zoom, teams, verbitext, ics, source_platform, post_session_revision).
  - language: Language code. Format should be RFC 5646 Language code.
- discard_transcript: This property determines which script type needs to be discarded (media, media_and_transcript).
po-number: This is the purchase order number.
settings: This object determine specific settings for the order:
- asr: This object builds our the ASR settings:
  - profanity_filter: Determines if the user wants to filer out profanity (True, False).
  - domain: This property allows the order to be assigned to a specific domain (Education, Legal, Media, Finance).
- captions_placement: This object allows the order determine place of captions on the screen.
  - id: This id determines the assigned position as an integer ( 1 , 3, 4, 6, 7, 9).
cost-center: This is the cost center number that will be applied to the order.
contact_details: This object contains all the contact details attached to this order:
- email: This an email for the person possibly managing the event.
- phone_number: This a phone number for the person possibly managing the event.
- phone_country_code: This is the country code for the person possibly managing the event.
- first_name: This is the first name for the person possibly managing the event.
- last_name: This the email for the person possibly managing the event.
- cc_email_addresses: This object contains a list of email addresses.
- order_contact_person_email: This email address is for the person managing the order.
- order_contact_person_first_name: This is the first name for the person managing the order.
- order_contact_person_last_name: This is the first name for the person managing the order.

Updating An Order and In Bulk

Updating an order is the similar to creating an order but a PATCH request will be called instead. The user will need to obtain the client_transaction_id of the order that needs to be update. If the user is updating orders in bulk this will require the user to provide an array of orders in the body of the call.

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.

Order Update

Here is an example of an order update call:

curl --request PATCH \
     --url https://orders.verbit.co/api/v2/orders \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer <BEARER-TOKEN>' \
     --data '
[
  {
    "name": "Live Show",
    "category_id": "A course",
    "client_transaction_id": "81190fa2-93c3-4e67-867a-7668cd8eac51",
    "status": {
      "name": "canceled"
    },
    "internal_status": {
      "name": "pending_missing_data"
    },
    "input": {
      "connection_params": {
        "url": "https://server.customer-domain.com/"
      },
      "external_urls": [
        "string"
      ],
      "glossary": [
        "John",
        "Marry"
      ],
      "schedule": {
        "max_duration": 28800,
        "start_at": "2023-02-08T13:24:51.569Z",
        "timezone": "Europe/Kyiv"
      },
      "url_type": "zoom"
    },
    "po_number": "string",
    "cost_center": "string",
    "settings": {
      "asr": {
        "profanity_filter": false,
        "domain": "Education"
      },
      "captions_placement": {
        "id": 1
      }
    },
    "contact_details": {
      "email": "[email protected]",
      "phone_number": "539977661",
      "phone_country_code": "+972",
      "first_name": "John",
      "last_name": "Doe",
      "cc_email_addresses": [
        "[email protected]",
        "[email protected]"
      ],
      "order_contact_person_email": "[email protected]",
      "order_contact_person_first_name": "John",
      "order_contact_person_last_name": "Doe"
    },
    "attachments": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "groups": [
      {
        "rules": [
          {
            "recurrence_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "rrule": "RRULE:FREQ=WEEKLY;COUNT=2",
            "start_at": "2024-07-09T12:16:13.844139+00:00",
            "max_duration": 28800,
            "timezone": "Europe/Kyiv"
          }
        ],
        "id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
        "blackout_days": "2024-07-28T00:00:00"
      }
    ],
    "psr_product_id": "string",
    "psr_product": {
      "id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
      "type": "transcription",
      "addon_type": "MDTECH",
      "tier": "automatic",
      "target_languages": "en-US",
      "turn_around_time_hours": 72,
      "service_type": "live"
    },
    "editor_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "legal_template_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
]
'

Updating Orders In Bulk

Here is an example of an order update call:

curl --request PATCH \
     --url https://orders.verbit.co/api/v2/orders \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer <BEARER-TOKEN>' \
     --data '
[
  {
    "name": "Live Show",
    "category_id": "A course",
    "client_transaction_id": "81190fa2-93c3-4e67-867a-7668cd8eac51",
    "status": {
      "name": "canceled"
    },
    "internal_status": {
      "name": "pending_missing_data"
    },
    "input": {
      "connection_params": {
        "url": "https://server.customer-domain.com/"
      },
      "external_urls": [
        "string"
      ],
      "glossary": [
        "John",
        "Marry"
      ],
      "schedule": {
        "max_duration": 28800,
        "start_at": "2023-02-08T13:24:51.569Z",
        "timezone": "Europe/Kyiv"
      },
      "url_type": "zoom"
    },
    "po_number": "string",
    "cost_center": "string",
    "settings": {
      "asr": {
        "profanity_filter": false,
        "domain": "Education"
      },
      "captions_placement": {
        "id": 1
      }
    },
    "contact_details": {
      "email": "[email protected]",
      "phone_number": "539977661",
      "phone_country_code": "+972",
      "first_name": "John",
      "last_name": "Doe",
      "cc_email_addresses": [
        "[email protected]",
        "[email protected]"
      ],
      "order_contact_person_email": "[email protected]",
      "order_contact_person_first_name": "John",
      "order_contact_person_last_name": "Doe"
    },
    "attachments": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "groups": [
      {
        "rules": [
          {
            "recurrence_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "rrule": "RRULE:FREQ=WEEKLY;COUNT=2",
            "start_at": "2024-07-09T12:16:13.844139+00:00",
            "max_duration": 28800,
            "timezone": "Europe/Kyiv"
          }
        ],
        "id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
        "blackout_days": "2024-07-28T00:00:00"
      }
    ],
    "psr_product_id": "string",
    "psr_product": {
      "id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
      "type": "transcription",
      "addon_type": "MDTECH",
      "tier": "automatic",
      "target_languages": "en-US",
      "turn_around_time_hours": 72,
      "service_type": "live"
    },
    "editor_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "legal_template_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
]
'

Get An Order

If a order needs to be obtained a call the folling GET endpoint needs to be made:

curl --request GET \
     --url https://orders.verbit.co/api/v2/orders/order_id \
     --header 'accept: application/json'\
     --header 'authorization: Bearer <BEARER-TOKEN>' \

A response would look like this:

{
  "order": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "category_id": "string",
    "short_id": "string",
    "name": "Live Show",
    "client_transaction_id": "81190fa2-93c3-4e67-867a-7668cd8eac51",
    "status": {
      "name": "created"
    },
    "internal_status": {
      "name": "pending_missing_data"
    },
    "last_updated_at": "2024-07-09T12:16:13.844139+00:00",
    "input": {
      "language": "en-US",
      "glossary": [
        "John",
        "Marry"
      ],
      "schedule": {
        "max_duration": 28800,
        "start_at": "2024-11-01T11:33:38.195810Z"
      },
      "external_urls": [
        "string"
      ],
      "connection_plan": {
        "facility_id": 0,
        "vchip_rating_code": "string"
      },
      "notes": "string",
      "connection_params": {
        "url": "wss://wss.customer-domain.com/"
      }
    },
    "output": [
      {
        "product": {
          "target_languages": [
            "en-US"
          ],
          "tier": "automatic",
          "type": "captions"
        },
        "delivery": [
          {
            "connection_params": {
              "url": "ws://platform.verbit.co/ws?token=eyJhbGciO...."
            },
            "type": "websocket"
          }
        ],
        "discard_transcript": "media",
        "allow_asr_fallback": false,
        "legal_template_id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
        "session_duration": [
          {
            "started_at": "2024-11-27T20:05:18.299Z",
            "duration": 28800
          }
        ],
        "status": {
          "name": "created"
        }
      }
    ],
    "po_number": "123456",
    "cost_center": "123456",
    "service_type": "live",
    "settings": {
      "asr": {
        "profanity_filter": false,
        "domain": "Education"
      },
      "captions_placement": {
        "id": 1
      }
    },
    "contact_details": {
      "email": "[email protected]",
      "phone_number": "539977661",
      "phone_country_code": "+972",
      "first_name": "John",
      "last_name": "Doe",
      "cc_email_addresses": [
        "[email protected]",
        "[email protected]"
      ],
      "order_contact_person_email": "[email protected]",
      "order_contact_person_first_name": "John",
      "order_contact_person_last_name": "Doe"
    },
    "request_origin": "frontend",
    "attachments": [
      {
        "id": "d851f169-5050-4efb-bcdc-42d24046f90c",
        "filestack_id": "AbcdexFgrtskkae",
        "file_name": "file.pdf"
      }
    ],
    "created_by": {
      "email": "[email protected]",
      "name": "John Doe"
    },
    "container": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Live Show",
      "verbitext_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "has_ad_hoc_orders": true
    },
    "groups": [
      {
        "rules": [
          {
            "recurrence_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "rrule": "RRULE:FREQ=WEEKLY;COUNT=2",
            "start_at": "2024-07-09T12:16:13.844139+00:00",
            "max_duration": 28800,
            "timezone": "Europe/Kyiv"
          }
        ],
        "id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
        "blackout_days": "2024-07-28T00:00:00"
      }
    ],
    "created_at": "2024-07-09T12:16:13.844139+00:00",
    "verbitext_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "editor_ids": [
      "81190fa2-93c3-4e67-867a-7668cd8eac30",
      "81190fa2-93c3-4e67-867a-7668cd8eac31"
    ],
    "collections": [
      {
        "name": "string",
        "user_collection_id": "string",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "short_id": "string",
        "total_orders": 0
      }
    ]
  }
}

Get A List of Orders

A list of orders can be obtained and filtered depending on the criteria needed. A GET call would need to be made to the following endpoint:

 curl --request GET \
     --url https://orders.verbit.co/api/v2/orders \
     --header 'accept: application/json'
     --header 'authorization: Bearer <BEARER-TOKEN>' \

The following response would provide an array of orders with pagination:

{
  "orders": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "category_id": "string",
      "short_id": "string",
      "name": "Live Show",
      "client_transaction_id": "81190fa2-93c3-4e67-867a-7668cd8eac51",
      "status": {
        "name": "created"
      },
      "internal_status": {
        "name": "pending_missing_data"
      },
      "last_updated_at": "2024-07-09T12:16:13.844139+00:00",
      "input": {
        "language": "en-US",
        "glossary": [
          "John",
          "Marry"
        ],
        "schedule": {
          "max_duration": 28800,
          "start_at": "2024-11-01T11:33:38.195810Z"
        },
        "external_urls": [
          "string"
        ],
        "connection_plan": {
          "facility_id": 0,
          "vchip_rating_code": "string"
        },
        "notes": "string",
        "connection_params": {
          "url": "wss://wss.customer-domain.com/"
        }
      },
      "output": [
        {
          "product": {
            "target_languages": [
              "en-US"
            ],
            "tier": "automatic",
            "type": "captions"
          },
          "delivery": [
            {
              "connection_params": {
                "url": "ws://platform.verbit.co/ws?token=eyJhbGciO...."
              },
              "type": "websocket"
            }
          ],
          "discard_transcript": "media",
          "allow_asr_fallback": false,
          "legal_template_id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
          "session_duration": [
            {
              "started_at": "2024-11-27T20:05:18.299Z",
              "duration": 28800
            }
          ],
          "status": {
            "name": "created"
          }
        }
      ],
      "po_number": "123456",
      "cost_center": "123456",
      "service_type": "live",
      "settings": {
        "asr": {
          "profanity_filter": false,
          "domain": "Education"
        },
        "captions_placement": {
          "id": 1
        }
      },
      "contact_details": {
        "email": "[email protected]",
        "phone_number": "539977661",
        "phone_country_code": "+972",
        "first_name": "John",
        "last_name": "Doe",
        "cc_email_addresses": [
          "[email protected]",
          "[email protected]"
        ],
        "order_contact_person_email": "[email protected]",
        "order_contact_person_first_name": "John",
        "order_contact_person_last_name": "Doe"
      },
      "request_origin": "frontend",
      "attachments": [
        {
          "id": "d851f169-5050-4efb-bcdc-42d24046f90c",
          "filestack_id": "AbcdexFgrtskkae",
          "file_name": "file.pdf"
        }
      ],
      "created_by": {
        "email": "[email protected]",
        "name": "John Doe"
      },
      "container": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Live Show",
        "verbitext_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "has_ad_hoc_orders": true
      },
      "groups": [
        {
          "rules": [
            {
              "recurrence_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "rrule": "RRULE:FREQ=WEEKLY;COUNT=2",
              "start_at": "2024-07-09T12:16:13.844139+00:00",
              "max_duration": 28800,
              "timezone": "Europe/Kyiv"
            }
          ],
          "id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
          "blackout_days": "2024-07-28T00:00:00"
        }
      ],
      "created_at": "2024-07-09T12:16:13.844139+00:00",
      "verbitext_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "editor_ids": [
        "81190fa2-93c3-4e67-867a-7668cd8eac30",
        "81190fa2-93c3-4e67-867a-7668cd8eac31"
      ],
      "collections": [
        {
          "name": "string",
          "user_collection_id": "string",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "short_id": "string",
          "total_orders": 0
        }
      ]
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1
  }
}

Get A Transcript

If needed a transcript can be obtained from a specific. This will require an order id. A GET call would be made to this end point:

curl --request GET \
     --url https://orders.verbit.co/api/v2/orders/order_id/transcript \
     --header 'accept: application/json'
     --header 'authorization: Bearer <BEARER-TOKEN>' \

This response example would bring back a link:

{
  "link": "string",
  "is_verbitext_available": true,
  "series_link": "string",
  "audio_recording_link": "string"
}

Cancel An Order

Orders can be cancelled through a PUT request, which will require the order id.

Important Notes:

Cancelation Restrictions: Orders can only be canceled while in the following statuses:

created
pending_approval
pending_execution
ready_to_connect
execution_error
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.

To cancel an order the following call needs to be made to this endpoint:

curl --request PUT \
     --url https://orders.verbit.co/api/v2/orders/order_id/status \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"name":"created"}'
     --header 'authorization: Bearer <BEARER-TOKEN>' \

If successful the following response will be received:

{
  "order": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "category_id": "string",
    "short_id": "string",
    "name": "Live Show",
    "client_transaction_id": "81190fa2-93c3-4e67-867a-7668cd8eac51",
    "status": {
      "name": "created"
    },
    "internal_status": {
      "name": "pending_missing_data"
    },
    "last_updated_at": "2024-07-09T12:16:13.844139+00:00",
    "input": {
      "language": "en-US",
      "glossary": [
        "John",
        "Marry"
      ],
      "schedule": {
        "max_duration": 28800,
        "start_at": "2024-11-01T11:33:38.195810Z"
      },
      "external_urls": [
        "string"
      ],
      "connection_plan": {
        "facility_id": 0,
        "vchip_rating_code": "string"
      },
      "notes": "string",
      "connection_params": {
        "url": "wss://wss.customer-domain.com/"
      }
    },
    "output": [
      {
        "product": {
          "target_languages": [
            "en-US"
          ],
          "tier": "automatic",
          "type": "captions"
        },
        "delivery": [
          {
            "connection_params": {
              "url": "ws://platform.verbit.co/ws?token=eyJhbGciO...."
            },
            "type": "websocket"
          }
        ],
        "discard_transcript": "media",
        "allow_asr_fallback": false,
        "legal_template_id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
        "session_duration": [
          {
            "started_at": "2024-11-27T20:05:18.299Z",
            "duration": 28800
          }
        ],
        "status": {
          "name": "created"
        }
      }
    ],
    "po_number": "123456",
    "cost_center": "123456",
    "service_type": "live",
    "settings": {
      "asr": {
        "profanity_filter": false,
        "domain": "Education"
      },
      "captions_placement": {
        "id": 1
      }
    },
    "contact_details": {
      "email": "[email protected]",
      "phone_number": "539977661",
      "phone_country_code": "+972",
      "first_name": "John",
      "last_name": "Doe",
      "cc_email_addresses": [
        "[email protected]",
        "[email protected]"
      ],
      "order_contact_person_email": "[email protected]",
      "order_contact_person_first_name": "John",
      "order_contact_person_last_name": "Doe"
    },
    "request_origin": "frontend",
    "attachments": [
      {
        "id": "d851f169-5050-4efb-bcdc-42d24046f90c",
        "filestack_id": "AbcdexFgrtskkae",
        "file_name": "file.pdf"
      }
    ],
    "created_by": {
      "email": "[email protected]",
      "name": "John Doe"
    },
    "container": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Live Show",
      "verbitext_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "has_ad_hoc_orders": true
    },
    "groups": [
      {
        "rules": [
          {
            "recurrence_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "rrule": "RRULE:FREQ=WEEKLY;COUNT=2",
            "start_at": "2024-07-09T12:16:13.844139+00:00",
            "max_duration": 28800,
            "timezone": "Europe/Kyiv"
          }
        ],
        "id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
        "blackout_days": "2024-07-28T00:00:00"
      }
    ],
    "created_at": "2024-07-09T12:16:13.844139+00:00",
    "verbitext_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "editor_ids": [
      "81190fa2-93c3-4e67-867a-7668cd8eac30",
      "81190fa2-93c3-4e67-867a-7668cd8eac31"
    ],
    "collections": [
      {
        "name": "string",
        "user_collection_id": "string",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "short_id": "string",
        "total_orders": 0
      }
    ]
  }
}

Reoccurrence API Overview

The Verbit Reoccurrence API allows the user to update single or multiple orders belonging to a reoccurring event series. This API also can cancel reoccurrences as well.

To use this endpoint it will require one of the following user roles:

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).

Learn more about the Booking API data here in the API Reference.

Update Reoccurrence Order

Before making the call to this endpoint the recurrence_id would need to be obtained prior. Here is an example PATCH call that would be made to the following endpoint:

curl --request PATCH \
     --url https://orders.verbit.co/api/v2/recurrences/recurrence_id \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     --header 'authorization: Bearer <BEARER-TOKEN>' \

The following successful response would be received:

{
  "order": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "category_id": "string",
    "short_id": "string",
    "name": "Live Show",
    "client_transaction_id": "81190fa2-93c3-4e67-867a-7668cd8eac51",
    "status": {
      "name": "created"
    },
    "internal_status": {
      "name": "pending_missing_data"
    },
    "last_updated_at": "2024-07-09T12:16:13.844139+00:00",
    "input": {
      "language": "en-US",
      "glossary": [
        "John",
        "Marry"
      ],
      "schedule": {
        "max_duration": 28800,
        "start_at": "2024-11-01T11:33:38.195810Z"
      },
      "external_urls": [
        "string"
      ],
      "connection_plan": {
        "facility_id": 0,
        "vchip_rating_code": "string"
      },
      "notes": "string",
      "connection_params": {
        "url": "wss://wss.customer-domain.com/"
      }
    },
    "output": [
      {
        "product": {
          "target_languages": [
            "en-US"
          ],
          "tier": "automatic",
          "type": "captions"
        },
        "delivery": [
          {
            "connection_params": {
              "url": "ws://platform.verbit.co/ws?token=eyJhbGciO...."
            },
            "type": "websocket"
          }
        ],
        "discard_transcript": "media",
        "allow_asr_fallback": false,
        "legal_template_id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
        "session_duration": [
          {
            "started_at": "2024-11-27T20:05:18.299Z",
            "duration": 28800
          }
        ],
        "status": {
          "name": "created"
        }
      }
    ],
    "po_number": "123456",
    "cost_center": "123456",
    "service_type": "live",
    "settings": {
      "asr": {
        "profanity_filter": false,
        "domain": "Education"
      },
      "captions_placement": {
        "id": 1
      }
    },
    "contact_details": {
      "email": "[email protected]",
      "phone_number": "539977661",
      "phone_country_code": "+972",
      "first_name": "John",
      "last_name": "Doe",
      "cc_email_addresses": [
        "[email protected]",
        "[email protected]"
      ],
      "order_contact_person_email": "[email protected]",
      "order_contact_person_first_name": "John",
      "order_contact_person_last_name": "Doe"
    },
    "request_origin": "frontend",
    "attachments": [
      {
        "id": "d851f169-5050-4efb-bcdc-42d24046f90c",
        "filestack_id": "AbcdexFgrtskkae",
        "file_name": "file.pdf"
      }
    ],
    "created_by": {
      "email": "[email protected]",
      "name": "John Doe"
    },
    "container": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Live Show",
      "verbitext_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "has_ad_hoc_orders": true
    },
    "groups": [
      {
        "rules": [
          {
            "recurrence_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "rrule": "RRULE:FREQ=WEEKLY;COUNT=2",
            "start_at": "2024-07-09T12:16:13.844139+00:00",
            "max_duration": 28800,
            "timezone": "Europe/Kyiv"
          }
        ],
        "id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
        "blackout_days": "2024-07-28T00:00:00"
      }
    ],
    "created_at": "2024-07-09T12:16:13.844139+00:00",
    "verbitext_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "editor_ids": [
      "81190fa2-93c3-4e67-867a-7668cd8eac30",
      "81190fa2-93c3-4e67-867a-7668cd8eac31"
    ],
    "collections": [
      {
        "name": "string",
        "user_collection_id": "string",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "short_id": "string",
        "total_orders": 0
      }
    ]
  }
}

Cancel Orders By Reoccurrence

Orders can also be cancelled by which will require a recurrence_id.

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.

To cancel an order a PUT request would have to be made to the following endpoint.

curl --request PUT \
     --url https://orders.verbit.co/api/v2/recurrences/recurrence_id/cancel \
     --header 'accept: application/json'
     --header 'authorization: Bearer <BEARER-TOKEN>' \

The following successful response will be received:

{
  "order": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "category_id": "string",
    "short_id": "string",
    "name": "Live Show",
    "client_transaction_id": "81190fa2-93c3-4e67-867a-7668cd8eac51",
    "status": {
      "name": "created"
    },
    "internal_status": {
      "name": "pending_missing_data"
    },
    "last_updated_at": "2024-07-09T12:16:13.844139+00:00",
    "input": {
      "language": "en-US",
      "glossary": [
        "John",
        "Marry"
      ],
      "schedule": {
        "max_duration": 28800,
        "start_at": "2024-11-01T11:33:38.195810Z"
      },
      "external_urls": [
        "string"
      ],
      "connection_plan": {
        "facility_id": 0,
        "vchip_rating_code": "string"
      },
      "notes": "string",
      "connection_params": {
        "url": "wss://wss.customer-domain.com/"
      }
    },
    "output": [
      {
        "product": {
          "target_languages": [
            "en-US"
          ],
          "tier": "automatic",
          "type": "captions"
        },
        "delivery": [
          {
            "connection_params": {
              "url": "ws://platform.verbit.co/ws?token=eyJhbGciO...."
            },
            "type": "websocket"
          }
        ],
        "discard_transcript": "media",
        "allow_asr_fallback": false,
        "legal_template_id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
        "session_duration": [
          {
            "started_at": "2024-11-27T20:05:18.299Z",
            "duration": 28800
          }
        ],
        "status": {
          "name": "created"
        }
      }
    ],
    "po_number": "123456",
    "cost_center": "123456",
    "service_type": "live",
    "settings": {
      "asr": {
        "profanity_filter": false,
        "domain": "Education"
      },
      "captions_placement": {
        "id": 1
      }
    },
    "contact_details": {
      "email": "[email protected]",
      "phone_number": "539977661",
      "phone_country_code": "+972",
      "first_name": "John",
      "last_name": "Doe",
      "cc_email_addresses": [
        "[email protected]",
        "[email protected]"
      ],
      "order_contact_person_email": "[email protected]",
      "order_contact_person_first_name": "John",
      "order_contact_person_last_name": "Doe"
    },
    "request_origin": "frontend",
    "attachments": [
      {
        "id": "d851f169-5050-4efb-bcdc-42d24046f90c",
        "filestack_id": "AbcdexFgrtskkae",
        "file_name": "file.pdf"
      }
    ],
    "created_by": {
      "email": "[email protected]",
      "name": "John Doe"
    },
    "container": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Live Show",
      "verbitext_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "has_ad_hoc_orders": true
    },
    "groups": [
      {
        "rules": [
          {
            "recurrence_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "rrule": "RRULE:FREQ=WEEKLY;COUNT=2",
            "start_at": "2024-07-09T12:16:13.844139+00:00",
            "max_duration": 28800,
            "timezone": "Europe/Kyiv"
          }
        ],
        "id": "81190fa2-93c3-4e67-867a-7668cd8eac50",
        "blackout_days": "2024-07-28T00:00:00"
      }
    ],
    "created_at": "2024-07-09T12:16:13.844139+00:00",
    "verbitext_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "editor_ids": [
      "81190fa2-93c3-4e67-867a-7668cd8eac30",
      "81190fa2-93c3-4e67-867a-7668cd8eac31"
    ],
    "collections": [
      {
        "name": "string",
        "user_collection_id": "string",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "short_id": "string",
        "total_orders": 0
      }
    ]
  }
}

Download API Overview

The Verbit DownloadAPI allows the user to allows the user to download a transcript after a completion of an order.

To use this endpoint it will require one of the following user roles:

customer_admin
customer_content_manager
CART participant (Can be used for downloading)

Learn more about the Booking API data here in the API Reference.

Creating A Download

The following details can be specified in the request body:

Order IDs (order_ids) - List of order IDs for which the download request is created.
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)
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. This is how to make POST call to the endpoint to request a download:

curl --request POST \
     --url https://orders.verbit.co/api/v2/deliveries \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer <BEARER-TOKEN>' \
     --data '
{
  "order_ids": [
    "b40f75aa-3681-49a7-b6d7-e1031d8793af"
  ],
  "formats": [
    "srt",
    "txt"
  ],
  "languages": [
    "en-US"
  ],
  "inaudible_mode": "timestamp",
  "timecode_on_speaker_change": true,
  "timecode_interval": 2,
  "timestamps_shift_for_text": "04:00:00",
  "timestamps_shift_for_captions": "00:00:30",
  "translate_on_all_possible_languages": true,
  "first_page": 0
}
'

The following successful response will be received:

{
  "delivery": {
    "id": "860a5dc5-5235-46ab-b751-7f3a7f6bb91b",
    "order_ids": [
      "b40f75aa-3681-49a7-b6d7-e1031d8793af"
    ],
    "formats": [
      "srt",
      "txt"
    ],
    "languages": [
      "en-US"
    ],
    "inaudible_mode": "timestamp",
    "timecode_on_speaker_change": true,
    "timecode_interval": 2,
    "timestamps_shift_for_text": "04:00:00",
    "timestamps_shift_for_captions": "00:00:30",
    "translate_on_all_possible_languages": true,
    "first_page": 0,
    "status": "pending",
    "url": "https://s3.verbit.co/file.zip"
  }
}

Creating Download

To get a download the delivery_id would be needed for the following GET call:

curl --request GET \
     --url https://orders.verbit.co/api/v2/deliveries/delivery_id \
     --header 'accept: application/json'
     --header 'authorization: Bearer <BEARER-TOKEN>' \

The response would be as follows:

{
  "delivery": {
    "id": "860a5dc5-5235-46ab-b751-7f3a7f6bb91b",
    "order_ids": [
      "b40f75aa-3681-49a7-b6d7-e1031d8793af"
    ],
    "formats": [
      "srt",
      "txt"
    ],
    "languages": [
      "en-US"
    ],
    "inaudible_mode": "timestamp",
    "timecode_on_speaker_change": true,
    "timecode_interval": 2,
    "timestamps_shift_for_text": "04:00:00",
    "timestamps_shift_for_captions": "00:00:30",
    "translate_on_all_possible_languages": true,
    "first_page": 0,
    "status": "pending",
    "url": "https://s3.verbit.co/file.zip"
  }
}

Get Download Status

To get a download status the delivery_id would be needed for the following GET call:

curl --request GET \
     --url https://orders.verbit.co/api/v2/deliveries/delivery_id/status \
     --header 'accept: application/json'
     --header 'authorization: Bearer <BEARER-TOKEN>' \

The response would be as follows:

{
  "status": "pending"
}

Upload Attachments API Overview

The Verbit Upload API allow a user to get a pre-signed URL attachments.

To use this endpoint it will require one of the following user roles:

customer_admin
customer_content_manager
CART participant (Can be used for downloading)

Learn more about the Booking API data here in the API Reference.

The a file name would have to be passed into the file_nmae query parameters into a GET call:

curl --request GET \
     --url 'https://orders.verbit.co/api/v2/uploads/attachments?file_name=testfile' \
     --header 'accept: application/json'
     --header 'authorization: Bearer <BEARER-TOKEN>' \

The response would be as follows:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "string",
  "fields": {
    "key": "string",
    "AWSAccessKeyId": "string",
    "x-amz-security-token": "string",
    "policy": "string",
    "signature": "string"
  }
}

Live Booking API

📘
All Verbit APIs use OAuth2.0 authentication. This will require a bearer token to be generated and passed through the Authorization header. Refer to the documentation for details on how to get an API token.

Orders API Overview

Creating An Order

Updating An Order and In Bulk

Order Update

Updating Orders In Bulk

Get An Order

Get A List of Orders

Get A Transcript

Cancel An Order

Reoccurrence API Overview

Update Reoccurrence Order

Cancel Orders By Reoccurrence

Download API Overview

Creating A Download

Creating Download

Get Download Status

Upload Attachments API Overview

📘All Verbit APIs use OAuth2.0 authentication. This will require a bearer token to be generated and passed through the Authorization header. Refer to the documentation for details on how to get an API token.

Orders API Overview

Creating An Order

Updating An Order and In Bulk

Order Update

Updating Orders In Bulk

Get An Order

Get A List of Orders

Get A Transcript

Cancel An Order

Reoccurrence API Overview

Update Reoccurrence Order

Cancel Orders By Reoccurrence

Download API Overview

Creating A Download

Creating Download

Get Download Status

Upload Attachments API Overview

📘
All Verbit APIs use OAuth2.0 authentication. This will require a bearer token to be generated and passed through the Authorization header. Refer to the documentation for details on how to get an API token.