# Search jobs (/docs/reference/jobs/search)

`GET https://api.getmattered.com/api/v1/developer/jobs/search`

Searches the whole job supply by title and place, beyond the candidate's matches. Answers only jobs GetMattered can apply to now, best first, at most 10: narrow the search rather than page it. Omit `query` and `location` to search the candidate's saved preferences. Pass a result's `jobUrl` to `POST /developer/apply`. Free.

Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md).

## Parameters

- `location` (query): A city or country. Omit it to search the countries in the candidate's preferences.

- `needsVisaSponsorship` (query): `true` drops jobs that say they do not sponsor a visa.

- `postedWithinDays` (query): Only jobs posted in the last this many days.

- `query` (query): A job title. Omit it to search the titles in the candidate's preferences.

- `remoteOnly` (query): `true` keeps only remote jobs.

- `salaryMin` (query): Lowest yearly pay in US dollars. A job with no stated pay stays in.

## Responses

### 200: Jobs GetMattered can apply to now, best first.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "countries": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "ae",
              "ar",
              "at",
              "au",
              "bd",
              "be",
              "bh",
              "bo",
              "br",
              "ca",
              "ch",
              "cl",
              "cn",
              "co",
              "cr",
              "cu",
              "cz",
              "de",
              "dk",
              "do",
              "ec",
              "eg",
              "es",
              "fi",
              "fr",
              "gr",
              "gt",
              "hk",
              "hn",
              "hu",
              "id",
              "ie",
              "il",
              "in",
              "ir",
              "it",
              "jp",
              "ke",
              "kr",
              "kw",
              "lu",
              "mx",
              "my",
              "ng",
              "ni",
              "nl",
              "no",
              "nz",
              "om",
              "pa",
              "pe",
              "ph",
              "pk",
              "pl",
              "pr",
              "pt",
              "py",
              "qa",
              "ro",
              "ru",
              "sa",
              "sd",
              "se",
              "sg",
              "sv",
              "tr",
              "ua",
              "ug",
              "uk",
              "us",
              "uy",
              "ve",
              "vn",
              "za",
              "xx"
            ],
            "description": "ISO-3166-1 alpha-2 country code (xx = unknown)",
            "example": "de"
          },
          "description": "The countries the search read"
        },
        "jobs": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "company": {
                "type": "string",
                "example": "Ramp"
              },
              "jobMatchId": {
                "type": [
                  "integer",
                  "null"
                ],
                "exclusiveMinimum": 0,
                "description": "The candidate's own match for this job, when there is one: `GET /developer/jobs/{id}` reads it.",
                "example": 90412
              },
              "jobUrl": {
                "type": "string",
                "description": "The employer's own posting. `POST /developer/apply` takes it as `postingUrl`.",
                "example": "https://jobs.ashbyhq.com/acme/1f2e3d4c"
              },
              "location": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "postedDate": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "When the employer posted it, as the source wrote it"
              },
              "remote": {
                "type": "boolean"
              },
              "salaryMaxUsd": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "salaryMinUsd": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "system": {
                "type": "string",
                "description": "The hiring system name a person reads",
                "example": "Ashby"
              },
              "title": {
                "type": "string",
                "example": "Founding Engineer"
              }
            },
            "required": [
              "company",
              "jobMatchId",
              "jobUrl",
              "location",
              "postedDate",
              "remote",
              "salaryMaxUsd",
              "salaryMinUsd",
              "system",
              "title"
            ]
          },
          "maxItems": 10
        },
        "outcome": {
          "type": "string",
          "enum": [
            "found",
            "none_found",
            "no_query",
            "no_place",
            "no_remote_country"
          ],
          "description": "What the job search found: jobs, none, or why it could not search",
          "example": "found"
        },
        "titles": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The job titles the search read"
        }
      },
      "required": [
        "countries",
        "jobs",
        "outcome",
        "titles"
      ]
    },
    "meta": {
      "type": "object",
      "properties": {
        "duration": {
          "type": "number",
          "minimum": 0,
          "description": "Request duration in milliseconds",
          "example": 150
        },
        "performance": {
          "type": "object",
          "properties": {
            "dbQueries": {
              "type": "integer",
              "minimum": 0
            },
            "totalDbTime": {
              "type": "number",
              "minimum": 0
            }
          },
          "description": "Performance metrics (preview/local only)"
        },
        "requestId": {
          "type": "string",
          "description": "Unique request identifier",
          "example": "req_abc123"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp",
          "example": "2026-11-17T12:00:00.000Z"
        },
        "version": {
          "type": "string",
          "description": "API version",
          "example": "v1"
        }
      }
    },
    "success": {
      "type": "boolean",
      "enum": [
        true
      ]
    }
  },
  "required": [
    "data",
    "success"
  ],
  "additionalProperties": false,
  "description": "Successful API response"
}
```

### 400: Bad Request

### 401: Unauthorized

### 404: Not Found

### 429: Too Many Requests

### 500: Internal Server Error

### 503: Service Unavailable

Error responses use the envelope in /errors.md.