Confirm a verification code

POSThttps://sandbox-api.tryflume.ai/partner/v1/users/confirm-verificationCopy

RequestReturnsErrors

Confirms the code a user typed and returns their user access token.

• Flume opens a Flume account for the user, or links the one their email already has.
• access_token is returned once and has no expiry. Store it as a secret, against the user.
• Three wrong tries burn the code. After that, or after 10 minutes, send a new one.
• Confirming again issues a new token and stops the old one.

Guide: Verify a user

curl

curl -X POST "https://sandbox-api.tryflume.ai/partner/v1/users/confirm-verification" \
  -H "X-Flume-Partner-Key: $FLUME_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "sarah.chen@example.com",
  "code": "482913"
}'

Python

import os

import requests

headers = {
    "X-Flume-Partner-Key": os.environ["FLUME_PARTNER_KEY"],
}

response = requests.post(
    "https://sandbox-api.tryflume.ai/partner/v1/users/confirm-verification",
    headers=headers,
    json={
        "email": "sarah.chen@example.com",
        "code": "482913",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://sandbox-api.tryflume.ai/partner/v1/users/confirm-verification", {
  method: "POST",
  headers: {
    "X-Flume-Partner-Key": process.env.FLUME_PARTNER_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "sarah.chen@example.com",
    "code": "482913"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

Response: 200

{
  "external_ref": "u_8812",
  "email": "sarah.chen@example.com",
  "access_token": "ut_dev_acme_example_token",
  "token_type": "user_token",
  "verified_at": "2026-10-16T09:02:11Z",
  "account": "CREATED"
}

Request

Headers

Header	Required	Description
X-Flume-Partner-Key	Yes	Your partner key. See Authentication and keys.

Body

Send application/json. A field the API does not list returns a 422 that names it.

• methodenumOptional

  The method used to send the code. email_code is the only method today.

  • Default "email_code"
• emailstringRequired

  The address the code was sent to.

  • Max 320 characters
  • Pattern ^[^@\s]+@[^@\s]+\.[^@\s]+$
• codestringRequired

  The 6 digits from the email.

  • 6 digits
• external_refstring or nullOptional

  Your id for the user. Needed only when two of your users share one email.

  • Max 128 characters

Returns

200 with these fields. Every field is always present. A field with no value is null.

• external_refstring

  Your id for the user. Check that it is the user you expect before you store the token.

• emailstring

  The verified address.

• access_tokenstring

  The user access token. Returned once. Flume keeps only a hash of it.

• token_typestring

  Always user_token.

  • Always "user_token"
  • Default "user_token"
• verified_atstring

  When the user verified their email, in UTC.

• accountenum

  CREATED: Flume opened a new Flume account with the details you sent. LINKED: the email already had a Flume account, and Flume linked it unchanged.

Errors

Every error uses one envelope. Branch on error.code.

Status	Code	Meaning
401	EMBED_TOKEN_INVALID	You sent an Authorization header and no X-Flume-Partner-Key. Flume read the call as one from its own iframe.
401	PARTNER_KEY_INVALID	The partner key is missing, unknown, revoked, expired, or from the other environment. On live, also a platform Flume has not enabled yet.
401	USER_TOKEN_INVALID	The user access token is unknown, revoked, another partner's, or replaced by a later verification. A verification in the iframe replaces it too.
404	NOT_FOUND	The thing does not exist, or is not this user's. A search id that is not a UUID also returns this code.
422	USER_ACCOUNT_CLOSED	The user's email belongs to a Flume account that Flume has closed.
422	VALIDATION_FAILED	A field is missing, unknown or has an unusable value. field names it as a dotted path. Some refusals carry the detail in details and leave field empty.
422	VERIFICATION_CODE_EXPIRED	No code is valid: it is older than 10 minutes, already used, or was never sent.
422	VERIFICATION_CODE_INVALID	The code is wrong. The message says how many tries are left.
422	VERIFICATION_TRIES_EXHAUSTED	The code was wrong 3 times. It is burned.
500	INTERNAL	Something failed on Flume's side.