Authentication

# With shell, you can just pass the correct header with each request
curl "https://www.happyscribe.com/api/v1/transcriptions" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/transcriptions', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

You can get your HappyScribe API key by logging in and going to your "Account" page.

HappyScribe expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer **your_api_key_here**"

You must replace **your_api_key_here** with your personal API key.

Uploads

When creating a transcription, a media file URL (accessible to our servers) must be provided.
This can be a publicly accessible URL hosted by you or a third party. We also support public links from services like YouTube and Vimeo. Alternatively, you can upload files directly to our storage system (AWS S3 bucket) and create the transcription using the returned URL.

To upload files to our AWS S3 bucket, you must first request a signed URL using the endpoints below.

1. Get a Signed Url

curl "https://www.happyscribe.com/api/v1/uploads/new?filename=my_media.mp3" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/uploads/new?filename=my_media.mp3', {
  headers: {
    authorization: 'Bearer **your_api_key_here**',
  }
})

{
  "signedUrl": "https://happy-scribe-domain.s3.eu-west-1.amazonaws.com/xxxxxx?x-amx-signature=xxxxx..."
}

This endpoint returns a signed URL which can be used to make PUT requests to our S3 bucket. More information here: docs.aws.amazon.com

Once the file is uploaded, this same URL should be used as the tmp_url when creating the associated transcription.

HTTP Request

GET https://www.happyscribe.com/api/v1/uploads/new

Parameters

Parameter	Description
filename	(required) The filename and extension of the media file (e.g. `my_media.mp3`)

2. Upload your file with the Signed Url

curl -X PUT -T my_media.mp3 -L https://signed-url...

fetch('https://signed-url...', {
    method: 'PUT',
    body: my_media_data // This should be a Blob or File object representing my_media.mp3
})

Once you have a signed URL, you have to upload the file there, and you do it as you would with any AWS S3 bucket.

To upload a file to the signed URL you may use cURL like the example on the right.

Here you have more information about how to deal with AWS S3 signed URLs docs.aws.amazon.com.

Transcriptions

List All Transcriptions

curl "https://www.happyscribe.com/api/v1/transcriptions" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/transcriptions', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

{
    "results": [
        {
            "id": "e458099e7f8da14f9625854ba7b6a026917ad306",
            "name": "interview1.mov",
            "createdAt": "2024-10-29T14:31:29.799+00:00",
            "updatedAt": "2024-10-29T14:31:38.495+00:00",
            "state": "automatic_done",
            "sharingEnabled": false,
            "language": "en-GB",
            "audioLengthInSeconds": 42,
            "costInCents": 100,
            "refunded": false,
            "_links": {
              "self": {
                "url": "https://www.happyscribe.com/api/v1/transcriptions/e458099e7f8da14f9625854ba7b6a026917ad306"
              }
            },
            "tags": ["To do", "req_1234"],
        },
        {
            "id": "9jossdjdf09j309omsldknslkjndfjknsdfs",
            "name": "interview2.mov",
            "createdAt": "2024-10-29T14:31:29.799+00:00",
            "updatedAt": "2024-10-29T14:31:38.495+00:00",
            "state": "automatic_done",
            "sharingEnabled": false,
            "language": "en-GB",
            "audioLengthInSeconds": 42,
            "costInCents": 100,
            "refunded": false,
            "_links": {
              "self": {
                "url": "https://www.happyscribe.com/api/v1/transcriptions/9jossdjdf09j309omsldknslkjndfjknsdfs"
              }
            },
            "tags": [],
        },
        ...
    ],
    "_links": {
      "next": {
        "url": "https://www.happyscribe.com/api/v1/transcriptions?page=2"
      }
    }
}

Returns a list of transcriptions you’ve previously created. The transcriptions are returned in sorted order, with the most recent charges appearing first. The information returned is metadata about each transcription, not the actual transcript. To retrieve a specific transcript you have to use the export endpoint.

HTTP Request

GET https://www.happyscribe.com/api/v1/transcriptions

Query Parameters

Parameter	Default	Description
organization_id	-	(required) Id of the organization to get the transcriptions from
folder_id	All folders	When set, filters the list to transcriptions that are inside the specified folder or its subfolders. To get the folder id, navigate to the given folder in the web application and copy the id from the URL.
page	0	Request a specific page
tags	-	List of tags to filter by.

Create a Transcription

curl -X POST "https://www.happyscribe.com/api/v1/transcriptions" \
  -H "Authorization: Bearer **your_api_key_here**" \
  -H "Content-Type: application/json" \
  -d '{
    "transcription": {
        "name": "My Interview",
        "language": "en-GB",
        "tmp_url": "https://example.com/my_media.mp3",
        "is_subtitle": false,
        "organization_id": "413",
        "folder_id": "521",
        "tags": ["To do", "req_1234"],
      }
    }'

fetch('https://www.happyscribe.com/api/v1/transcriptions', {
  method: 'POST',
  headers: {
    authorization: 'Bearer **your_api_key_here**',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    transcription: {
      name: 'My Interview',
      language: 'en-GB',
      tmp_url: 'https://example.com/my_media.mp3',
      is_subtitle: false,
      organization_id: '413',
      tags: ['To do', 'req_1234']
    }
  })
})

{
  "id": "9josdjdfo09j309omsldknslkjndfjknsdfs",
  "name": "My Interview",
  "createdAt": "2024-10-29T14:31:29.799+00:00",
  "updatedAt": "2024-10-29T14:31:38.495+00:00",
  "sharingEnabled": false,
  "state": "ingesting",
  "language": "en-GB",
  "tags": ["To do", "req_1234"],
  "_links": {
    "self": {
      "url": "https://www.happyscribe.com/api/v1/transcriptions/f6511f81s5611daede28dc85f25a796ae7996d11"
    },
  }
}

This endpoint creates a new transcription. After a transcription is created, the system will proceed to automatically transcribe it. You can watch if the transcription process has finished by retrieving a transcription.

You can order as many transcriptions as needed (within the established rate limit). The transcriptions will be processed in parallel.

HTTP Request

POST https://www.happyscribe.com/api/v1/transcriptions

Parameters

Parameter	Type	Description
name	String	(required) Name of the transcription
language	String	(required) BCP-47 language code. Full list here
tmp_url	String	(required) A url where the media file is located and can be retrieved by our server.
is_subtitle	Boolean	(default: false) If set to true, we will treat this transcription as subtitles.
service	String	`auto`(default) : Machine generated transcription/subtitles. `pro` : transcription/subtitles hand-crafted by human professionals. `alignment`: Align the text provided in `document_url` with the media from `tmp_url` Note: check the supported languages.
organization_id	String	(required) Id of the organization to save the transcription in.
folder	String	(optional) Path of the folder to save the transcription in. Example: `path/to/my folder`.
folder_id	String	(optional) Id of the folder to save the transcription in.
document_url	String	(only for `alignment` ) An accessible url to a plain text document that needs to be aligned with the media provided in `tmp_url`.
sharing_enabled	Boolean	(default: false) If set to true, everyone with the editor url will be able to access it.
tags	Array	(optional) List of tags to add to the transcription.

The media file tmp_url must be publicly accessible during the ingestion process. Otherwise, our server won't be able to make a copy of it.
Once the file is copied and ingested, we no longer need access to the tmp_url and the file can be safely deleted.

Retrieve a Transcription

curl "https://www.happyscribe.com/api/v1/transcriptions/<ID>" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/transcriptions/<ID>', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

{
  "id": "9josdjdfo09j309omsldknslkjndfjknsdfs",
  "name": "interview2.mov",
  "createdAt": "2024-10-29T14:31:29.799+00:00",
  "updatedAt": "2024-10-29T14:31:38.495+00:00",
  "failureReason": null,
  "sharingEnabled": false,
  "state": "automatic_done",
  "language": "en-GB",
  "audioLengthInSeconds": 42,
  "costInCents": 100,
  "refunded": false,
  "tags": ["To do", "req_1234"],
  "soundwaveUrl":"https://hs-soundwaves-prod.s3-eu-west-1.amazonaws.com/e4c8e370a92aafb8b03da708c5016bb6-10.dat",
  "_links": {
    "self": {
      "url": "https://www.happyscribe.com/api/v1/transcriptions/f6511f81156114aede28dc85325a796ae7996d11"
    },
    "editor": {
      "url": "https://www.happyscribe.com/transcriptions/9josdjdfo09j309omsldknslkjndfjknsdfs/edit_v2",
    },
  }
}

This endpoint retrieves information about a specific transcription. To retrieve the transcript you have to use the export endpoint.

HTTP Request

GET https://www.happyscribe.com/api/v1/transcriptions/<ID>

Soundwave

It's only generated for subtitles ("is_subtitle": true). The soundwaveUrl is not available until the state is automatic_done

Additional transcription properties

Value	Description
`deliveryEstimatedAt`	Estimated time for the transcription to be delivered. It can change over time.
`failureReason`	Error code for the failure.
`failureMessage`	User friendly message explaining the failure root cause.

Transcription State Descriptions

Value	Description
`initial`	Transcription is waiting to be processed
`ingesting`	Media file is being ingested
`automatic_transcribing`	Audio is being transcribed to text
`automatic_done`	Transcription is finished and ready to export!
`aligning`	Text is being realigned with the audio
`locked`	Transcription is locked due to insufficient credits
`failed`	File failed to process
`demo`	The initial demo file

Delete a Transcription

curl -X DELETE "https://www.happyscribe.com/api/v1/transcriptions/<ID>" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/transcriptions/<ID>', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

This endpoint deletes a transcription.

HTTP Request

DELETE https://www.happyscribe.com/api/v1/transcriptions/<ID>

Query Parameters

Parameter	Default	Description
permanent	false	When set to "true" the action is irreversible. Otherwise, the transcription can be found in the Trash.

Exports

Create an Export

curl -X POST "https://www.happyscribe.com/api/v1/exports" \
  -H "Authorization: Bearer **your_api_key_here**" \
  -H 'Content-Type: application/json' \
  -d '{
    "export": {
      "format": "txt",
      "transcription_ids": [
        "**transcription_id_1**"
      ]
    }
  }'

fetch('https://www.happyscribe.com/api/v1/exports', {
  method: 'POST',
  headers: {
    authorization: 'Bearer **your_api_key_here**',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    export: {
      format: 'txt', 
      transcription_ids: 
      [
        '**transcription_id_1**'
      ] 
    }
  })
})

{
   "id":"**export_id**",
   "state":"pending",
   "format":"txt",
   "show_timestamps":false,
   "show_speakers":false,
   "show_comments":false,
   "show_highlights":false,
   "transcription_ids":[
      "**transcription_id_1**"
   ]
}

This endpoint creates a new export. After an export is created, the system will proceed to generate it. You can watch if the exporting process has finished by retrieving an export.

The exporting process is generally very fast. Each file takes ~10s to complete. You can submit more than one file at the same time.

HTTP Request

POST https://www.happyscribe.com/api/v1/exports

JSON Parameters

Parameter	Default	Description
format	none	(required) Specify the export format (see chart below)
show_timestamps	false	Include timestamps (only formats: `txt`, `docx`, `pdf` )
timestamps_frequency	nil	Include inline timecodes at a given frequency (valid values: 5s, 10s, 15s, 20s, 30s, 60s)
show_speakers	false	Include speaker labels (only formats: `txt`, `docx`, `pdf` )
show_comments	false	Include comments (only formats: `txt`, `docx`, `pdf` )
show_highlights	false	Include highlights (only formats: `docx`, `pdf` )
show_highlights_only	false	Include only highlights (only formats: `docx`, `pdf` )

Export formats

Value	Description
txt	Text Document (.txt)
docx	Word Document (.docx)
pdf	PDF Document (.pdf)
srt	Subtitles (SubRip .srt)
vtt	Subtitles (WebVTT .vtt)
stl	Subtitles (EBU-STL .stl)
avid	Avid Markers (.txt)
html	Interactive Transcript (.html)
premiere	Premiere Pro (Beta) (.xml)
maxqda	Maxqda (.txt)
json	JSON (.json)
fcp	Final Cut Pro (.fcp)

Retrieve an Export

curl "https://www.happyscribe.com/api/v1/exports/<ID>" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/exports/<ID>', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

{
   "id":"**export_id**",
   "state":"ready",
   "format":"txt",
   "show_timestamps":false,
   "show_speakers":false,
   "show_comments":false,
   "show_highlights":false,
   "transcription_ids":[
      "**transcription_id_1**",
   ],
   "download_link":"**download_link**"
}

This endpoint retrieves information about a specific export. To download it you can use the returned download_link.

HTTP Request

GET https://www.happyscribe.com/api/v1/exports/<ID>

Export State Descriptions

Value	Description
`pending`	Waiting to be processed.
`processing`	The export is being generated.
`ready`	The export is ready to download.
`expired`	No longer available.
`failed`	A problem occurred.

Translations

Create a Translation Task

curl -X POST "https://www.happyscribe.com/api/v1/task/transcription_translation" \
  -H "Authorization: Bearer **your_api_key_here**" \
  -H 'Content-Type: application/json' \
  -d '{
    "source_transcription_id": "**source_transcription_id**",
    "target_language": "es"
  }'

fetch('https://www.happyscribe.com/api/v1/task/transcription_translation', {
  method: 'POST',
  headers: {
    authorization: 'Bearer **your_api_key_here**',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    source_transcription_id: "**source_transcription_id**",
    target_language: "es"
  })
})

{
  "id": "054fe9f3aa0b446baea730fba688f96c",
  "state": "working",
  "failureReason": null,
  "progressPercent": null,
  "targetLanguage": "es"
}

Creates a new translation task given a source transcription and a target language code. After a translation task is created, the system will proceed to generate a new transcription with the translated content. You can watch the task status and get the result by retrieving a translation task using the response id property.

The translation task typically takes ~10s to complete but can take up to two minutes if the source transcription is large.

If the specified source transcription is itself the result of a translation task, the transcription that will be translated will be the original one, not the translation. Example: We translate a transcription with id = 1 and get a translated transcription with id = 2 as a result. If we create a translation task with source_transcription_id = 2, then the transcription with id = 1 will be used instead. The result will be the same as if we had created the task with source_transcription_id = 1.

HTTP Request

POST https://www.happyscribe.com/api/v1/task/transcription_translation

JSON Parameters

Parameter	Default	Description
source_transcription_id	none	(required) Specify the id of the transcription you want to translate from. It must be in one of the supported source translation languages.
target_language	none	(required) The language code of the language you want to translate to. Full list here.

Target translation languages

Code	Language
af	Afrikaans
sq	Albanian
am	Amharic
ar	Arabic
hy	Armenian
az	Azerbaijani
eu	Basque
bn	Bengali
bs	Bosnian
bg	Bulgarian
ca	Catalan
zh	Chinese
hr	Croatian
cs	Czech
da	Danish
nl	Dutch
en	English
et	Estonian
fil	Filipino
fi	Finnish
fr	French
gl	Galician
ka	Georgian
de	German
el	Greek
gu	Gujarati
he	Hebrew
hi	Hindi
hu	Hungarian
is	Icelandic
id	Indonesian
it	Italian
ja	Japanese
jv	Javanese
kn	Kannada
km	Khmer
ko	Korean
lo	Lao
lv	Latvian
lt	Lithuanian
mk	Macedonian
ms	Malay
ml	Malayalam
mr	Marathi
mn	Mongolian
my	Burmese
ne	Nepali
no	Norwegian
fa	Persian
pl	Polish
pt-PT	Portuguese (Portugal)
pt-BR	Portuguese (Brazil)
pa	Punjabi
ro	Romanian
ru	Russian
sr	Serbian
si	Sinhala
sk	Slovak
sl	Slovenian
es	Spanish
su	Sundanese
sw	Swahili
sv	Swedish
ta	Tamil
te	Telugu
th	Thai
tr	Turkish
uk	Ukrainian
ur	Urdu
uz	Uzbek
vi	Vietnamese
zu	Zulu

Supported source translation languages

Language Code	Language Name
af	Afrikaans
sq	Albanian
am	Amharic
ar	Arabic
hy	Armenian
az	Azerbaijani
eu	Basque
bn	Bengali
bs	Bosnian
bg	Bulgarian
ca	Catalan
cmn-Hans-CN	Chinese, Mandarin (Simplified, China)
cmn-Hans-HK	Chinese, Mandarin (Simplified, Hong Kong)
cmn-Hant-TW	Chinese, Mandarin (Traditional, Taiwan)
hr	Croatian
cs	Czech
da	Danish
nl	Dutch
en	English
et	Estonian
fil	Filipino
fi	Finnish
fr	French
gl	Galician
ka	Georgian
de	German
el	Greek
gu	Gujarati
he	Hebrew
hi	Hindi
hu	Hungarian
is	Icelandic
id	Indonesian
it	Italian
ja	Japanese
jv	Javanese
kn	Kannada
km	Khmer
ko	Korean
lo	Lao
lv	Latvian
lt	Lithuanian
mk	Macedonian
ms	Malay
ml	Malayalam
mr	Marathi
mn	Mongolian
my	Burmese
ne	Nepali
no	Norwegian
fa	Persian
pl	Polish
pt	Portuguese
pa	Punjabi
ro	Romanian
ru	Russian
sr	Serbian
si	Sinhala
sk	Slovak
sl	Slovenian
es	Spanish
su	Sundanese
sw	Swahili
sv	Swedish
ta	Tamil
te	Telugu
th	Thai
tr	Turkish
uk	Ukrainian
ur	Urdu
uz	Uzbek
vi	Vietnamese
zu	Zulu

Retrieve a Translation Task

curl "https://www.happyscribe.com/api/v1/task/transcription_translation/<ID>" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/task/transcription_translation/<ID>', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

{
  "id": "054fe9f3aa0b446baea730fba688f96c",
  "state": "done",
  "failureReason": null,
  "progressPercent": 100.0,
  "targetLanguage": "es",
  "translatedTranscriptionId": "372e9530d8f24ba68ccbcce11de43f9d"
}

This endpoint returns information about a translation task. To get the translated transcription when the task has finished you can use the translatedTranscriptionId property in the response. Remember that you can use the transcription endpoint or the export endpoint to retrieve the information and content of the transcription given the transcription id.

HTTP Request

GET https://www.happyscribe.com/api/v1/task/transcription_translation/<id>

Translation task state descriptions

Value	Description
initial	The task is waiting to be processed
working	The translation is being generated
failed	A problem occured. See the `failureReason` attribute.
done	The translated transcription is ready. The `translatedTranscriptionId` attribute can be used to retrieve the translated transcription.

Orders

This new section of the API replaces the deprecated Translations endpoints. For speech-to-text use cases you can still refer to the Transcriptions endpoints.

Create a Translation Order

curl -X POST "https://www.happyscribe.com/api/v1/orders/translation" \
  -H "Authorization: Bearer **your_api_key_here**" \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
      "source_transcription_id": "**source_transcription_id**",
      "target_languages": ["es"],
      "service": "pro",
      "confirm": true
    }
  }'

fetch('https://www.happyscribe.com/api/v1/orders/translation', {
  method: 'POST',
  headers: {
    authorization: 'Bearer **your_api_key_here**',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    order: {
      source_transcription_id: "**source_transcription_id**",
      target_languages: ["es"],
      service: "pro",
      confirm: false
    }
  })
})

{
  "id": "7cb8b631b14342da900f49fbc02faf14",
  "folder_id": 1,
  "state": "submitted",
  "operations": [
    {
      "name": "subtitles",
      "type": "pro",
      "language": "en-US",
      "use_vocab": true,
      "glossary_ids": []
    },
    {
      "name": "transcription_translation",
      "type": "pro",
      "language": "en-US",
      "glossary_ids": [],
      "target_language": "es"
    }
  ],
  "details": {
    "items": [
      {
        "id": 256,
        "filename": "TED+Talk [SUB]",
        "pricing_unit_name": "minutes",
        "pricing_unit_count": 0.12,
        "service": {
          "name": "subtitles",
          "type": "pro",
          "language": "en-US",
          "use_vocab": true,
          "glossary_ids": []
        },
        "addon_id": null,
        "addon_name": null,
        "turnaround_minutes": 1440,
        "cents_per_unit": 214,
        "cents": 100,
        "credits": null
      },
      {
        "id": 256,
        "filename": "TED+Talk [SUB]",
        "pricing_unit_name": "minutes",
        "pricing_unit_count": 0.12,
        "service": {
          "name": "transcription_translation",
          "type": "pro",
          "language": "en-US",
          "glossary_ids": [],
          "target_language": "es"
        },
        "addon_id": null,
        "addon_name": null,
        "turnaround_minutes": 4320,
        "cents_per_unit": 475,
        "cents": 57,
        "credits": null
      }
    ],
    "pricing_unit_name": "minutes",
    "pricing_unit_total_count": 0.12,
    "total_cents": 157,
    "total_credits": null,
    "currency": "usd",
    "currency_symbol": "$",
    "addons_total_cents": {
      "rush": 12,
      "verbatim": 12,
      "light_human": 0,
      "sdh": 18
    },
    "minimum_charge": 50
  },
  "addons": [],
  "inputs": [
    {
      "transcription_id": "aec40bff9aa6409da41658cb20c1b89f"
    }
  ],
  "needsMoneyWalletTopup": false,
  "showUpgradeBusinessModal": false,
  "canTopupOffSession": true,
  "currentUserIsPayer": true,
  "canBeSubmitted": false,
  "detectedLanguage": null,
  "suggestedLanguages": [],
  "duplicates": [],
  "outputsCount": 1
}

Creates a new translation order based on a source transcription and one or more target languages. After a translation order is created, the system will generate new transcriptions with the translated content for each target language specified. You can monitor the order status and access the results by retrieving the order using the response id property.

The translation processing time depends on the service type:

For "auto" service: Typically completed within a few seconds
For "pro" service: Approximately 3 days for human translation

Important: When translating a transcription that is itself already a translation, the system will automatically use the original source transcription. For example: If transcription id = 1 was translated to create transcription id = 2, and you request a translation using source_transcription_id = 2, the system will automatically use transcription id = 1 as the source. This ensures consistent translations from the original content.

HTTP Request

POST https://www.happyscribe.com/api/v1/orders/translation

JSON Parameters

Parameter	Default	Description
source_transcription_id	none	(required) The ID of the transcription you want to translate from.
target_languages	none	(required) An array of language codes you want to translate to. See the full list here.
service	auto	Specify "pro" for human translation or "auto" for automatic translation.
confirm	false	When set to true, the order will be submitted automatically. When false, the order remains in "incomplete" state until confirmed.

Response

The response follows the Order object structure as described in the "Retrieve an Order" section.

Key fields in the response include:

id: Use this identifier to check the order status later
state: Initially "submitted" (when confirm=true) or "incomplete" (when confirm=false)
operations: Details of the translation operations being performed
inputs: Contains the source transcription ID

Retrieve an Order

curl "https://www.happyscribe.com/api/v1/orders/<ID>" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/orders/<ID>', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

{
  "id": "10b1edd9381d4a00a3d0db1ca1b3d0cf",
  "folder_id": 1,
  "state": "incomplete",
  "operations": [
    {
      "name": "transcription_translation",
      "type": "auto",
      "language": "en-US",
      "target_language": "es",
      "glossary_ids": []
    }
  ],
  "details": {
    "items": [
      {
        "id": 258,
        "filename": "TED+Talk",
        "pricing_unit_name": "minutes",
        "pricing_unit_count": 0.12,
        "service": {
          "name": "transcription_translation",
          "type": "auto",
          "language": "en-US",
          "target_language": "es",
          "glossary_ids": []
        },
        "addon_id": null,
        "addon_name": null,
        "turnaround_minutes": 1,
        "cents_per_unit": 20,
        "cents": 3,
        "credits": 0.12
      }
    ],
    "pricing_unit_name": "minutes",
    "pricing_unit_total_count": 0.12,
    "total_cents": 3,
    "total_credits": 0.12,
    "currency": "usd",
    "currency_symbol": "$",
    "addons_total_cents": {},
    "minimum_charge": 50
  },
  "addons": [],
  "inputs": [
    {
      "transcription_id": "e5fb537cecc9436b93c04be2a9219001"
    }
  ],
  "needsMoneyWalletTopup": false,
  "showUpgradeBusinessModal": false,
  "canTopupOffSession": true,
  "currentUserIsPayer": true,
  "canBeSubmitted": true,
  "detectedLanguage": null,
  "suggestedLanguages": [],
  "duplicates": [],
  "outputsCount": 0
}

This endpoint retrieves information about a specific order by its ID. Use this endpoint to check the status of an order, view its details, and access the results when the order is complete.

HTTP Request

GET https://www.happyscribe.com/api/v1/orders/<ID>

URL Parameters

Parameter	Description
ID	The unique identifier of the order to retrieve

Order Description

Field	Description
id	Unique identifier for the order (UUID format)
folder_id	ID of the folder containing the order
state	Current state of the order (see "Order States" below)
operations	Array of operations being performed as part of this order
details	Contains pricing information, items being processed, and other order details
inputs	Source materials for the order, including transcription_id
outputsCount	Number of outputs generated by the order
canBeSubmitted	Whether the order can be submitted
currentUserIsPayer	Whether the current API user is responsible for payment
needsMoneyWalletTopup	Whether additional funds are needed to process the order
addons	Array of additional services applied to the order
duplicates	Array of any duplicate orders detected in the system
suggestedLanguages	Suggested languages for translation based on source content
detectedLanguage	Automatically detected language of the source content

Order States

State	Description
incomplete	The order has been created but not yet submitted for processing
waiting_for_payment	The order is waiting for payment to be processed
submitted	The order has been submitted for processing
locked	Legacy state for pay-as-you-go orders that are being verified for payment
fulfilled	The order has been completed successfully
failed	The order processing has failed
canceled	The order has been canceled
expired	The order has expired
free_trial_submitted	Legacy state for free trial orders that have been submitted
free_trial_fulfilled	Legacy state for free trial orders that have been fulfilled

Operations Object

The operations array contains details about each operation being performed as part of the order:

Field	Description
name	The type of operation (e.g., "transcription_translation", "subtitles")
type	The service level ("auto" or "pro")
language	The source language code
target_language	The target language code for translation operations
glossary_ids	Array of glossary IDs to use for the translation
use_vocab	Whether to use vocabulary optimization (for subtitle operations)

Confirm an Order

curl -X POST "https://www.happyscribe.com/api/v1/orders/<ID>/confirm" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/orders/<ID>/confirm', {
  method: "POST",
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

This endpoint confirms an order that was previously created with confirm=false. Once confirmed, the order will begin processing according to the service type selected.

HTTP Request

POST https://www.happyscribe.com/api/v1/orders/<ID>/confirm

URL Parameters

Parameter	Description
ID	The unique identifier of the order to confirm