curl --request POST \
--url https://web-api.dev.soxai.site/api/users/sn \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
[
{
"uid": "user_123",
"email": "developer@example.com"
}
]
'import requests
url = "https://web-api.dev.soxai.site/api/users/sn"
payload = [
{
"uid": "user_123",
"email": "developer@example.com"
}
]
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify([{uid: 'user_123', email: 'developer@example.com'}])
};
fetch('https://web-api.dev.soxai.site/api/users/sn', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"uid": "user123",
"email": "member@example.com",
"sn": [
"sn_0123456789"
],
"message": "success"
}{
"error": "bad-request",
"error_msg": "Too many items. Maximum allowed is 200."
}{
"error": "http-error",
"error_msg": "Invalid authentication credentials. <reason>"
}{
"error": "forbidden",
"error_msg": "Not enough permission"
}{
"error": "not-found",
"error_msg": "User '<uid>' not found"
}{
"error": "unprocessable-entity",
"error_msg": "body.<field>: <validation message>"
}{
"error": "rate-limited",
"error_msg": "Rate limit exceeded. Retry after <n> seconds."
}{
"error": "internal-server-error",
"error_msg": "Failed to fetch data: <error_message>"
}Look up a user's ring serial numbers
A request authenticated with a Sandbox soxai-api-key is answered 403 This endpoint is not available in the sandbox., because it changes state that every Sandbox caller shares. It is published here because the Sandbox runs the same build; use it in Production. See Sandbox.
Look up the ring serial number(s) for a user identified by uid or email.
Accepts a single lookup object, or a list of at most 200 for batch lookups. In batch mode, per-item errors are returned inline (soft failure).
Scope: a PartnerAdmin or OrgAdmin queries only users within its own reach. For
them a target that does not exist is refused exactly like a target outside their scope,
so the endpoint cannot be used to test whether an address or uid is registered. Which
roles are accepted is stated once, in the Authorization block below.
Absence: 404 when an email resolves to no account, or when a uid has neither an account nor an SN record in any source. A uid whose Auth account is gone but whose SN records remain is answered normally. In batch mode these become inline per-item errors carrying status_code, and the response stays 200.
Lookup key (exactly one per item):
- uid: Firebase user ID.
- email: resolved via Firebase Authentication.
SN sources (checked in order, results merged and deduplicated):
ring_identify_infocollection — ring_uuid in sn_ format yields SN; MAC address returned as-is.warrantycollection — sn_list field from document keyed by uid.system_info/user_info/usersubcollection — SN field.{uid}/user_profiledocument — SN field.
Parameters
- Body: a single lookup object, or a list of at most 200. Each item carries exactly one
of
uidoremail.
Response
200for a single item returns that user’s uid and the serial numbers found for them, merged and deduplicated across the four sources listed above.200for a list returns one entry per item, in the order they were sent. A per-item failure is inline: that entry carrieserrorandstatus_code, and the response is still200.
Errors
| Status | Condition |
|---|---|
| 400 | The list holds more than 200 items |
| 404 | The item names nobody, or names somebody outside the caller’s reach - the two are answered the same way. Only the single-item form answers this; in the list form it is folded into that item |
Authorization
- Scheme:
Authorization: Bearer <idToken>orsoxai-api-key: <api key>. - Accepted roles:
Admin,PartnerAdmin,OrgAdmin - Any other caller receives
403 Not enough permission.
curl --request POST \
--url https://web-api.dev.soxai.site/api/users/sn \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
[
{
"uid": "user_123",
"email": "developer@example.com"
}
]
'import requests
url = "https://web-api.dev.soxai.site/api/users/sn"
payload = [
{
"uid": "user_123",
"email": "developer@example.com"
}
]
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify([{uid: 'user_123', email: 'developer@example.com'}])
};
fetch('https://web-api.dev.soxai.site/api/users/sn', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"uid": "user123",
"email": "member@example.com",
"sn": [
"sn_0123456789"
],
"message": "success"
}{
"error": "bad-request",
"error_msg": "Too many items. Maximum allowed is 200."
}{
"error": "http-error",
"error_msg": "Invalid authentication credentials. <reason>"
}{
"error": "forbidden",
"error_msg": "Not enough permission"
}{
"error": "not-found",
"error_msg": "User '<uid>' not found"
}{
"error": "unprocessable-entity",
"error_msg": "body.<field>: <validation message>"
}{
"error": "rate-limited",
"error_msg": "Rate limit exceeded. Retry after <n> seconds."
}{
"error": "internal-server-error",
"error_msg": "Failed to fetch data: <error_message>"
}Authorizations
Body
Response
The serial numbers on file, merged and deduplicated across the four sources. The list form answers one entry per item in the order sent, and a per-item failure stays inline as error plus status_code rather than failing the batch.