> ## Documentation Index
> Fetch the complete documentation index at: https://www.hirebase.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Look Up Jobs by URL

> Find live jobs from the posting URLs you already have. Billed only for the jobs found.

If you already have the postings (from your ATS, a spreadsheet or a scrape) and need their Hirebase records, for example to get the `job_id` for [Hiring Manager Contacts](https://www.hirebase.org/docs/api-reference/jobs/contacts.md), look them up by URL instead of searching by company and title. You pay for the jobs that match, not for every job a search returns.

## Endpoint

```bash theme={null}
POST /v2/jobs/lookup
```

## Request Body

**urls** `string[]` *required*

1 to 100 posting URLs: the job's page on its ATS or careers site (each at most 2,048 characters). Copied links still match: tracking parameters such as `?utm_source=`, a trailing `/application` or `/apply`, a trailing slash, and either Greenhouse host (`boards.greenhouse.io` or `job-boards.greenhouse.io`).

## Response

**jobs** `object[]`

The live jobs found, each in the same shape as [Get Job by ID](https://www.hirebase.org/docs/api-reference/jobs/get-by-id.md). A job matched by two of your URLs appears once.

**matches** `object[]`

Which of your URLs matched which job.

**url** `string`

The URL as you sent it

**job\_id** `string`

The matching job's `_id`

**not\_found** `string[]`

URLs that matched no live job, including postings that have already closed.

## Billing

Each job in `jobs` counts as one job toward your plan's job allowance, the same as a job returned by [Job Search](https://www.hirebase.org/docs/api-reference/jobs/search-post.md). URLs in `not_found` are free.

## Example Request

```bash cURL theme={null}
curl -X POST "https://api.hirebase.org/v2/jobs/lookup" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "urls": [
      "https://jobs.ashbyhq.com/companyxyz/0a6c6a9e-1234-4c5d-9e8f-123456789abc/application?utm_source=linkedin",
      "https://example.com/careers/not-a-job"
    ]
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.hirebase.org/v2/jobs/lookup",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"urls": [
        "https://jobs.ashbyhq.com/companyxyz/0a6c6a9e-1234-4c5d-9e8f-123456789abc/application?utm_source=linkedin",
        "https://example.com/careers/not-a-job",
    ]},
)
data = response.json()
for match in data["matches"]:
    print(match["url"], "->", match["job_id"])
```

## Example Response

Jobs are shortened here; each one has every field from [Get Job by ID](https://www.hirebase.org/docs/api-reference/jobs/get-by-id.md).

```json theme={null}
{
  "jobs": [
    {
      "_id": "67d550e407a47816d9b14f42",
      "job_title": "Design Engineer",
      "company_name": "CompanyXYZ",
      "application_link": "https://jobs.ashbyhq.com/companyxyz/0a6c6a9e-1234-4c5d-9e8f-123456789abc"
    }
  ],
  "matches": [
    {
      "url": "https://jobs.ashbyhq.com/companyxyz/0a6c6a9e-1234-4c5d-9e8f-123456789abc/application?utm_source=linkedin",
      "job_id": "67d550e407a47816d9b14f42"
    }
  ],
  "not_found": ["https://example.com/careers/not-a-job"]
}
```

## Error Responses

> [accordion] 401 Unauthorized
>
> Missing or invalid API key.

> [accordion] 422 Unprocessable Entity
>
> `urls` is empty, has more than 100 entries, or contains a URL longer than 2,048 characters.

> [accordion] 429 Too Many Requests
>
> Your plan's job allowance is used up (`X-Billing-Code: limit_exceeded`), or you hit the rate limit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.