# Save job preferences (/docs/reference/preferences)

`PUT https://api.getmattered.com/api/v1/developer/preferences`

Saves the candidate's job preferences the way GetMattered saves them: titles and places are matched to known ones, then the matches are rebuilt for the new search. Fields you omit stay as saved. At most 6 saves in 5 minutes per account, the app's limit. Free.

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

## Request body (application/json)

```json
{
  "type": "object",
  "properties": {
    "benefits": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Must-have job benefits",
      "example": [
        "health_insurance",
        "remote_work"
      ]
    },
    "companySize": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Preferred company sizes",
      "example": [
        "startup",
        "small"
      ]
    },
    "educationLevel": {
      "type": "string",
      "description": "Minimum education level filter",
      "example": "bachelor"
    },
    "excludeIndustries": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Industries to exclude from matches",
      "example": [
        "Government & Public Sector"
      ]
    },
    "experienceLevel": {
      "type": "string",
      "enum": [
        "intern",
        "entry",
        "junior",
        "mid",
        "senior",
        "lead",
        "executive"
      ],
      "description": "Target experience level (DEPRECATED scalar  -  prefer `experienceLevels`). When `experienceLevels` is present it wins; this scalar is kept so legacy mobile binaries keep working.",
      "example": "senior"
    },
    "experienceLevels": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "intern",
          "entry",
          "junior",
          "mid",
          "senior",
          "lead",
          "executive"
        ],
        "description": "Professional experience level",
        "example": "mid"
      },
      "description": "Target experience levels (multi-select, new source of truth). Empty/omitted = no seniority constraint. The first element is mirrored into the deprecated scalar `experienceLevel`.",
      "example": [
        "mid",
        "senior"
      ]
    },
    "includeRemote": {
      "type": "boolean",
      "description": "Include region-restricted remote jobs (workStyles \"remote\") even when specific locations are set. Does NOT control worldwide remote  -  see `remoteGlobal`.",
      "example": true
    },
    "remoteGlobal": {
      "type": "boolean",
      "description": "Accept worldwide \"Remote  -  Anywhere (Global)\" jobs from any region. Independent of `includeRemote`/workStyles \"remote\" (which stay region-restricted). Set via the \"Remote  -  Anywhere (Global)\" option in the location picker.",
      "example": false
    },
    "industries": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Target industries",
      "example": [
        "Technology",
        "Finance"
      ]
    },
    "isActive": {
      "type": "boolean",
      "description": "Enable or disable daily matches",
      "example": true
    },
    "jobTypes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Preferred job types",
      "example": [
        "full_time",
        "contract"
      ]
    },
    "locations": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 5,
      "description": "Preferred locations as \"City, Country\" or \"Country\" (max 5). Middle admin segments (state/province) are stripped on ingest. Placeholder values (\"anywhere\", \"any\", ...) are rejected for security (they disable location scoping and let clients harvest the full job pool). An empty array is accepted ONLY for a caller opted into `remoteGlobal` - worldwide remote is itself the location answer.",
      "example": [
        "San Francisco, United States",
        "Berlin, Germany"
      ]
    },
    "salaryCurrency": {
      "type": "string",
      "enum": [
        "usd",
        "eur",
        "gbp",
        "cad",
        "aud",
        "inr"
      ],
      "description": "Currency for the salary band (converted to USD for matching). Defaults to usd.",
      "example": "eur"
    },
    "salaryMax": {
      "type": "number",
      "minimum": 0,
      "description": "Maximum salary requirement",
      "example": 200000
    },
    "salaryMin": {
      "type": "number",
      "minimum": 0,
      "description": "Minimum salary requirement",
      "example": 100000
    },
    "skills": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "User skills (from resume or manual entry)",
      "example": [
        "TypeScript",
        "React",
        "Node.js",
        "PostgreSQL"
      ]
    },
    "targetRoles": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200
      },
      "minItems": 1,
      "maxItems": 5,
      "description": "Target role titles (max 5). When present, at least one specific title is required  -  empty arrays and placeholder values (\"anywhere\", \"any\", ...) are rejected for security (they disable role scoping and let clients harvest the full job pool).",
      "example": [
        "Software Engineer",
        "Full Stack Developer"
      ]
    },
    "visaSponsorship": {
      "type": "string",
      "description": "Visa sponsorship preference",
      "example": "required"
    },
    "workStyles": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "onsite",
          "hybrid",
          "remote"
        ],
        "description": "User's preferred work style, physical mode only, no geo scoping",
        "example": "remote"
      },
      "minItems": 1,
      "description": "Preferred work styles (onsite/hybrid/remote)  -  multi-select, at least 1 required. Geo scoping is inferred from `locations`, NOT this field.",
      "example": [
        "remote",
        "hybrid"
      ]
    }
  },
  "additionalProperties": false,
  "example": {
    "locations": [
      "San Francisco, United States"
    ],
    "salaryCurrency": "usd",
    "salaryMax": 190000,
    "salaryMin": 150000,
    "targetRoles": [
      "Senior Software Engineer",
      "Full Stack Developer"
    ],
    "workStyles": [
      "remote",
      "hybrid"
    ]
  }
}
```

## Responses

### 200: The preferences as saved.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "allOf": [
        {
          "type": "object",
          "properties": {
            "benefits": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              }
            },
            "companySize": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              }
            },
            "createdAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "educationLevel": {
              "type": [
                "string",
                "null"
              ]
            },
            "excludeIndustries": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              }
            },
            "experienceLevel": {
              "type": [
                "string",
                "null"
              ]
            },
            "experienceLevels": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              }
            },
            "id": {
              "type": "integer"
            },
            "includeRemote": {
              "type": "boolean"
            },
            "industries": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              }
            },
            "isActive": {
              "type": "boolean"
            },
            "jobTypes": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              }
            },
            "locations": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              }
            },
            "remoteGlobal": {
              "type": "boolean"
            },
            "salaryCurrency": {
              "type": "string",
              "enum": [
                "usd",
                "eur",
                "gbp",
                "cad",
                "aud",
                "inr"
              ],
              "description": "Currency for salary values",
              "example": "usd"
            },
            "salaryMax": {
              "type": [
                "number",
                "null"
              ]
            },
            "salaryMin": {
              "type": [
                "number",
                "null"
              ]
            },
            "skills": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              }
            },
            "targetRoles": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              }
            },
            "updatedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "visaSponsorship": {
              "type": [
                "string",
                "null"
              ]
            },
            "workStyles": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "onsite",
                  "hybrid",
                  "remote"
                ],
                "description": "User's preferred work style, physical mode only, no geo scoping",
                "example": "remote"
              }
            }
          },
          "required": [
            "benefits",
            "companySize",
            "createdAt",
            "educationLevel",
            "excludeIndustries",
            "experienceLevel",
            "experienceLevels",
            "id",
            "includeRemote",
            "industries",
            "isActive",
            "jobTypes",
            "locations",
            "remoteGlobal",
            "salaryCurrency",
            "salaryMax",
            "salaryMin",
            "skills",
            "targetRoles",
            "updatedAt",
            "visaSponsorship",
            "workStyles"
          ]
        },
        {
          "type": "object",
          "properties": {
            "prefsChanged": {
              "type": "boolean",
              "description": "PUT only. True when this save changed at least one job_match_preference column (always true when it created the row). False means nothing moved. Absent on GET.",
              "example": true
            }
          }
        }
      ]
    },
    "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",
  "example": {
    "data": {
      "benefits": null,
      "companySize": [
        "startup",
        "medium"
      ],
      "createdAt": "2026-09-01T12:00:00.000Z",
      "educationLevel": "bachelor",
      "excludeIndustries": null,
      "experienceLevel": "senior",
      "experienceLevels": [
        "senior"
      ],
      "id": 311,
      "includeRemote": true,
      "industries": [
        "Software & SaaS",
        "Financial Services"
      ],
      "isActive": true,
      "jobTypes": [
        "full_time"
      ],
      "locations": [
        "San Francisco, United States"
      ],
      "remoteGlobal": false,
      "salaryCurrency": "usd",
      "salaryMax": 190000,
      "salaryMin": 150000,
      "skills": [
        "TypeScript",
        "React",
        "Node.js",
        "PostgreSQL"
      ],
      "targetRoles": [
        "Senior Software Engineer",
        "Full Stack Developer"
      ],
      "updatedAt": "2026-09-20T08:30:00.000Z",
      "visaSponsorship": null,
      "workStyles": [
        "remote",
        "hybrid"
      ]
    },
    "success": true
  }
}
```

### 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.