Retrieve a user

Look up a user by user_id or by email. Scoped to the authenticated organization.

Retrieves a user by either their user_id or their email. Pass exactly one — passing both or neither returns a 422 validation error.

The user must be linked to your organization. A user that exists in another org but not yours returns 404 not found — preventing cross-org existence checks.

Endpoint

POST https://api.productbridge.io/api/external/v1/users/retrieve

Arguments

body

api_keystring

Required

Your organization's public API key. See Authentication.

body

user_idstring

Look up the user by their UUID. Mutually exclusive with email.

body

emailstring

Look up the user by their email address. Case-sensitive. Mutually exclusive with user_id.

Exactly one of user_id or email is required. The endpoint returns 422 if both are provided or neither is provided.

Returns

A user object on success, or a 404 error envelope when the user isn't linked to this organization.

Example request

# By email
curl -X POST https://api.productbridge.io/api/external/v1/users/retrieve \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "pb_YOUR_PUBLIC_API_KEY",
    "email":  "sally@acme.example.com"
  }'

# By user_id
curl -X POST https://api.productbridge.io/api/external/v1/users/retrieve \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "pb_YOUR_PUBLIC_API_KEY",
    "user_id": "bb3c3ef8-b8cd-cd15-01ba-useruser0001"
  }'

const res = await fetch(
  "https://api.productbridge.io/api/external/v1/users/retrieve",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: process.env.PRODUCTBRIDGE_API_KEY,
      email: "sally@acme.example.com",
    }),
  }
);
if (res.status === 404) throw new Error("User not in this org");
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const user = await res.json();

import os, httpx

resp = httpx.post(
    "https://api.productbridge.io/api/external/v1/users/retrieve",
    json={
        "api_key": os.environ["PRODUCTBRIDGE_API_KEY"],
        "email": "sally@acme.example.com",
    },
)
if resp.status_code == 404:
    raise LookupError("User not in this org")
resp.raise_for_status()
user = resp.json()

Example response

{
  "id":   "ff3c3ef8-b8cd-cd15-01ba-orguser000001",
  "user_id": "bb3c3ef8-b8cd-cd15-01ba-useruser0001",
  "email": "sally@acme.example.com",
  "name":  "Sally Doe",
  "avatar_url": "https://acme.example.com/avatars/sally.png",
  "portal_role": "end_user",
  "company_name": "Acme Inc",
  "customer_status": "paying",
  "created_at": "2026-04-01T08:00:00.000Z"
}

Errors

Status	Body	Cause
`401`	`{"detail":{"error":"invalid api_key"}}`	Missing / unknown / inactive `api_key`.
`404`	`{"detail":{"error":"user not found"}}`	The user exists but is not linked to your organization, or doesn't exist at all.
`422`	Validation error envelope	Both `user_id` and `email` supplied, or neither, or invalid types.

See Errors for the full envelope shape.

Was this page helpful?

Last updated 2 weeks ago

Built with Documentation.AI