Find (or create) user by phone number
Looks up a user by their phone number in D1. By default, 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. Pass searchOnly=true to look up ONLY: a miss then answers 404 and nothing is created.
curl -X GET "https://api.spkey.co/users/by-phone?phoneNumber=%2B1-555-0123&email=user%40example.com&uuid=example_string&searchOnly=true" \
-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&searchOnly=true"
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&searchOnly=true", {
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&searchOnly=true", 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&searchOnly=true')
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": "Bad Request",
"message": "The request contains invalid parameters or malformed data",
"code": 400,
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
{
"error": "Not Found",
"message": "The requested resource was not found",
"code": 404
}
{
"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, in international form. "+48123456789", "+48 123 456 789" and "0048123456789" all resolve to the same user; a number without a leading "+" or "00" is rejected.
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)
When true, only look the user up — do not create one on a miss (404 instead). Defaults to false, which keeps the existing find-or-create behaviour.
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, in international form. "+48123456789", "+48 123 456 789" and "0048123456789" all resolve to the same user; a number without a leading "+" or "00" is rejected.
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)
When true, only look the user up — do not create one on a miss (404 instead). Defaults to false, which keeps the existing find-or-create behaviour.
truefalse