Skip to main content
POST
/
api
/
v1
/
job-titles
/
canonicalize
Canonicalize job titles
curl --request POST \
  --url https://trynormalize.com/api/v1/job-titles/canonicalize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "<string>",
  "inputs": [
    "<string>"
  ],
  "exclude": [
    "<string>"
  ],
  "include": [
    "<string>"
  ],
  "debug": false
}
'
{
  "best_title": "<string>",
  "best_title_id": "<string>",
  "cluster": "<string>",
  "cluster_id": "<string>",
  "seniority": [
    "<string>"
  ],
  "confidence": 0.5,
  "needs_review": true,
  "debug": {
    "parse": {
      "language": "<string>",
      "include_groups": [
        {
          "op": "<string>",
          "phrases": [
            "<string>"
          ]
        }
      ],
      "exclude_phrases": [
        "<string>"
      ],
      "detected_seniority": [
        "<string>"
      ],
      "raw_intent": "<string>"
    },
    "matches": [
      {
        "phrase": "<string>",
        "title_id": "<string>",
        "title_label": "<string>",
        "cluster_id": "<string>",
        "method": "<string>",
        "score": 123
      }
    ]
  }
}

Authorizations

Authorization
string
header
required

API key from the dashboard. Pass as Authorization: Bearer <key>.

Body

application/json

Use input or inputs, not both.

input
string

Single input string. Use input or inputs, not both.

Maximum string length: 500
inputs
string[]

Batch of inputs. Use input or inputs, not both.

Maximum array length: 100
exclude
string[]

Titles or keywords to exclude from results.

Maximum array length: 25
include
string[]

Override parsed include phrases.

Maximum array length: 25
debug
boolean
default:false

Include parse structure and matches in response.

Response

Success (single or batch)

best_title
string | null
required
best_title_id
string | null
required
cluster
string | null
required
cluster_id
string | null
required
seniority
string[]
required
confidence
number
required
Required range: 0 <= x <= 1
needs_review
boolean
required
debug
object