Profiles API

The Profiles API returns one customer profile, looked up by the userId that you send to the Identify API. Use it to confirm what JustAI saved after an Identify call, and to check that your credentials work.

Endpoint

GET https://ingest.justwords.ai/api/profiles/{org_slug}/{user_id}
X-Api-Key: YOUR_API_KEY

The request has no body. It uses the same API key, organization slug, and environment rules as the Identify and Track APIs.

Header	Required	Value
X-Api-Key	Yes, or send the key in Authorization	Your JustAI API key. Authorization: Bearer and HTTP Basic also work. See Authentication.
X-JustAI-Environment	Non-production environments only	The environment key, for example staging. Leave it out for Production. See Environments.

Encode the user ID

URL-encode the user ID before you put it in the path. In JavaScript, use encodeURIComponent(userId). In Python, use urllib.parse.quote(user_id, safe="").

User ID	Path segment
user-1234	user-1234
ada@example.com	ada%40example.com
team/user-1234	team%2Fuser-1234

• JustAI looks up profiles by user ID only. You cannot look up a profile by email address.
• Identify removes leading and trailing spaces from userId before it saves the profile. Read the profile with the trimmed ID.
• An empty user ID, as in /api/profiles/{org_slug}/, returns 404 with the plain-text body 404 Not Found.

Response fields

A successful read returns 200 with this JSON object:

Field	Type	Description
org_slug	string	The organization slug, or the environment path value, from the request path.
user_id	string	The user ID from the request path, decoded.
profile_id	string	JustAI’s identifier for the profile.
updated_at	number	The latest update time applied to the profile, in epoch milliseconds. JustAI takes it from your Identify timestamp values, or from the receipt time when a call has no timestamp. An older update does not move it back.
fields	object	Every saved trait. Values keep their JSON types. A trait set to null appears with the value null.

Example

curl "https://ingest.justwords.ai/api/profiles/$JUSTAI_ORG_SLUG/user-1234" \
  -H "X-Api-Key: $JUSTAI_API_KEY"

Response

{
  "org_slug": "acme",
  "user_id": "user-1234",
  "profile_id": "8f14e45f-ceea-4e7a-9a1b-2c3d4e5f6a7b",
  "updated_at": 1790856000000,
  "fields": {
    "email": "ada@example.com",
    "first_name": "Ada",
    "plan": "pro",
    "address": { "city": "Paris", "country": "FR" }
  }
}

Read right after an update

A read right after an Identify call can briefly return the previous values. For a new user, it can briefly return 404. If your change is not there, wait a minute and read again.

A 200 from Identify does not mean that every trait changed. JustAI skips a trait when the stored value is newer than your call’s time. Compare fields with what you sent. See How updates merge.

Errors

Status	Body	Cause	Action
404	{"error":"Profile not found"}	No profile in this environment has this user ID.	Check the user ID, its encoding, and the environment. If you sent the first Identify for this user moments ago, wait a minute and read again.
404	404 Not Found (plain text)	The URL does not match the endpoint. Causes include an empty user ID, a trailing slash, and a method other than GET.	Fix the URL and method.

Authentication, path, and server errors are the same for all three APIs. See Errors and retries.

Next steps

Identify APICreate and update the profiles you read here.

Test your connectionSend a profile, read it back, and send an event.

Errors and retriesStatus codes, retries, and duplicate handling.