---
title: "Request Goal Phone Code"
method: POST
path: "/goals/phone/code"
tags: ["goals"]
---

# Request Goal Phone Code

`POST /goals/phone/code`

Text a one-time code to the phone the athlete typed, so they can prove
they hold it before we ever schedule a message to it.

Unsafe on purpose: this triggers an outbound text to a number the request
names, which is exactly the kind of thing a cross-site page must not be
able to do with someone else's cookie. The store owns all three budgets
(per session, per requester — the stable abuse material a fresh cookie
cannot reset — and per receiving phone); a refused mint sends nothing,
and the 429 says when asking again can work. Asking again inside the
budget replaces the pending code — that one path is "Resend code" and
"wrong number, let me fix it" both — and a re-ask within the store's
cooldown returns the SAME code under the same outbox dedupe key, which is
what makes retrying this route after a failed enqueue safe and free.

The phone never lands in telemetry; the session id is the trace key.

## Request body

- GoalPhoneCodeRequest — The phone the athlete typed, asking for its one-time code.
  - `phone` string, required
  - `locale` string, nullable

## Response `200`

Successful Response

- GoalPhoneCodeResponse — The code text is queued; ``expires_at`` bounds how long typing it works.
  - `status` 'sent'
  - `expires_at` string, date-time, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-02** `55d56c4beab4` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/imperfect/apis/imperfect-api/changes/goals/phone/code/post.md)

---

[API](https://skmtc.dev/imperfect/apis/imperfect-api.md) · [All operations](https://skmtc.dev/imperfect/apis/imperfect-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/imperfect/imperfect-api/revisions/55d56c4beab4/schema)