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
status | What it means | What to do |
|---|---|---|
in_progress | GetMattered 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_review | It 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_you | It waits on the account owner for something else, such as a detail only they can give. | Ask the owner to open trackingUrl in GetMattered. |
landed | The employer confirmed it. landedEvidence says how. | Nothing. The application is done. |
held | It 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_landed | It 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:
| Evidence | What it is |
|---|---|
receipt | The employer's confirmation email. |
screenshot | The 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/applyfor 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:
status | Event |
|---|---|
in_progress | none |
held_for_review | application.held_for_review |
needs_you | application.needs_you |
landed | application.landed |
held | none |
not_landed | application.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.