> ## Documentation Index
> Fetch the complete documentation index at: https://docs.junction.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create user
> Create or submit user via the Junction API. Requires authentication with your team API key.
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.
```bash cURL theme={null}
curl --request POST \
--url {{BASE_URL}}/v2/user/ \
--header 'Accept: application/json' \
--header 'x-vital-api-key: ' \
--header 'Content-Type: application/json' \
--data '
{
"client_user_id": "your_unique_id"
}
'
```
```typescript TypeScript theme={null}
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: "" });
```
```python Python theme={null}
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="")
```
```java Java theme={null}
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("")
.build()
);
```
```go Go theme={null}
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: "",
})
if err != nil {
return err
}
fmt.Printf("Received data %s\n", response)
```
## OpenAPI
````yaml POST /v2/user
openapi: 3.1.0
info:
title: Junction API
description: https://docs.junction.com/
version: 0.4.483
servers:
- url: https://api.us.junction.com
x-fern-server-name: Production
- url: https://api.eu.junction.com
x-fern-server-name: ProductionEU
- url: https://api.sandbox.us.junction.com
x-fern-server-name: Sandbox
- url: https://api.sandbox.eu.junction.com
x-fern-server-name: SandboxEU
security:
- apiKeyAuth: []
paths:
/v2/user:
post:
tags:
- user
summary: Create User
description: POST Create a Vital user given a client_user_id and returns the user_id.
operationId: create_user_v2_user_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCreateBody'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ClientFacingUser'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ClientUserIDConflictResponse'
description: Bad Request
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
UserCreateBody:
properties:
client_user_id:
type: string
title: Client User Id
description: >-
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:
anyOf:
- type: string
- type: 'null'
title: Fallback Time Zone
description: |2-
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:
anyOf:
- type: string
format: date
- type: 'null'
title: Fallback Birth Date
description: >-
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:
anyOf:
- type: string
format: date
- type: 'null'
title: Ingestion Start
description: >-
Starting bound for user [data ingestion
bounds](https://docs.tryvital.io/wearables/providers/data-ingestion-bounds).
ingestion_end:
anyOf:
- type: string
format: date
- type: 'null'
title: Ingestion End
description: >-
Ending bound for user [data ingestion
bounds](https://docs.tryvital.io/wearables/providers/data-ingestion-bounds).
type: object
required:
- client_user_id
title: UserCreateBody
ClientFacingUser:
properties:
user_id:
type: string
format: uuid
title: User Id
description: >-
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:
type: string
format: uuid
title: Team Id
description: Your team id.
client_user_id:
type: string
title: Client User Id
description: >-
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:
type: string
format: date-time
title: Created On
description: When your item is created
connected_sources:
items:
$ref: '#/components/schemas/ConnectedSourceClientFacing'
type: array
title: Connected Sources
description: A list of the users connected sources.
fallback_time_zone:
anyOf:
- $ref: '#/components/schemas/FallbackTimeZone'
- type: 'null'
description: |2-
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:
anyOf:
- $ref: '#/components/schemas/FallbackBirthDate'
- type: 'null'
description: >-
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:
anyOf:
- type: string
format: date
- type: 'null'
title: Ingestion Start
description: >-
Starting bound for user [data ingestion
bounds](https://docs.tryvital.io/wearables/providers/data-ingestion-bounds).
ingestion_end:
anyOf:
- type: string
format: date
- type: 'null'
title: Ingestion End
description: >-
Ending bound for user [data ingestion
bounds](https://docs.tryvital.io/wearables/providers/data-ingestion-bounds).
type: object
required:
- user_id
- team_id
- client_user_id
- created_on
- connected_sources
- fallback_time_zone
title: User
example:
client_user_id: ZTEwZjNjMjctOTI2ZS00M2Vm
connected_sources:
- created_on: '2026-05-15T20:25:39+00:00'
source:
logo: logo_url
name: Oura
slug: oura
created_on: '2026-05-15T20:25:39+00:00'
fallback_birth_date:
source_slug: manual
updated_at: '2026-05-15T20:25:39+00:00'
value: '1989-09-12'
fallback_time_zone:
id: Europe/London
source_slug: manual
updated_at: '2026-05-15T20:25:39+00:00'
team_id: 56bd81c9-6219-4000-a775-ae85526eba18
user_id: 56bd81c9-6219-4000-a775-ae85526eba18
ClientUserIDConflictResponse:
properties:
detail:
$ref: '#/components/schemas/ClientUserIDConflict'
type: object
required:
- detail
title: ClientUserIDConflictResponse
example:
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
HTTPValidationError:
properties:
detail:
title: Detail
type: object
title: HTTPValidationError
ConnectedSourceClientFacing:
properties:
provider:
$ref: '#/components/schemas/ClientFacingProvider'
description: The provider of this connected source.
created_on:
type: string
format: date-time
title: Created On
description: When your item is created
source:
$ref: '#/components/schemas/ClientFacingProvider'
description: >-
Deprecated. Use `provider` instead. Subject to removal after 1 Jan
2024.
deprecated: true
type: object
required:
- provider
- created_on
- source
title: ConnectedSourceClientFacing
FallbackTimeZone:
properties:
id:
type: string
title: Id
description: |2-
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).
source_slug:
type: string
title: Source Slug
description: Slug for designated source
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- id
- source_slug
- updated_at
title: FallbackTimeZone
FallbackBirthDate:
properties:
value:
type: string
format: date
title: Value
description: >-
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.
source_slug:
type: string
title: Source Slug
description: Slug for designated source
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- value
- source_slug
- updated_at
title: FallbackBirthDate
ClientUserIDConflict:
properties:
error_type:
type: string
title: Error Type
error_message:
type: string
title: Error Message
user_id:
type: string
format: uuid
title: User Id
created_on:
type: string
format: date-time
title: Created On
type: object
required:
- error_type
- error_message
- user_id
- created_on
title: ClientUserIDConflict
ClientFacingProvider:
properties:
name:
type: string
title: Name
description: Name of source of information
slug:
type: string
title: Slug
description: Slug for designated source
logo:
type: string
title: Logo
description: URL for source logo
type: object
required:
- name
- slug
- logo
title: Provider
description: A vendor, a service, or a platform which Vital can connect with.
example:
logo: https://logo_url.com
name: Oura
slug: oura
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-vital-api-key
description: Vital Team API Key
````