Dokumentation

SMS-verifierings-API för felai.se

Introduktion

felai.se tillhandahåller ett enkelt REST-API för att verifiera användares telefonnummer via SMS. Flödet är:

Du skapar en verifiering med ett POST-anrop.
Du visar den returnerade verify_url (eller QR-koden) för användaren.
Användaren skickar SMS-koden till det angivna numret.
Verifieringen markeras som verified och du får telefonnumret.

Verifierade nummer cachas i 90 dagar. Du kan slå upp ett nummer igen med GET /api/lookup/{phone} utan att skicka nytt SMS.

Autentisering

Alla API-anrop (utom webhook) kräver autentisering via en Bearer-token i Authorization-headern:

Authorization: Bearer DIN_API_NYCKEL

Hitta din API-nyckel på kontosidan. Anrop utan giltig token returnerar 401 Unauthorized.

Bas-URL

https://felai.se

Alla endpoint-sökvägar nedan är relativa till denna bas-URL.

POST /api/verify

Skapar en ny verifieringsbegäran.

POST /api/verify

Parametrar (JSON body)

Parameter	Typ	Krävs	Beskrivning
`name`	string	Krävs	Användarnamnet att koppla till verifieringen. Visas på verifieringssidan.
`phone`	string	Valfri	Förväntat telefonnummer (t.ex. `+46701234567`). Om utelämnat tas numret från inkommande SMS. Stöder format `07XXXXXXXX` (konverteras till `+46`).
`callback_url`	string	Valfri	URL som kallas med POST-anrop (JSON) när verifieringen lyckas.

cURL-exempel

Skapa verifiering cURL

curl -X POST https://felai.se/api/verify \
  -H "Authorization: Bearer DIN_API_NYCKEL" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Anna Svensson",
    "phone": "+46701234567",
    "callback_url": "https://din-app.se/webhook/verified"
  }'

Svar — 200 OK

Fält	Typ	Beskrivning
`id`	string	Unikt verifierings-ID (16 hex-tecken).
`status`	string	Alltid `"pending"` vid skapandet.
`verify_url`	string	URL att visa för användaren (eller generera QR-kod från).
`code`	string	SMS-koden som användaren ska skicka.
`sms_number`	string	Telefonnumret SMS:et ska skickas till.

Exempelsvar JSON

{
  "id": "a3f8c2d1e4b59f02",
  "status": "pending",
  "verify_url": "https://felai.se/verify/a3f8c2d1e4b59f02",
  "code": "KXMP4",
  "sms_number": "+46700123456"
}

GET /api/verify/{id}

Hämtar aktuell status för en verifiering.

GET /api/verify/{id}

cURL-exempel

Hämta status cURL

curl https://felai.se/api/verify/a3f8c2d1e4b59f02 \
  -H "Authorization: Bearer DIN_API_NYCKEL"

Svarsfält

Fält	Typ	Beskrivning
`id`	string	Verifierings-ID.
`status`	string	`"pending"` — väntar på SMS `"verified"` — verifieringen lyckades `"expired"` — koden gick ut (10 minuter)
`name`	string	Användarnamnet som angavs vid skapandet.
`phone`	string	Verifierat telefonnummer (tomt om ej verifierat).
`verified_at`	string / null	Tidsstämpel när verifieringen skedde (ISO 8601), eller `null`.

Polling: Det rekommenderas att polla var 2:a sekund under maximalt 15 minuter. Koden gäller i 10 minuter; därefter returneras "expired".

POST /sms/incoming

Denna endpoint kallas av 46elks när ett inkommande SMS tas emot på verifieringsnumret. Du behöver inte anropa denna endpoint själv.

POST /sms/incoming

46elks skickar form-kodad data (application/x-www-form-urlencoded). felai.se matchar koden mot pågående verifieringar och uppdaterar statusen.

Parametrar från 46elks

Parameter	Typ	Beskrivning
`from`	string	Avsändarens telefonnummer (t.ex. `+46701234567`).
`message`	string	SMS-texten — ska matcha den aktiva koden.
`to`	string	Verifieringsnumrets nummer.

GET /api/lookup/{phone}

Slår upp ett telefonnummer i cachen av verifierade nummer. Returnerar namn och verifieringstidpunkt om numret är cachat (inom 90 dagar).

GET /api/lookup/{phone}

Telefonnumret i URL:en kodas automatiskt (t.ex. %2B46701234567). Du kan också använda format 07XXXXXXXX — det konverteras till +46.

cURL-exempel

Slå upp telefonnummer cURL

curl "https://felai.se/api/lookup/%2B46701234567" \
  -H "Authorization: Bearer DIN_API_NYCKEL"

Svarsfält

Fält	Typ	Beskrivning
`phone`	string	Telefonnumret i E.164-format.
`name`	string	Senast använda användarnamnet för detta nummer.
`verified_at`	string	Tidsstämpel när verifieringen gjordes.
`expires_at`	string	När cache-posten upphör att gälla (90 dagar efter verifiering).

Exempelsvar JSON

{
  "phone": "+46701234567",
  "name": "Anna Svensson",
  "verified_at": "2026-03-15 14:22:05",
  "expires_at": "2026-06-13 14:22:05"
}

Komplett cURL-exempel

Skapa och polla verifiering cURL

# 1. Skapa verifiering
RESPONSE=$(curl -s -X POST https://felai.se/api/verify \
  -H "Authorization: Bearer DIN_API_NYCKEL" \
  -H "Content-Type: application/json" \
  -d '{"name": "Anna Svensson"}')

ID=$(echo $RESPONSE | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
echo "Verifierings-ID: $ID"

# 2. Polla status
curl -s "https://felai.se/api/verify/$ID" \
  -H "Authorization: Bearer DIN_API_NYCKEL"

Komplett Python-exempel

Flask-integration Python

import requests
import time

API_KEY = "DIN_API_NYCKEL"
BASE    = "https://felai.se"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type":  "application/json",
}

# Skapa en verifiering
resp = requests.post(f"{BASE}/api/verify",
    headers=HEADERS,
    json={"name": "Anna Svensson", "phone": "+46701234567"})
data = resp.json()

print(f"Visa denna URL: {data['verify_url']}")
vid = data["id"]

# Polla tills verifierad eller utgången
for _ in range(150):   # max 5 min
    time.sleep(2)
    status = requests.get(f"{BASE}/api/verify/{vid}", headers=HEADERS).json()
    if status["status"] == "verified":
        print(f"Verifierad! Telefon: {status['phone']}")
        break
    elif status["status"] == "expired":
        print("Verifieringen gick ut.")
        break
else:
    print("Timeout — ingen verifiering mottagen.")