Skip to main content

​
Maintenance Requests

Use POST /maintenance/requests to create a maintenance process targeted at a specific account. 
POST /maintenance/requests

​
When To Use It

Use this endpoint when you need account maintenance work such as profile editing. This is the recommended public maintenance entrypoint.

​
Current Supported Step

The current implementation supports one maintenance action:
  • edit_profile

​
Request Example

curl -X POST "$PHONEFARM_BASE_URL/maintenance/requests" \
  -H "Authorization: Bearer $PHONEFARM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "maint-2026-03-22-001",
    "account_id": "account_user095916355",
    "inputs": {
      "steps": [
        {
          "action": "edit_profile",
          "params": {
            "display_name": "weekday meals",
            "bio": "quick dinners and meal prep",
            "mutation_kind": "operator_requested",
            "randomized": false
          }
        }
      ],
      "metadata": {
        "source": "ugc-tracker"
      }
    },
    "callback": {
      "url": "https://ugc-tracker.example.com/phonefarm/process-updates",
      "metadata": {
        "environment": "production"
      }
    },
    "requested_by": {
      "system": "ugc-tracker",
      "user": "operator@example.com",
      "metadata": {}
    }
  }'

​
Accepted Response

{
  "status": "accepted",
  "process_id": "3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870",
  "request_id": "maint-2026-03-22-001",
  "process_type": "maintenance"
}

​
Request Fields

FieldTypeRequiredNotes
request_idstringyesCaller-generated idempotency key component.
account_idstringyesTarget account id. Must resolve to an active account.
inputsobjectyesContains steps and optional metadata.
callbackobjectyesCallback destination and metadata.
requested_byobjectyesCaller identity.

​
inputs.steps[]

FieldTypeRequiredNotes
actionstringyesMust currently be edit_profile.
paramsobjectyesAt least one supported profile field is required.
Supported edit_profile.params fields:
  • display_name
  • bio
  • username
  • mutation_kind
  • randomized
At least one of display_name, bio, or username must be present.

​
Idempotency

Idempotency key: 
(process_type, requested_by.system, request_id)
Duplicate requests return the existing process.

​
Advanced Compatibility Note

The lower-level capability contract also knows about a maintenance capability. Public docs treat POST /maintenance/requests as the canonical maintenance route.

​
Failure Modes

Status codeMeaning
401Missing or invalid bearer token.
404Account not found or inactive.
422Invalid request structure or unsupported step payload.
500Unexpected enqueue failure.