Test your connection

In this tutorial, you send one customer profile and one customer event for a test person from your terminal. Then you read the profile back with the Profiles API and find the person and the event in the JustAI app. When you finish, you know that your API key, organization slug, and environment work, and that a profile and an event with the same user ID line up. The last check may require waiting for the event to appear.

Before you begin

A terminal with bash or zsh, and curl.
An API key for the environment you want to test. In the JustAI app, switch to that environment. Open the account menu, select Settings > API keys, and select New key. Copy the key when it is shown, because JustAI shows it only once. A new key may not work immediately. Confirm it succeeds before switching traffic to it. If New key reports that key creation is restricted, ask your JustAI team to enable API access for your organization.
Your organization slug, from your JustAI team.
Access to the JustAI app in the same environment.

This tutorial uses the test user ID user-1234 and the address ada@example.com. Use values that do not belong to a real customer.

1. Store your credentials in the shell

Run these commands and enter each value at the prompt. For production, leave the environment key empty and press Enter. The API key does not appear on screen and does not go into your shell history.

printf "Organization slug: "
read -r JUSTAI_ORG_SLUG
printf "Environment key (empty for production): "
read -r JUSTAI_ENVIRONMENT
printf "API key (hidden): "
read -r -s JUSTAI_API_KEY
echo

Check the values without printing the key:

echo "Slug: $JUSTAI_ORG_SLUG"
echo "Environment: ${JUSTAI_ENVIRONMENT:-production}"
echo "Key starts with: ${JUSTAI_API_KEY:0:4}"

You see your slug, the environment, and the start of the key:

Slug: acme
Environment: production
Key starts with: jai_

If the key does not start with jai_, run the commands again and paste the key exactly as JustAI showed it.

Every command on this page sends the X-JustAI-Environment header with your environment key. When the environment key is empty, curl leaves the header out, and the request goes to production.

2. Send a customer profile

Send one Identify request for the test person:

curl --silent --show-error --write-out "\nHTTP %{http_code}\n" \
  --request POST "https://ingest.justwords.ai/api/identify/$JUSTAI_ORG_SLUG" \
  --header "X-Api-Key: $JUSTAI_API_KEY" \
  --header "X-JustAI-Environment: $JUSTAI_ENVIRONMENT" \
  --header "Content-Type: application/json" \
  --data @- <<'EOF'
{
  "userId": "user-1234",
  "messageId": "connection-test-identify-user-1234",
  "traits": {
    "email": "ada@example.com",
    "first_name": "Ada",
    "plan": "trial"
  }
}
EOF

JustAI creates the profile and returns 200. The output is the response body, followed by HTTP 200:

{"success":true,"messageId":"connection-test-identify-user-1234","duplicate":false}

If you run this step again without changes, the response has "duplicate":true. That is expected. JustAI recognizes the same messageId and body as a retry and applies nothing twice.

3. Read the profile back

Read the saved profile with the Profiles API:

curl --silent --show-error --write-out "\nHTTP %{http_code}\n" \
  "https://ingest.justwords.ai/api/profiles/$JUSTAI_ORG_SLUG/user-1234" \
  --header "X-Api-Key: $JUSTAI_API_KEY" \
  --header "X-JustAI-Environment: $JUSTAI_ENVIRONMENT"

JustAI returns 200 with the profile. Your org_slug, profile_id, and updated_at values differ from this example:

{"org_slug":"acme","user_id":"user-1234","profile_id":"5f0c9a52-3e1b-4d7a-9c2e-8b6f1a2d4e90","updated_at":1791817200000,"fields":{"plan":"trial","email":"ada@example.com","first_name":"Ada"}}

Check that fields holds the three traits you sent.

If you get 404 with {"error":"Profile not found"} right after step 2, wait a minute and run the command again. A read right after an update can briefly return the previous state.

4. Send an event for the same user

Send one Track request with the same user ID. The command fills in the current time as the event’s timestamp:

curl --silent --show-error --write-out "\nHTTP %{http_code}\n" \
  --request POST "https://ingest.justwords.ai/api/track/$JUSTAI_ORG_SLUG" \
  --header "X-Api-Key: $JUSTAI_API_KEY" \
  --header "X-JustAI-Environment: $JUSTAI_ENVIRONMENT" \
  --header "Content-Type: application/json" \
  --data @- <<EOF
{
  "type": "track",
  "messageId": "connection-test-track-user-1234",
  "userId": "user-1234",
  "event": "Connection Tested",
  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "properties": {
    "source": "curl"
  }
}
EOF

JustAI accepts the event and returns 202. The output ends with HTTP 202:

{"message_id":"connection-test-track-user-1234","status":"accepted"}

Check that message_id matches the messageId you sent. If you run this step again, JustAI returns 202 again and still counts the event once, because the messageId is the same.

The event name Connection Tested stays in your event list and in journey event pickers for 30 days. Tell your team that it is a test event.

5. Confirm both in JustAI

In the JustAI app, check the account menu at the bottom of the left sidebar. It shows your organization and environment. Switch to the environment you sent to if needed.
Select Users and search for user-1234. Open the person. Attributes shows the User ID user-1234, the Email ada@example.com, and the first_name and plan traits.
Select Events, then the Custom events tab. Connection Tested appears after processing. Select Refresh to reload the list.
Select Connection Tested. Under Recent events, find the event from user-1234.

If the accepted event still doesn’t appear after you refresh, contact your JustAI team with the messageId connection-test-track-user-1234. Do not resend it.

Your connection works. The API key, organization slug, and environment are correct, and the profile and event for user-1234 belong to the same person.

If a step fails

Response	Cause	Fix
`401` with `{"error":"Missing API key"}`	The key variable is empty.	Run step 1 again.
`401` with `{"error":"Invalid API key"}`	The key is incomplete, mistyped, or revoked, or it was just created.	Wait a minute and run the command again. If it still fails, paste the key again in step 1, or create a new key in Settings > API keys.
`403` with `{"error":"Forbidden"}`	The key belongs to a different organization or environment than the URL and headers.	Run step 1 again with the slug or path value and the environment key that match the key’s environment.
`400` with `{"error":"Invalid org slug"}`	The slug is not in the right format. Uppercase letters are a common cause.	Use the lowercase slug from your JustAI team.
`400` with `{"error":"Invalid environment"}`	The environment key has the wrong format.	Run step 1 again with the exact environment key from your JustAI team. For production, leave it empty.
`400` with `{"error":"Invalid Identify call", ...}`	The Identify body failed validation.	Read the `issues` list in the response, then fix the body.
`404` with the text `404 Not Found`	The URL has a typo or a trailing slash.	Copy the URL from this page again.
`404` with `{"error":"Profile not found"}`	The read came right after the write, or the user ID or environment is different.	Wait a minute and read again. Check the user ID and environment.
`500` or `503`	A temporary problem in JustAI.	Run the same command again after a short wait.

For every status code and how to retry, see Errors and retries. For symptoms that are not errors, such as a missing event, see Troubleshooting.

Clean up

Remove the credentials from your shell:

unset JUSTAI_API_KEY JUSTAI_ORG_SLUG JUSTAI_ENVIRONMENT

To remove the test person, open them in Users and select Delete user. JustAI asks you to confirm, because the deletion can’t be undone.

If you created the API key only for this test, revoke it in Settings > API keys.

To run this tutorial again later, change both messageId values first, for example by adding the date. JustAI applies each messageId once, so a repeated Identify ID changes nothing, even after you delete the test person.

Next steps

Send customer profilesHow Identify updates merge into a profile, and how to read a profile back.

Send customer eventsName events and send properties that journeys can use.

Connect IterableAdd your Iterable project, content data feed, system webhook, and a sending profile.