# Apply to a job posting (/docs/reference/apply)

`POST https://api.getmattered.com/api/v1/developer/apply`

Needs a key made with the `apply` scope. Applies to one job posting for the key owner's own account, the way GetMattered applies from the app: it resolves the link to the employer's posting, prepares the application and sends it, or holds it for the owner's approval. Answers at once; read the outcome from `GET /developer/applications/{id}`. The same posting twice answers with the same application. A stopped application starts again, except one `held` or one the owner cancelled. It spends the API balance, never the app plan, and needs 40,000 API tokens there for each application in progress plus this one to start; a running application finishes even if it takes the balance below zero, and the next call is refused until a top-up. At most 5 applications started by API are in progress at once, and an account reads at most 5 postings a minute across its keys. Spends the tokens the application uses plus the request fee, recorded as `apply`. A call refused before the posting is read spends nothing; once the posting is read, the call pays the request fee whatever it answers.

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

## Request body (application/json)

```json
{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "auto",
        "review"
      ],
      "description": "`auto` sends once the application is ready. `review` holds it for the account owner to approve in GetMattered. Omitted, the account's own setting decides, and `auto` never overrides an account set to review.",
      "example": "auto"
    },
    "postingUrl": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri",
      "description": "The job posting to apply to: the employer's own posting, or a job-board link to it. GetMattered applies only on the hiring systems it supports.",
      "example": "https://job-boards.greenhouse.io/acme/jobs/4012345"
    }
  },
  "required": [
    "postingUrl"
  ],
  "additionalProperties": false
}
```

## Responses

### 202: The application, started now or found from an earlier call.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "description": "The application. The same posting always answers with the same id.",
          "example": 2481
        },
        "status": {
          "type": "string",
          "enum": [
            "in_progress",
            "held_for_review",
            "needs_you",
            "landed",
            "held",
            "not_landed"
          ],
          "description": "`in_progress`: GetMattered is preparing or sending it, or it was sent and the employer has not confirmed it yet. `held_for_review`: ready, and waiting for the account owner to approve it in GetMattered. `needs_you`: waiting on the account owner for something else. `landed`: the employer confirmed it, by their own email or their confirmation page; `landedEvidence` says which. `held`: it stopped, and a mail may be the employer's answer, so GetMattered will not send it again; do not retry. `not_landed`: it stopped without the employer confirming it. Calling apply again for a stopped posting sends it again, except a `held` one or one the owner cancelled.",
          "example": "in_progress"
        },
        "trackingUrl": {
          "type": "string",
          "format": "uri",
          "description": "The application's page in GetMattered, behind the account owner's sign-in.",
          "example": "https://getmattered.com/dashboard/applications/2481"
        }
      },
      "required": [
        "id",
        "status",
        "trackingUrl"
      ],
      "additionalProperties": false
    },
    "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

### 402: The key owner's API balance cannot start an application. Nothing was sent.

### 403: The key lacks the `apply` scope its owner grants at creation. Nothing was sent.

### 404: Not Found

### 422: GetMattered cannot apply to this posting; `reason` says why. Nothing was sent; the request fee was spent.

### 429: Too Many Requests

### 500: Internal Server Error

### 503: Service Unavailable

Error responses use the envelope in /errors.md.