Create user - Junction

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-14T13:13:59+00:00",
      "source": {
        "logo": "logo_url",
        "name": "Oura",
        "slug": "oura"
      }
    }
  ],
  "created_on": "2026-07-14T13:13:59+00:00",
  "fallback_birth_date": {
    "source_slug": "manual",
    "updated_at": "2026-07-14T13:13:59+00:00",
    "value": "1989-09-12"
  },
  "fallback_time_zone": {
    "id": "Europe/London",
    "source_slug": "manual",
    "updated_at": "2026-07-14T13:13:59+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>"
}

POST

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-14T13:13:59+00:00",
      "source": {
        "logo": "logo_url",
        "name": "Oura",
        "slug": "oura"
      }
    }
  ],
  "created_on": "2026-07-14T13:13:59+00:00",
  "fallback_birth_date": {
    "source_slug": "manual",
    "updated_at": "2026-07-14T13:13:59+00:00",
    "value": "1989-09-12"
  },
  "fallback_time_zone": {
    "id": "Europe/London",
    "source_slug": "manual",
    "updated_at": "2026-07-14T13:13:59+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

created_on

string<date-time>

required

When your item is created

connected_sources

ConnectedSourceClientFacing · object[]

required

A list of the users connected sources.

Show child attributes

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).

Show child attributes

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.

Show child attributes

ingestion_start

string<date> | null

Starting bound for user data ingestion bounds.

ingestion_end

string<date> | null

Ending bound for user data ingestion bounds.

Get User

⌘I