Introduction

The US Profiles API provides access to Lightcast’s comprehensive database of U.S. profiles. It allows you to retrieve profiles that can be filtered, sorted, and ranked by various properties such as company, occupation, skills, and geography.

Profiles are collected from multiple sources and enriched with standardized metadata, including company names, job titles, skills, and geographic information.

Note: By default, all clients are allowed a maximum of 5 requests per second. Contact us if you require higher limits.

📑Latest OpenAPI Specification

Request Headers

(*) Indicates the action to be required

All requests must include the following headers:

Header Key	Value	Description
*Authorization	Bearer `<ACCESS_TOKEN>`	This is the token obtained from the Authentication API. Include it in this header to authorize the request. (This must be included in all authenticated requests)
Content-Type	application/json	Required for endpoints that accept a request body. Specifies that the body is in JSON format.

Authentication

All endpoints in this category require an OAuth 2.0 Bearer Token for authentication. Tokens are granted through Lightcast’s Authentication API and are valid for 1 hour.

To access the US Profiles API, the token must include the following scope:

profiles:us (for access to U.S. profiles)

Sample Request

curl --request POST \
  --url https://auth.emsicloud.com/connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=CLIENT_ID \
  --data client_secret=CLIENT_SECRET \
  --data grant_type=client_credentials \
  --data scope=profiles:us

Request Parameters

Parameter	Type	Description
client_id	string	The client ID provided by Lightcast.
client_secret	string	The client secret associated with your client ID.
grant_type	string	Must be set to `client_credentials`.
scope	string	Use `profiles:us` based on your access.

Filtering

Filtering

All endpoints support an extensive filter request object, allowing you to narrow job postings to specific subsets.

Required filter property:

when – Filters job postings by date, either "active" for currently active postings or an object specifying start and end dates.

Taxonomy Filters

Many filters correspond to a taxonomy and support ID-based or name-based filtering:

ID filters – Use taxonomy codes (e.g., skill IDs).
Name filters – Use exact names of items (e.g., skill names).

Important: Exact matches are required, including capitalization, punctuation, and whitespace. Supported codes/names can be retrieved via /rankings or /taxonomies.

Shorthand Filter Example

{
  "when": {
    "start": "2018-01",
    "end": "2018-06"
  },
  "skills_name": [
    "SQL (Programming Language)",
    "C++ (Programming Language)"
  ]
}

Matches postings that include either SQL or Python skills in the first six months of 2025.

Verbose Filter Example

{
  "when": {
    "start": "2025-01-01",
    "end": "2025-06-30"
  },
  "skills_name": {
    "include": [
      "SQL (Programming Language)",
      "Python (Programming Language)"
    ],
    "include_op": "and",
    "exclude": [
      "Java (Programming Language)"
    ],
    "exclude_op": "or"
  },
  "occupation_id": [1234, 5678],
  "company_name": [
    "Acme Corp",
    "Global Tech Solutions"
  ],
  "geography_name": [
    "United States",
    "Canada"
  ]
}

This matches postings active between January 1 and June 30, 2025:

Include postings with both SQL and Python skills,

Exclude postings with Java,

Filtered by occupation IDs, company names, and countries.

Notes

include_op / exclude_op define how multiple values are matched:
- and – all items must match
- or – any item can match
All filter conditions must be true for a job posting to be included.

Metrics Reference: For a full list of job posting metrics and definitions, see the Job Postings Metrics page

Sample Response

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Note that the Tokens expire after 3600 seconds. To maintain uninterrupted access, refresh the token before it expires. To know more about this, refer to the Authentication guide.

Response Parameters

Parameter	Type	Description
access_token	string	The token used to authorize the API requests.
expires_in	integer	Number of seconds before the token expires.
token_type	string	Indicates the type of token. (Always Bearer).

Status Code Summary

Code	Meaning	Description
200	OK	Request was successful.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	Authentication error.
404	Not Found	Resource not found.

🔗
For a complete list of HTTP status codes and their meanings, refer here.