---
title: "Create a User Intent"
method: POST
path: "/v1/user_intent"
tags: ["User"]
---

# Create a User Intent

`POST /v1/user_intent`

> 📘
>
> You can place your application's `client_id` into the `username` field, and your `client_secret` into the `password` form field of the Authentication section of this documentation 👉.

A User Intent manages the lifecycle of the creation of a User, before that User has been fully created. This endpoint creates a User Intent, starting the process of verifying the end-user's identity in the background.\n

For managing UserIntents, Astra recommends that once a UserIntent is created, you should store that UserIntent ID with the User record. The UserIntent ID can then be sent as a query string parameter to the Astra OAuth flow. Once your application receives the `authorization_code`, you can make a call to the `GET /v1/user` endpoint which will give you a `user_id`.

> 📘
>
> For `receive-only` Users, the SSN and DOB fields become optional. For `unverified` Users, the SSN field becomes optional. For `verified Users`, SSN and DOB are required, unless your program is approved for KYC Delegation. If your program is approved for KYC delegation, the SSN field becomes optional.

> 🚧
>
> Note that a new UserIntent should only be created if an end-user is starting from scratch or had originally provided incorrect information.

> 🚧
>
> Note that if a UserIntent doesn't have an address2 value, send Astra an empty string instead of a null or you'll recieve a 400 response upon POSTing the request.

> ❗️
>
> Note that you may only attempt to create 3 UserIntents per email address. If you reach this limit while creating UserIntents in your Sandbox Environment, you will receive an error.

> ❗️
>
> The `ip_address` field is the IP address of the User’s device they are using to access our Platform. Submission of Private IP Addresses or VPNs can result in downgraded User capabilities or even a `rejected` UserIntent / User Profile.

## Request body

- object
  - `email` string, required — Email address of the user
  - `phone` string, required — Phone number of the user (format: +15557771234)
  - `first_name` string, required — First name of the user
  - `last_name` string, required — Last name of the user
  - `preferred_first_name` string — Preferred first name of the user
  - `preferred_last_name` string — Preferred last name of the user
  - `preferred_pronouns` string — Preferred pronouns of the user
  - `address1` string, required — Address line 1 of the user (PO Boxes are not allowed)
  - `address2` string — Address line 2 of the user (PO Boxes are not allowed)
  - `city` string, required — City of the user
  - `state` string, required — State of the user's address
  - `postal_code` string, required — Postal code of the user
  - `date_of_birth` string, required — Date of birth of the user (format: YYYY-MM-DD)
  - `ssn` string, required — Social Security Number of the user (format: Last four ####)
  - `ip_address` string, required — IP address of the User's device they are using to access Astra's Platform
  - `kyc_type` 'receive-only' | 'unverified' | 'verified' — The verification type of the user, which determines the user's capabilities to send and/or receive funds (will default to 'verified' if not provided)
  - `metadata` object — An optional metadata object for submitting [custom metadata](https://docs.astra.finance/reference/custom-metadata) that will be associated with the User Intent and the User. Do not submit any sensitive information (bank account numbers, card details, PII, etc.) as metadata keys or values. metadata key: 1–64 chars, allowed chars set [a-zA-Z0-9_.-] metadata values: 1–256 chars Max keys: 25 Recommended use case: Submitting a customer specific unique identifier (UUID format). Uniqueness not required.

## Response `201`

Successful response

- object
  - `id` string — Unique Astra user intent ID

## Other responses

- `400` — Bad Request
- `403` — Forbidden

---

[API](https://skmtc.net/astra/apis/astra-developer-api.md) · [All operations](https://skmtc.net/astra/apis/astra-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/astra/astra-developer-api/versions/09f0430e5d33/schema)