Skip to main content
POST
/
v2
/
user
curl --request POST \
     --url {{BASE_URL}}/v2/user/ \
     --header 'Accept: application/json' \
     --header 'x-vital-api-key: <API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
{
     "client_user_id": "your_unique_id"
}
'
import { JunctionClient, JunctionEnvironment } from "@junction-api/sdk";

const client = new JunctionClient({
    apiKey: "YOUR_API_KEY",
    environment: JunctionEnvironment.Sandbox,
});

const data = await client.user.create({ clientUserId: "<client_user_id>" });
from junction import Junction
from junction.environment import JunctionEnvironment

client = Junction(
    api_key="YOUR_API_KEY",
    environment=JunctionEnvironment.SANDBOX,
)

data = client.user.create(client_user_id="<client_user_id>")
import com.junction.api.Junction;
import com.junction.api.core.Environment;
import com.junction.api.resources.user.requests.UserCreateBody;

Junction client = Junction.builder()
    .apiKey("YOUR_API_KEY")
    .environment(Environment.SANDBOX)
    .build();

var data = client.user().create(
    UserCreateBody.builder()
        .clientUserId("<client_user_id>")
        .build()
);
import (
    "context"

    junction "github.com/junction-api/junction-go"
    "github.com/junction-api/junction-go/client"
    "github.com/junction-api/junction-go/option"
)

c := client.NewClient(
    option.WithApiKey("YOUR_API_KEY"),
    option.WithBaseURL(junction.Environments.Sandbox),
)

response, err := c.User.Create(context.TODO(), &junction.UserCreateBody{
    ClientUserId: "<client_user_id>",
})
if err != nil {
    return err
}
fmt.Printf("Received data %s\n", response)
{
  "client_user_id": "ZTEwZjNjMjctOTI2ZS00M2Vm",
  "connected_sources": [
    {
      "created_on": "2026-07-10T17:33:48+00:00",
      "source": {
        "logo": "logo_url",
        "name": "Oura",
        "slug": "oura"
      }
    }
  ],
  "created_on": "2026-07-10T17:33:48+00:00",
  "fallback_birth_date": {
    "source_slug": "manual",
    "updated_at": "2026-07-10T17:33:48+00:00",
    "value": "1989-09-12"
  },
  "fallback_time_zone": {
    "id": "Europe/London",
    "source_slug": "manual",
    "updated_at": "2026-07-10T17:33:48+00:00"
  },
  "team_id": "56bd81c9-6219-4000-a775-ae85526eba18",
  "user_id": "56bd81c9-6219-4000-a775-ae85526eba18"
}
{
"detail": {
"created_on": "2023-02-27T12:31:24+00:00",
"error_message": "Client user id already exists.",
"error_type": "INVALID_REQUEST",
"user_id": "1449752e-0d8a-40e0-9206-91ab099b2537"
}
}
{
"detail": "<unknown>"
}
When the supplied client_user_id conflicts with an existing user, the 400 Bad Request error response includes the Junction User ID (user_id) and the creation date (created_on) of the conflicting user.
curl --request POST \
     --url {{BASE_URL}}/v2/user/ \
     --header 'Accept: application/json' \
     --header 'x-vital-api-key: <API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
{
     "client_user_id": "your_unique_id"
}
'
import { JunctionClient, JunctionEnvironment } from "@junction-api/sdk";

const client = new JunctionClient({
    apiKey: "YOUR_API_KEY",
    environment: JunctionEnvironment.Sandbox,
});

const data = await client.user.create({ clientUserId: "<client_user_id>" });
from junction import Junction
from junction.environment import JunctionEnvironment

client = Junction(
    api_key="YOUR_API_KEY",
    environment=JunctionEnvironment.SANDBOX,
)

data = client.user.create(client_user_id="<client_user_id>")
import com.junction.api.Junction;
import com.junction.api.core.Environment;
import com.junction.api.resources.user.requests.UserCreateBody;

Junction client = Junction.builder()
    .apiKey("YOUR_API_KEY")
    .environment(Environment.SANDBOX)
    .build();

var data = client.user().create(
    UserCreateBody.builder()
        .clientUserId("<client_user_id>")
        .build()
);
import (
    "context"

    junction "github.com/junction-api/junction-go"
    "github.com/junction-api/junction-go/client"
    "github.com/junction-api/junction-go/option"
)

c := client.NewClient(
    option.WithApiKey("YOUR_API_KEY"),
    option.WithBaseURL(junction.Environments.Sandbox),
)

response, err := c.User.Create(context.TODO(), &junction.UserCreateBody{
    ClientUserId: "<client_user_id>",
})
if err != nil {
    return err
}
fmt.Printf("Received data %s\n", response)

Authorizations

x-vital-api-key
string
header
required

Vital Team API Key

Body

application/json
client_user_id
string
required

A unique ID representing the end user. Typically this will be a user ID from your application. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

fallback_time_zone
string | null
Fallback time zone of the user, in the form of a valid IANA tzdatabase identifier (e.g., `Europe/London` or `America/Los_Angeles`).
Used when pulling data from sources that are completely time zone agnostic (e.g., all time is relative to UTC clock, without any time zone attributions on data points).
fallback_birth_date
string<date> | null

Fallback date of birth of the user, in YYYY-mm-dd format. Used for calculating max heartrate for providers that don not provide users' age.

ingestion_start
string<date> | null

Starting bound for user data ingestion bounds.

ingestion_end
string<date> | null

Ending bound for user data ingestion bounds.

Response

Successful Response

user_id
string<uuid>
required

User id returned by vital create user request. This id should be stored in your database against the user and used for all interactions with the vital api.

team_id
string<uuid>
required

Your team id.

client_user_id
string
required

A unique ID representing the end user. Typically this will be a user ID from your application. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

created_on
string<date-time>
required

When your item is created

connected_sources
ConnectedSourceClientFacing · object[]
required

A list of the users connected sources.

fallback_time_zone
FallbackTimeZone · object | null
required
Fallback time zone of the user, in the form of a valid IANA tzdatabase identifier (e.g., `Europe/London` or `America/Los_Angeles`).
Used when pulling data from sources that are completely time zone agnostic (e.g., all time is relative to UTC clock, without any time zone attributions on data points).
fallback_birth_date
FallbackBirthDate · object | null

Fallback date of birth of the user, in YYYY-mm-dd format. Used for calculating max heartrate for providers that don not provide users' age.

ingestion_start
string<date> | null

Starting bound for user data ingestion bounds.

ingestion_end
string<date> | null

Ending bound for user data ingestion bounds.