Core components in an order

Your basic order would look like this:

{
    "name": "My first order",
    "client_transaction_id": "{{$guid}}",
    "input": {
        "language": "en-US",
        "schedule": {
            "recurrence": false,
            "start_at": "2024-08-26T08:03:00.000Z",
            "timezone": "Asia/Jerusalem",
            "max_duration": 3600
        },
        "type": "onsite"
    },
    "output": [
        {
            "product": {
                "type": "captions",
                "tier": "automatic",
                "target_languages": [
                    "en-US"
                ]
            }
        }
    ]
}

You can see that there are a few basic fields:

name

This is the name of your order.

client_transaction_id

This is your internal identifier - how you know your order. This needs to be unique for each order you create.

input

This is where you give info about the audio source. You would need to specify the media source (type), the language we are expected to transcribe, and the schedule of when the event should start and finish.

output

This is the product you are buying in this order.

In the example above you can see that we are buying captions (which is used for transcription)

With automatic service tier - this service tier is Captivate basic. For Captivate - use proffesional.

The target language is what language should we output.

If you want to also have live translation you can see how to book it in this example

Order's status

An order can be in any of those statuses:

created - The order was created successfully. Please note that it is not yet confirmed. You will need to wait for the pending_execution status to be sure that the order would work. For Captivate and Captivate Basic orders the confirmation should arrive almost immediately.
pending_execution - The order was approved and is pending execution until the start time.
ready_to_connect - The order event is ready to start, for example, a Zoom event.
in_progress - The order is currently in progress. Once complete it will move to completed. If there were any errors during the event, the status will reflect as execution_error.
completed - The order is complete. The event was executed successfully.

pending_approval - Once created, orders that require a human to be assigned to them may move to pending_approval status. From here the order can either be approved and moved to pending_execution or to bedeclined in the rear occasion that we won't have a human to support it.
declined - An order can be declined while in pending approval status. Once declined, no further processing of the order is possible.

canceled - An order can only be canceled while pending_execution or pending_approval. Different cancelation terms and conditions apply to each service tier.

excecution_error - An error occurred while executing the order event.
returned -

Note: An order status can only be updated to canceled through the API (while the current status of the order is pending_execution or pending_approval).

You can find out about missing information here in the Internal Status (internal_status). From this field, you can see if your order has missing information, for example, a missing meeting link.

Recurring orders

You can also book transcription for a recurring meeting without having to keep renewing the order. You can use rrule in order to do that.

Recurrence rules (rrule) are used to define repeating events. Here's a simplified explanation with examples:

Basic Components:

Frequency: How often the event repeats (DAILY, WEEKLY, MONTHLY, YEARLY)
Interval: The interval between occurrences (e.g., every 2 weeks)
Byweekday: Specific days of the week (MO, TU, WE, TH, FR, SA, SU)
Bymonthday: Specific days of the month
Bymonth: Specific months of the year
Count: Number of occurrences
Until: End date of the recurrence

And more... google it 😀

Examples:

Daily for 5 days: FREQ=DAILY;COUNT=5
Weekly on Mondays and Tuesdays for 5 weeks: FREQ=WEEKLY;COUNT=5;BYDAY=MO,TU
Monthly on the first Monday of every month for 3 months: FREQ=MONTHLY;BYDAY=1MO;COUNT=3
Daily until November 17, 2024: RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20241117T140000Z

Using in Code:

{...
  "schedule": {
            "recurrence": true,
            "start_at": "2024-08-26T08:03:00.000Z",
            "rrule": "RRULE:FREQ=WEEKLY;COUNT=2",
            "timezone": "Asia/Jerusalem",
            "max_duration": 3600
        },...
}