Quickstart

This page takes you from zero to a full job-postings response in under five minutes. You need nothing but a terminal with curl.

1. Sign up and get 100 free credits

Create an account at rolesapi.com. The free plan includes 100 credits, one time, with no card required. One credit buys one role detail or one search page.

2. Create an API key

In the dashboard, open API keys and create a key. Keys start with rk_ and are shown once — copy it somewhere safe. See Authentication for rotation and storage practices.

3. Make your first call

Fetch a role straight from an Indeed viewjob URL:

curl "https://api.rolesapi.com/v1/roles/by-url?url=https://www.indeed.com/viewjob?jk=a1b2c3d4e5f60718" \
  -H "Authorization: Bearer rk_live_your_key"

The response:

{
  "data": {
    "job_key": "a1b2c3d4e5f60718",
    "title": "Senior Backend Engineer",
    "company": { "name": "Acme Logistics", "rating": 4.1, "url": "https://www.indeed.com/cmp/Acme-Logistics" },
    "location": "Austin, TX",
    "remote": false,
    "employment_type": "Full-time",
    "salary": { "min": 140000, "max": 175000, "currency": "USD", "period": "year", "source": "employer" },
    "benefits": ["Health insurance", "401(k) matching", "Paid time off"],
    "description": "Acme Logistics is hiring a Senior Backend Engineer to build the services that power our fulfillment network...",
    "posted_at": "2026-06-28",
    "url": "https://www.indeed.com/viewjob?jk=a1b2c3d4e5f60718",
    "country": "us"
  },
  "request_id": "req_8f3a2b1c"
}

That call used 1 credit. You have 99 left.

How do I read the envelope?

Every successful response has the same shape:

Field	Meaning
data	The object (or array) you asked for.
meta	Present on list responses: total, count, limit, offset, has_more. See Pagination.
request_id	A unique id for this request. Include it when contacting support.

Errors use a parallel envelope — { "error": { "code", "message", "request_id" } } — documented in Errors.

What should I try next?

• Search postings by keyword and location: POST /v1/search.
• Pull up to 500 roles in one request: POST /v1/roles/batch and Async jobs.
• Get CSV instead of JSON with ?format=csv: Output formats.
• Trim responses with ?fields=title,company.name,salary.min: Field projection.
• Connect an AI agent over MCP: AI agents.