---
title: "Send a code"
method: POST
path: "/api/v2/connect/start"
tags: ["Connect"]
---

# Send a code

`POST /api/v2/connect/start`

Sends a one-time code to the user by email or phone. Provide **exactly one** of `email` or `phone`. Codes are valid for 10 minutes.

If you've designed a connect email in your dashboard, we send that branded email; otherwise we send a default one.

## Request body

- object
  - `email` string, email — The user's email address. Provide this or `phone`, not both.
  - `phone` string — The user's phone number in E.164 format (e.g. `+15551234567`). Provide this or `email`, not both.
  - `external_user_id` string — Optional. Your own identifier for the user, stored on the attempt for your reference.

## Response `201`

The attempt. Pass its `id` back as `connect_id` when you verify.

- ConnectAttempt
  - `object` 'connect_attempt'
  - `id` string — The attempt id. Pass it back as `connect_id` when you verify.
  - `channel` 'email' | 'phone' — The channel the code was sent on.
  - `expires_at` string, date-time — When the attempt expires (ISO 8601). Codes are valid for 10 minutes.

## Other responses

- `400` — `invalid_request` — missing or both of `email` and `phone`. `invalid_phone` — the number isn't valid or supported. `client_credentials_required` — the token wasn't minted from client credentials.
- `401` — `unauthorized` — the platform access token is missing or expired. Exchange your client credentials for a fresh one.
- `502` — `auth_provider_error` — the code couldn't be sent. Try again.
- `503` — `auth_unavailable` — authentication is temporarily unavailable. Retry shortly.

---

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