Changelog
Start typing to search…
Back to All
Added

Added POST endpoint to create application status changes

April 2nd, 2026

POST /api/v1/application_status_changes

You can now change an application's status via the API by sending a POST request to /api/v1/application_status_changes.

Request

Send a JSON:API-style body with:

  • Required

    • Application: data.attributes["application-id"] (or application_id) — the application whose status to change.
    • Status: data.attributes["status"] — the target status (e.g. "withdrawn", "recruiting", "approved").

  • Optional (required for some statuses; see the API guide):

    • status-date — date of the status change (ISO 8601).
    • status-reason, status-explanation
    • date-application-started, not-signed
    • overridden-reason, overridden-explanation (when the caller has override permission)
    • next-renewal-due-date, selected-renewal-template-lineage-slug
    • notification-date, appeal-location, contact-method

Validation: The request body is validated against allowed values. Invalid values yield 422 with errors (each error has source.pointer under /data/attributes/...). Rules:

  • status — must be one of the application status enum values (e.g. "withdrawn", "recruiting", "approved", "closed", "denied").
  • status-reason, overridden-reason, appeal-location, contact-method — when present, must be from their respective allowed lists.
  • status-date, date-application-started, next-renewal-due-date, notification-date — when present, must be ISO 8601 date strings.
  • date-application-started and not-signed — must not both be present in the same request. If you send both, the API returns 422 with a schema validation error whose detail explains that both fields were included and only one is allowed (e.g. "You included both date-application-started and not-signed, which is not allowed. Send only one.").

Renewal fields (conditional)

Renewal-related attributes are conditionally accepted. The API returns 422 with a clear error when they are sent in the wrong context:

  • next-renewal-due-date — Only allowed when changing a renewal application to approved. If you send it when changing an initial application to approved, or when changing to any other status, the API returns 422 with an error pointing at next-renewal-due-date.
  • selected-renewal-template-lineage-slug — Only allowed when changing status to approved and when the agency has renewal template selection enabled with more than one available renewal template lineage. If you send it when status is not approved, or when the agency does not have renewal template selection or has only one or zero options, the API returns 422 with an error pointing at selected-renewal-template-lineage-slug. If you send a slug that does not match a renewal template lineage for the agency, or that is not in the application's available list, the API returns 422.

Send selected-renewal-template-lineage-slug (string) — the slug of the desired renewal template lineage for the application's agency — not an integer ID. If omitted, the current template lineage is left unchanged. These two fields are independent: you can send one, the other, or both when their respective conditions are met.

Response

  • 201 Created: The new application status change record is returned (same shape as GET /api/v1/application_status_changes/:id), with a Location header pointing to that resource.

  • 422 Unprocessable Entity: One or more validations failed. The response body is a JSON:API errors array. 422 responses include a top-level meta object with current_api_user_can_override (boolean), indicating whether the current API user has permission to override validation blockers. Errors can come from:

    • The application (e.g. invalid status, missing required reason or date),
    • The applicant user or applicant agency profile (e.g. incomplete data for approval),
    • Or a list of blocking messages (e.g. incomplete requirements).
      Error source.pointer values indicate the attribute or context (e.g. /data/attributes/status, /data/attributes/user, /data/attributes/applicant-agency-profile, /data/attributes/base).

    Enriched error metadata (422 only): Each error object may include a meta object with:

    • type — string identifying the error category (e.g. incomplete_applicant_data, incomplete_documents, incomplete_background_checks), so clients can group or prioritize.
    • link — URL where the issue can be addressed (when applicable).
    • overridable — boolean indicating whether this error can be bypassed by retrying the request with overridden-reason and overridden-explanation.

    Some schema validation errors (e.g. sending both date-application-started and not-signed) return a human-readable detail in the errors array to help correct the request.

  • 403 Forbidden: The authenticated user is not allowed to change this application's status to the requested status.

  • 404 Not Found: The application id was not found or is not visible to the caller.

Notes

  • Changing an application's status is not supported on PUT /api/v1/applications/:id. Use this POST endpoint instead.
  • Required fields (e.g. status-reason, status-explanation, status-date) depend on the target status; see the API guide for details.
  • API users do not automatically have permission to override validation blockers. They can override only when they have been granted that access (same process as for the UI). See the Application Status Changes API guide for how to get override access.