> For the complete documentation index, see [llms.txt](https://api-docs.speechace.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.speechace.com/api-reference/score-word.md).
# Score Word
{% hint style="info" %}
**Run In Postman:** [Score a Word](https://docs.speechace.com/#824b2e5a-4e68-4946-ab15-7c5bdf0e7084)
{% endhint %}
The **Score Word** API scores the pronunciation of a **single lexical unit** — whether that is a dictionary word, a letter name, a letter sound, a non-word, or a set of single-word choices. It applies scoring optimizations and model combinations tuned for utterances where the speaker produces just one item, so it is the recommended endpoint whenever your activity targets one word (or one target chosen from a few).
For scoring a phrase, sentence, or passage of connected speech, use Score Text instead.
### What you can score
Everything Score Word handles is expressed through the `word` parameter — as plain text, as an `arpa_mark` phonetic string, or as `\n`-separated targets for multiple choice. There is no separate endpoint per input type; the table below maps each kind of target to how you pass it.
| Input type | Pass it as | Example word value |
| --------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------- |
| **Dictionary word** | Plain text | `cat` |
| Letter name
(the letter's spoken name)
| Plain text | `B` |
| Letter sound
(the phoneme a letter makes)
| `arpa_mark` | `[b]{b ah0}` with `markup_language=arpa_mark` |
| Non-word
(nonsense / custom word)
| `arpa_mark` | `[shuz\|zle]{sh ah1 \| z ah0 l}` with `markup_language=arpa_mark` |
| Multiple choice
(several single-word targets)
| `\n`-separated | `cat\ndog` |
{% hint style="info" %}
**Letter name vs. letter sound.** A *letter name* is scored by passing the letter itself as text (`word=B`). A *letter sound* is the phoneme that letter represents — express it with `arpa_mark` (`[b]{b ah0}`). Both flow through the same `word` parameter documented below.
**Markup tip:** the `arpa_mark` examples above include syllable boundaries (`|`) and stress marks (`0`/`1`/`2`). Score Word treats both as optional, but including them improves scoring — we recommend always providing them.
{% endhint %}
### Request Format
The endpoint to use will depend on the [region](/getting-started/api-regions-and-endpoints.md) of your subscription. For example, for US West, the endpoint is .
`POST` [`https://api.speechace.co/api/scoring/word/v9/json`](https://api.speechace.co/api/scoring/word/v9/json)
### Headers
| Name | Value |
|---|
| Content-Type | application/json |
### Query Parameters
| Parameter | Type | Description |
|---|
| key | String | Required API key issued by Speechace. |
| dialect | String | Optional default = en-us Supported values are: en-us, en-gb, es-es, es-mx, fr-fr, fr-ca |
| user_id | String | Optional A unique anonymized identifier (generated by your applications) for the end-user who submitted the response. |
### Request Body
| Parameter | Type | Description |
|---|
| word | String | Required. Max length: 300 characters. Word to score. Can be expressed as one of: - text: (e.g. "cat")
- arpa_mark: (e.g. "[cat]{k ah1 t}")
- Multiple Choice with '\n' as separator: (e.g. "cat\ndog")
- Multiple choice with arpa_mark: (e.g. "[cat]{k ah1 t}\n[dog]{d ao1 g})
Note: arpa_mark and Multiple choice only supported with en-us and en-gb dialects. |
| user_audio_file | File | Required. Max Duration: 30 seconds.
File with user audio (wav, mp3, m4a, webm, ogg, aiff) |
| markup_language | String | Optional
Supported values are: arpa_mark
Pass this parameter when using markup language in the word parameter.
Note: arpa_mark is only supported with en-us and en-gb dialects. |
| include_interference_metrics | String | Optional
Use include_interference_metrics=1 to include interference metrics in the response. When set, the interference_ratio field is returned inside word_score.
See the Detecting Speech Interference guide for how to interpret and use this field.
Note: include_interference_metrics is only supported with en-us and en-gb dialects. |
### Request Examples
The below examples show different modes of calling the Score Word API with the responses:
| Example | Request Body Parameters | When to Use |
|---|
| A. Score a word | word="cat" | When scoring a single word and you just want to accept Speechace lexicon for inferring phonetic makeup of the word. |
| B. Score a word with markup | word="[read]{r iy1 d}"
markup_language="arpa_mark" | When you wish to pass the exact expected phonetic markup for the word.
For example in this case you want the present tense of "read" rather than the possibility of present or past tense. |
| C. Score a word with MC | word="cat\ndog" | When you have multiple targets in your activity.
For example, you show 2 pictures of a dog and a cat and the learner speaks their favorite. |
| D. Score a word with MC and markup | word="[cat]{k ah1 t}\n[dog]{d ao1 g}"
markup_language="arpa_mark" | When you have multiple targets but you also wish to explicitly pass the exact phonetic markup for each target. |
{% hint style="info" %}
You can Review the full arpa\_mark syntax [here](/reference-data/markup-language.md#markup-syntax).
**Note:** Score Word relaxes two arpa\_mark syntax constraints:
* Stress is optional (i.e. no 0,1,2 stress required on vowels)
* Syllable boundary is optional (i.e. no '|' required between word syllables)\
\
Speechace strongly recommends passing stress and syllable information for best scoring results.
{% endhint %}
### Response Examples
Below are API response examples for each of the above cases: A, B, C, D.
{% tabs %}
{% tab title="A. word=" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}
```json
{
"status": "success",
"word_score": {
"word": "cat",
"quality_score": 98,
"quality_class": "pass",
"phone_score_list": [
{
"phone": "k",
"stress_level": null,
"extent": [
11,
17
],
"quality_score": 92,
"sound_most_like": "k"
},
{
"phone": "ae",
"stress_level": 1,
"extent": [
17,
29
],
"quality_score": 100,
"stress_score": 100,
"predicted_stress_level": 1,
"sound_most_like": "ae"
},
{
"phone": "t",
"stress_level": null,
"extent": [
29,
47
],
"quality_score": 100,
"sound_most_like": "t"
}
],
"syllable_score_list": [
{
"phone_count": 3,
"stress_level": 1,
"letters": "cat",
"quality_score": 97,
"stress_score": 100,
"predicted_stress_level": 1,
"extent": [
11,
47
]
}
]
},
"version": "9.17"
}
```
{% endcode %}
{% endtab %}
{% tab title="B. word=" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}
```json
{
"status": "success",
"word_score": {
"word": "read",
"quality_score": 100,
"quality_class": "pass",
"phone_score_list": [
{
"phone": "r",
"stress_level": null,
"extent": [
5,
17
],
"quality_score": 100,
"sound_most_like": "r"
},
{
"phone": "iy",
"stress_level": 1,
"extent": [
17,
29
],
"quality_score": 98,
"stress_score": 100,
"predicted_stress_level": 1,
"sound_most_like": "iy"
},
{
"phone": "d",
"stress_level": null,
"extent": [
29,
41
],
"quality_score": 100,
"sound_most_like": "d"
}
],
"syllable_score_list": [
{
"phone_count": 3,
"stress_level": 1,
"letters": "read",
"quality_score": 99,
"stress_score": 100,
"predicted_stress_level": 1,
"extent": [
5,
41
]
}
]
},
"version": "9.17"
}
```
{% endcode %}
{% endtab %}
{% tab title="C. word=" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}
```json
{
"status": "success",
"word_score": {
"word": "cat",
"quality_score": 98,
"quality_class": "pass",
"phone_score_list": [
{
"phone": "k",
"stress_level": null,
"extent": [
11,
17
],
"quality_score": 92,
"sound_most_like": "k"
},
{
"phone": "ae",
"stress_level": 1,
"extent": [
17,
29
],
"quality_score": 100,
"stress_score": 100,
"predicted_stress_level": 1,
"sound_most_like": "ae"
},
{
"phone": "t",
"stress_level": null,
"extent": [
29,
47
],
"quality_score": 100,
"sound_most_like": "t"
}
],
"syllable_score_list": [
{
"phone_count": 3,
"stress_level": 1,
"letters": "cat",
"quality_score": 97,
"stress_score": 100,
"predicted_stress_level": 1,
"extent": [
11,
47
]
}
]
},
"version": "9.17"
}
```
{% endcode %}
{% endtab %}
{% tab title="D. word=" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}
```json
{
"status": "success",
"word_score": {
"word": "cat",
"quality_score": 98,
"quality_class": "pass",
"phone_score_list": [
{
"phone": "k",
"stress_level": null,
"extent": [
11,
17
],
"quality_score": 92,
"sound_most_like": "k"
},
{
"phone": "ae",
"stress_level": 1,
"extent": [
17,
29
],
"quality_score": 100,
"stress_score": 100,
"predicted_stress_level": 1,
"sound_most_like": "ae"
},
```
{% endcode %}
{% endtab %}
{% endtabs %}
### Response fields
The response JSON contains the following scores.
| Field | Description |
|---|
word_score.word | The target word. If Multiple Choice was used, this is the closest target to what the user spoke. |
word_score.quality_score | The pronunciation score for the word (scale 0..100). See this guide for interpreting the quality_score. |
word_score.quality_class | pass | fail. The classification for the word based on its quality_score. The threshold applied for pass is quality_score ≥ 70. |
word_score.syllable_score_list | An array of syllables within the word, each with its quality_score, stress, and extent information. |
word_score.phone_score_list | An array of phonemes within the word, each with its quality_score, stress, and extent information. |
### Replacing Score Phone List
Score Word is the recommended way to score any single word built from a phoneme sequence, and is a complete replacement for the older Score Phone List endpoint — for both dictionary words and custom non-words.
Score Word uses [arpa\_mark](/reference-data/markup-language.md) to express an exact phonetic sequence, and (unlike Phone List) does not *require* stress notation or syllable boundaries — so converting an existing `phone_list` call is straightforward.
| Example | score phone_list syntax | score word syntax |
|---|
| The word: gotcha | phone_list="g|ao|ch|ah" | word="[gotcha]{g ao ch ah}" |
The word: photographer
* no stress or syllable boundaries | phone_list="f|ah|t|aa|g|r|ah|f|er" | word="[photographer]{f ah t aa g r ah f er}" |
The word: photographer
* with stress and syllable boundaries | phone_list="f|ah|t|aa|g|r|ah|f|er" | word="[pho|tog|ra|pher]{f ah0|t aa1 g|r ah0|f er0}" |
{% hint style="info" %}
Although stress and syllable boundaries are optional, we recommend including them — as in the third example. They improve scoring, especially for longer multi-syllable words.
{% endhint %}