Skip to Content

Application states

Every state an application started by API can be in, what each one means for you, and which webhook event fires.

POST /developer/apply, GET /developer/applications/{id} and GET /developer/applications answer with a status. It is one of six states. Reads are free and work with any key.

The states

statusWhat it meansWhat to do
in_progressGetMattered is preparing or sending it, or it was sent and the employer has not confirmed it yet.Wait. Poll every few minutes, or listen for a webhook.
held_for_reviewIt is ready and waits for the account owner to approve it.The owner approves it in GetMattered. A key with the apply scope can approve or cancel it by API.
needs_youIt waits on the account owner for something else, such as a detail only they can give.Ask the owner to open trackingUrl in GetMattered.
landedThe employer confirmed it. landedEvidence says how.Nothing. The application is done.
heldIt stopped, and a mail may be the employer's answer, so GetMattered will not send it again.Do not retry. Calling apply again does not send it.
not_landedIt stopped without the employer confirming it.Call POST /developer/apply for the same posting to send it again.

Landed needs the employer's proof

An application reads landed only on proof from the employer. landedEvidence lists it:

EvidenceWhat it is
receiptThe employer's confirmation email.
screenshotThe employer's confirmation page, captured after the send.

A click, a sent form or our own status never counts as landed. The proof can come well after the send, so an application can stay in_progress for a while. Once the proof arrives, the application reads landed, whatever state it was in before.

Stopped applications

held and not_landed both mean GetMattered stopped. They differ in what a retry does:

  • not_landed: POST /developer/apply for the same posting starts it again.
  • held: GetMattered will not send it again. A mail arrived that may be the employer's answer.

An application the owner cancelled reads not_landed, and apply does not send it again.

Webhook events

A webhook endpoint gets one event each time an application enters one of four states:

statusEvent
in_progressnone
held_for_reviewapplication.held_for_review
needs_youapplication.needs_you
landedapplication.landed
heldnone
not_landedapplication.not_landed

Events usually arrive within two minutes. in_progress and held send no event, so read them with GET /developer/applications/{id}. An application can enter the same state twice, for example needs_you again after the owner answered once. Each entry sends a new event. See Receive webhooks.

Filter by state

GET /developer/applications takes a status query with one of these states. It answers only the applications in that state, newest first. See List applications.

On this page