Find or create user by phone number
Looks up a user by their phone number in D1. If none matches, creates the user in both D1 (read model) and the UserAggregate (event sourcing) — the same find-or-create behaviour as /users/by-email — storing the phone number on the new D1 row. A user can have a phone number, an email, or both: pass email to also record one. Idempotent.
curl -X GET "https://api.spkey.co/users/by-phone?phoneNumber=%2B1-555-0123&email=user%40example.com&uuid=example_string" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN (JWT)" \
-H "X-API-Key: YOUR_API_KEY"
import requests
import json
url = "https://api.spkey.co/users/by-phone?phoneNumber=%2B1-555-0123&email=user%40example.com&uuid=example_string"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN (JWT)",
"X-API-Key": "YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
print(response.json())
const response = await fetch("https://api.spkey.co/users/by-phone?phoneNumber=%2B1-555-0123&email=user%40example.com&uuid=example_string", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN (JWT)",
"X-API-Key": "YOUR_API_KEY"
}
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://api.spkey.co/users/by-phone?phoneNumber=%2B1-555-0123&email=user%40example.com&uuid=example_string", nil)
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN (JWT)")
req.Header.Set("X-API-Key", "YOUR_API_KEY")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
require 'net/http'
require 'json'
uri = URI('https://api.spkey.co/users/by-phone?phoneNumber=%2B1-555-0123&email=user%40example.com&uuid=example_string')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer YOUR_API_TOKEN (JWT)'
request['X-API-Key'] = 'YOUR_API_KEY'
response = http.request(request)
puts response.body
{
"uuid": "example_string",
"email": "null",
"phoneNumber": "null",
"created_at": "example_string"
}
{
"error": "Conflict",
"message": "The request conflicts with the current state of the resource",
"code": 409,
"details": "Resource already exists"
}
{
"error": "Internal Server Error",
"message": "An unexpected error occurred on the server",
"code": 500,
"requestId": "req_1234567890"
}
{
"error": "Service Unavailable",
"message": "The service is temporarily unavailable. Please try again later",
"code": 503
}
/users/by-phone
Target server for requests. Edit to use your own host.
JWT token from SmartphoneKey authentication. Identifies the B2C user or B2B service.
API key for B2B organization access. Provided during organization onboarding.
Phone number to look up (exact match)
Optional email to also set on the user when one is created. A user can have a phone number, an email, or both — omitting this still creates a phone-only user on a miss.
Optional UUID to assign when creating a new user (must not already exist)
Request Preview
Response
Response will appear here after sending the request
Authentication
Bearer token (JWT). JWT token from SmartphoneKey authentication. Identifies the B2C user or B2B service.
API Key for authentication. API key for B2B organization access. Provided during organization onboarding.
Query Parameters
Phone number to look up (exact match)
Optional email to also set on the user when one is created. A user can have a phone number, an email, or both — omitting this still creates a phone-only user on a miss.
Optional UUID to assign when creating a new user (must not already exist)