> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# X Account Email Verification API & Login Challenges

> Submit an email verification code for an active X account login challenge. Start a fresh connect or reauthentication when it expires. See request fields.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="201" id="response-x-accounts-submit-challenge-201">
      ```json theme={null}
      {
        "id": "42",
        "xUserId": "9876543210",
        "xUsername": "elonmusk",
        "status": "active",
        "health": "healthy",
        "createdAt": "2025-01-15T12:00:00Z"
      }
      ```
    </Tab>

    <Tab title="202" id="response-x-accounts-submit-challenge-202">
      ```json theme={null}
      {
        "object": "x_account_connection_challenge",
        "id": "xch_8vGd8Y9JvH6dV0xA",
        "status": "requires_email_code",
        "expiresAt": "2026-05-08T12:10:00Z",
        "message": "Enter the email verification code to continue.",
        "username": "elonmusk"
      }
      ```
    </Tab>

    <Tab title="400" id="response-x-accounts-submit-challenge-400">
      ```json theme={null}
      {
        "error": "invalid_input",
        "message": "Invalid input. Check the request body."
      }
      ```
    </Tab>

    <Tab title="401" id="response-x-accounts-submit-challenge-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required. Provide a valid API key or bearer token."
      }
      ```
    </Tab>

    <Tab title="404" id="response-x-accounts-submit-challenge-404">
      ```json theme={null}
      {
        "error": "not_found",
        "message": "Resource not found."
      }
      ```
    </Tab>

    <Tab title="409" id="response-x-accounts-submit-challenge-409">
      ```json theme={null}
      {
        "error": "connection_challenge_inactive",
        "message": "Connection challenge is no longer active."
      }
      ```
    </Tab>

    <Tab title="410" id="response-x-accounts-submit-challenge-410">
      ```json theme={null}
      {
        "error": "connection_challenge_expired",
        "message": "Verification code expired. Start again."
      }
      ```
    </Tab>

    <Tab title="422" id="response-x-accounts-submit-challenge-422">
      ```json theme={null}
      {
        "error": "login_failed",
        "message": "Login failed. Check credentials and try again."
      }
      ```
    </Tab>

    <Tab title="429" id="response-x-accounts-submit-challenge-429">
      ```json theme={null}
      {
        "error": "rate_limit_exceeded",
        "message": "Too many requests. Try again later.",
        "retryAfter": 60
      }
      ```
    </Tab>

    <Tab title="503" id="response-x-accounts-submit-challenge-503">
      ```json theme={null}
      {
        "error": "service_unavailable",
        "message": "Service temporarily unavailable. Try again later."
      }
      ```
    </Tab>
  </Tabs>
</Panel>

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

<Callout icon="circle-check" color="#16a34a">
  **Free** - does not consume credits
</Callout>

Use this endpoint after [Connect X Account](/api-reference/x-accounts/connect) returns `202 Email Code Required`. Submit the one-time code from the account email inbox before `expiresAt` while the challenge is still active.

<Warning>
  This endpoint cannot reopen an expired, failed, completed, or replaced challenge. After `409`, `410`, or `422`, start [Connect X Account](/api-reference/x-accounts/connect) again for a new account. For an existing account, use [Re-authenticate X Account](/api-reference/x-accounts/reauth) with the current password and any required TOTP secret key.
</Warning>

## Continue the pending login

<CardGroup cols={1}>
  <Card title="Use the returned challenge ID" icon="ticket-check">
    Keep the `id` from the `202` response and submit the inbox code to that challenge. The challenge belongs to the same pending login attempt.
  </Card>

  <Card title="Enter the account email code" icon="mail-check">
    Use the one-time code X sent to the account email inbox. Xquik strips spaces before submission, so `123 456` and `123456` are handled the same way.
  </Card>

  <Card title="Handle another code prompt" icon="refresh-cw">
    If X asks for a new email code, this endpoint returns `202` again. Keep the same flow open and submit the next inbox code before `expiresAt`.
  </Card>

  <Card title="Start over when stale" icon="timer-reset">
    `410` means the code expired. `409` means the challenge was already completed, failed, expired, or replaced. Start [Connect X Account](/api-reference/x-accounts/connect) again for a new account, or use [Re-authenticate X Account](/api-reference/x-accounts/reauth) for an existing account.
  </Card>
</CardGroup>

The dashboard follows the same flow: it keeps the pending row open, asks for the email code, accepts a new `202` prompt if X asks again, and refreshes the account list after the `201` response.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://xquik.com/api/v1/x/account-connection-challenges/xch_8vGd8Y9JvH6dV0xA/submit \
    -H "x-api-key: xq_YOUR_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{ "email_code": "123456" }' | jq
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://xquik.com/api/v1/x/account-connection-challenges/xch_8vGd8Y9JvH6dV0xA/submit",
    {
      method: "POST",
      headers: {
        "x-api-key": "xq_YOUR_KEY_HERE",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email_code: "123456" }),
    },
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://xquik.com/api/v1/x/account-connection-challenges/xch_8vGd8Y9JvH6dV0xA/submit",
      headers={"x-api-key": "xq_YOUR_KEY_HERE"},
      json={"email_code": "123456"},
  )
  data = response.json()
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      body, _ := json.Marshal(map[string]string{
          "email_code": "123456",
      })

      req, err := http.NewRequest(
          "POST",
          "https://xquik.com/api/v1/x/account-connection-challenges/xch_8vGd8Y9JvH6dV0xA/submit",
          bytes.NewReader(body),
      )
      if err != nil {
          panic(err)
      }
      req.Header.Set("x-api-key", "xq_YOUR_KEY_HERE")
      req.Header.Set("Content-Type", "application/json")

      resp, err := http.DefaultClient.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      var data map[string]interface{}
      if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
          panic(err)
      }
      fmt.Println(data)
  }
  ```
</CodeGroup>

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key. Session cookie authentication is also supported. Generate a key from the [dashboard](https://xquik.com/dashboard).
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
  Challenge ID returned by [Connect X Account](/api-reference/x-accounts/connect).
</ParamField>

## Body

<ParamField body="email_code" type="string" required>
  Email verification code for the pending connection. Codes from 4 to 64 characters are accepted. Spaces are stripped before submission.
</ParamField>

## Response

### 201 Created

<ResponseField name="id" type="string">Unique account ID.</ResponseField>
<ResponseField name="xUsername" type="string">Connected X username.</ResponseField>
<ResponseField name="xUserId" type="string">X user ID.</ResponseField>
<ResponseField name="status" type="string">Account connection status (e.g. `"active"`).</ResponseField>
<ResponseField name="health" type="string">Derived login/cookie health. One of `healthy`, `locked`, `needsReauth`, `recovering`, `suspended`, `temporaryIssue`. See [Account health](/api-reference/x-accounts/list#account-health) for meanings.</ResponseField>
<ResponseField name="createdAt" type="string">ISO 8601 timestamp of when the account was connected.</ResponseField>

```json theme={null}
{
  "id": "3",
  "xUsername": "elonmusk",
  "xUserId": "44196397",
  "status": "active",
  "health": "healthy",
  "createdAt": "2026-02-20T08:15:00.000Z"
}
```

### 202 Email Code Required

<ResponseField name="object" type="string">Always `x_account_connection_challenge`.</ResponseField>
<ResponseField name="id" type="string">Challenge ID to submit with the next email verification code.</ResponseField>
<ResponseField name="status" type="string">Always `requires_email_code`.</ResponseField>
<ResponseField name="expiresAt" type="string">ISO 8601 expiration time for the challenge.</ResponseField>
<ResponseField name="message" type="string">Human-readable next step.</ResponseField>
<ResponseField name="username" type="string">X username being connected.</ResponseField>

```json theme={null}
{
  "object": "x_account_connection_challenge",
  "id": "xch_8vGd8Y9JvH6dV0xA",
  "status": "requires_email_code",
  "expiresAt": "2026-05-08T12:10:00Z",
  "message": "Enter the email verification code to continue.",
  "username": "elonmusk"
}
```

The connection still needs a valid email code. Submit the new code to the same endpoint.

### 400 Invalid Input

```json theme={null}
{ "error": "invalid_input", "message": "Invalid input. Check the request body." }
```

Missing `email_code`, invalid JSON, or a code outside the accepted length.

### 401 Unauthenticated

```json theme={null}
{ "error": "unauthenticated", "message": "Missing or invalid API key" }
```

Missing or invalid API key.

### 404 Not Found

```json theme={null}
{ "error": "connection_challenge_not_found", "message": "Connection challenge not found." }
```

The challenge ID does not exist or does not belong to the authenticated user.

### 409 Conflict

```json theme={null}
{ "error": "connection_challenge_inactive", "message": "Connection challenge is no longer active." }
```

The challenge was already completed, failed, expired, or replaced.

### 410 Expired

```json theme={null}
{ "error": "connection_challenge_expired", "message": "Verification code expired. Start again." }
```

Start a new account connection to receive a fresh challenge.

### 422 Login Failed

```json theme={null}
{ "error": "login_failed", "message": "Login failed. Check credentials and try again." }
```

The code or account login state was rejected. Start a new connection if the account requires fresh credentials.

### 429 Rate Limit Exceeded

```json theme={null}
{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }
```

Wait for the `Retry-After` header before retrying.

### 503 Service Unavailable

```json theme={null}
{ "error": "service_unavailable", "message": "Service temporarily unavailable. Try again later." }
```

Retry after a short delay.

<Note>
  **Related:** [Connect X Account](/api-reference/x-accounts/connect) starts the challenge, and [List X Accounts](/api-reference/x-accounts/list) verifies the account after connection.
</Note>