/versions/{version}/normalize

Normalize a raw job title string to the best matching Lightcast title

Supported document types and their expected Content-Type (Document must be UTF-8 encoded.):

JSON – application/json
Plain text – text/plain

Raw title size is limited to 1kB.

Note that this endpoint has a base tier yearly quota of 50 requests. Contact us if you'd like this increased or made unlimited. Responses from this endpoint will include two headers, RateLimit-Remaining and RateLimit-Reset, which indicate how many requests you have remaining in your current quota period and when that quota will reset, respectively.

`POST` Normalize a title

This endpoint requires additional permissions, please contact us if you'd like access to normalization.

URL Parameters

Name	Description
versionstring	The title version.Example: `latest`

Query Parameters

Name	Description
confidenceThresholdnumber	Filter out titles with a confidence value lower than this threshold (this query param does not apply for JSON requests).Minimum: `0`Maximum: `1`Default: `0.5`
fieldsstring	List of fields to return per title. See /versions/{version} for available fields (this query param does not apply for JSON requests).This parameter is optional.Default: `id,name`

Request Body

{
  "term": "data scientist"
}

{
    "$schema": "http://json-schema.org/draft-07/schema",
    "$id": "requests/normalize.schema.json",
    "type": "object",
    "properties": {
        "term": {
            "title": "Title name",
            "type": "string",
            "minLength": 1
        },
        "fields": {
            "title": "List of fields to return per title",
            "description": "See [/versions/{version}](#versions-version) for available fields.\n\n`mappings` require additional permissions, please [contact us](https://docs.lightcast.dev/contact) if you'd like access to mappings.",
            "type": "array",
            "items": {
                "type": "string",
                "minLength": 1,
                "__nodocs": true
            },
            "minItems": 1,
            "default": [
                "id",
                "name"
            ]
        },
        "confidenceThreshold": {
            "title": "Filter out normalized titles with a confidence value lower than this threshold",
            "type": "number",
            "default": 0.5,
            "minimum": 0,
            "maximum": 1
        }
    },
    "required": [
        "term"
    ],
    "additionalProperties": false
}

Code Examples

{
  "method": "POST",
  "url": "https://api.lightcast.io/titles/versions/latest/normalize",
  "show": true,
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer "
    },
    {
      "name": "Content-Type",
      "value": "application/json"
    }
  ],
  "postData": {
    "mimeType": "application/json",
    "text": "{ \"term\": \"data scientist\" }"
  },
  "queryString": []
}

Response Examples

{
  "data": {
    "confidence": 1,
    "jobLevels": [],
    "title": {
      "id": "ET3B93055220D592C8",
      "name": "Data Scientist"
    }
  }
}

Invalid request.

{
  "errors": [
    {
      "status": 400,
      "title": "Invalid request",
      "detail": "Invalid request body"
    }
  ]
}

You don't have access to the normalization endpoint.

{
  "errors": [
    {
      "status": 401,
      "title": "Unauthorized",
      "detail": "You do not have access to this endpoint, please contact us at '[email protected]' to request access."
    }
  ]
}

The version you requested wasn't found.

{
  "errors": [
    {
      "title": "URL not found",
      "status": 404,
      "detail": "Unrecognized version: invaildVersion"
    }
  ]
}

Request size too large.

{
  "errors": [
    {
      "detail": "Request size too large",
      "status": 413,
      "title": "Payload Too Large"
    }
  ]
}

Unsupported Content Type.

{
  "errors": [
    {
      "detail": "Accepted Content-Type(s): 'application/json', 'application/pdf', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'",
      "status": 415,
      "title": "Unsupported Content Type"
    }
  ]
}

{
    "$schema": "http://json-schema.org/draft-07/schema",
    "$id": "responses/normalize.schema.json",
    "type": "object",
    "properties": {
        "data": {
            "title": "Title normalize response object",
            "type": "object",
            "properties": {
                "title": {
                    "title": "Normalized title",
                    "type": "object",
                    "properties": {
                        "id": {
                            "title": "Title id",
                            "type": "string",
                            "minLength": 1
                        },
                        "name": {
                            "title": "Title name",
                            "type": "string",
                            "minLength": 1
                        },
                        "pluralName": {
                            "title": "Plural form of title name",
                            "type": "string",
                            "minLength": 1
                        },
                        "mapping": {
                            "title": "Title SOC and skill mappings",
                            "type": "object",
                            "properties": {
                                "names": {
                                    "title": "List of mapping names",
                                    "description": "Mapping names are included in Titles v4.6 and onward.\n\nTitles may have zero or more mappings associated with them, the names of those mappings are listed here and represented in the unified list of skills and socs below.",
                                    "type": "array",
                                    "items": {
                                        "type": "string",
                                        "minLength": 1,
                                        "__nodocs": true
                                    }
                                },
                                "socs": {
                                    "title": "List of SOC mappings",
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "id": {
                                                "title": "SOC code",
                                                "type": "string",
                                                "minLength": 1
                                            },
                                            "name": {
                                                "title": "SOC name",
                                                "type": "string",
                                                "minLength": 1
                                            }
                                        },
                                        "required": [
                                            "id",
                                            "name"
                                        ],
                                        "additionalProperties": false
                                    }
                                },
                                "skills": {
                                    "title": "List of skill mappings",
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "id": {
                                                "title": "Skill id",
                                                "type": "string",
                                                "minLength": 1
                                            },
                                            "name": {
                                                "title": "Skill name",
                                                "type": "string",
                                                "minLength": 1
                                            }
                                        },
                                        "required": [
                                            "id",
                                            "name"
                                        ],
                                        "additionalProperties": false
                                    }
                                }
                            },
                            "required": [
                                "socs",
                                "skills",
                                "names"
                            ],
                            "additionalProperties": false
                        },
                        "isSupervisor": {
                            "title": "Boolean value indicating whether the title's role is supervisory",
                            "type": "boolean",
                            "__internal": true
                        },
                        "levelBand": {
                            "title": "Standardized job level category",
                            "type": [
                                "string",
                                "null"
                            ],
                            "minLength": 1,
                            "__internal": true
                        },
                        "infoUrl": {
                            "title": "URL for a publicly accessible web page that includes information about the title",
                            "type": [
                                "string",
                                "null"
                            ],
                            "minLength": 1,
                            "pattern": "https://lightcast.io/open-titles/titles/.+"
                        }
                    },
                    "additionalProperties": false
                },
                "confidence": {
                    "title": "A number between 0 and 1 representing the confidence of the title normalization",
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1
                },
                "jobLevels": {
                    "title": "List of normalized job seniority information",
                    "type": "array",
                    "items": {
                        "type": "string",
                        "minLength": 1,
                        "__nodocs": true
                    }
                }
            },
            "required": [
                "title",
                "confidence",
                "jobLevels"
            ],
            "additionalProperties": false
        }
    },
    "required": [
        "data"
    ],
    "additionalProperties": false
}