# 

## Prerequisites

* A valid API key for the client account — see [Obtain API credentials](/docs/how-tos/setup/obtain-credentials)
* The client must already exist — see [Onboard a new client](/docs/how-tos/clients-users/onboard-client)


## User properties

| Field | Required | Description |
|  --- | --- | --- |
| `first_name` | Yes | User's first name |
| `last_name` | Yes | User's last name |
| `email` | Yes | Email address (also the username for login) |
| `phone` | No | Phone number in E.164 format |
| `time_zone` | No | IANA time zone (for example, `America/Chicago`) |


## Step 1: Create the user

Send `POST /v1/users` with the user details. Authenticate using the client's API key so the user is associated with the correct client.

curl
```shell
curl -X POST \
  https://api.dev.paradisegateway.net/v1/users \
  -H "Content-Type: application/json" \
  -H "APIKEY: CLIENT-API-KEY" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "phone": "+15559876543",
    "time_zone": "America/Chicago"
  }'
```

Python
```python
import requests

resp = requests.post(
    "https://api.dev.paradisegateway.net/v1/users",
    headers={"Content-Type": "application/json", "APIKEY": "CLIENT-API-KEY"},
    json={
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane.smith@example.com",
        "phone": "+15559876543",
        "time_zone": "America/Chicago",
    },
)
print(resp.json())
```

JavaScript
```javascript
const resp = await fetch(
  "https://api.dev.paradisegateway.net/v1/users",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "APIKEY": "CLIENT-API-KEY",
    },
    body: JSON.stringify({
      first_name: "Jane",
      last_name: "Smith",
      email: "jane.smith@example.com",
      phone: "+15559876543",
      time_zone: "America/Chicago",
    }),
  }
);
console.log(await resp.json());
```

C#
```csharp
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("APIKEY", "CLIENT-API-KEY");

var payload = new
{
    first_name = "Jane", last_name = "Smith",
    email = "jane.smith@example.com",
    phone = "+15559876543", time_zone = "America/Chicago"
};
var resp = await client.PostAsJsonAsync(
    "https://api.dev.paradisegateway.net/v1/users", payload);
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```

Java
```java
HttpClient client = HttpClient.newHttpClient();
String body = """
    {
      "first_name": "Jane", "last_name": "Smith",
      "email": "jane.smith@example.com",
      "phone": "+15559876543",
      "time_zone": "America/Chicago"
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dev.paradisegateway.net/v1/users"))
    .header("Content-Type", "application/json")
    .header("APIKEY", "CLIENT-API-KEY")
    .POST(HttpRequest.BodyPublishers.ofString(body)).build();
HttpResponse<String> resp = client.send(request,
    HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());
```

Go
```go
payload := strings.NewReader(`{
  "first_name": "Jane", "last_name": "Smith",
  "email": "jane.smith@example.com",
  "phone": "+15559876543",
  "time_zone": "America/Chicago"
}`)
req, _ := http.NewRequest("POST",
    "https://api.dev.paradisegateway.net/v1/users", payload)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("APIKEY", "CLIENT-API-KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
```

PHP
```php
$ch = curl_init("https://api.dev.paradisegateway.net/v1/users");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Content-Type: application/json", "APIKEY: CLIENT-API-KEY"],
    CURLOPT_POSTFIELDS => json_encode([
        "first_name" => "Jane", "last_name" => "Smith",
        "email" => "jane.smith@example.com",
        "phone" => "+15559876543",
        "time_zone" => "America/Chicago",
    ]),
]);
echo curl_exec($ch); curl_close($ch);
```

Ruby
```ruby
require "net/http"; require "json"
uri = URI("https://api.dev.paradisegateway.net/v1/users")
req = Net::HTTP::Post.new(uri, {
  "Content-Type" => "application/json", "APIKEY" => "CLIENT-API-KEY",
})
req.body = {
  first_name: "Jane", last_name: "Smith",
  email: "jane.smith@example.com",
  phone: "+15559876543", time_zone: "America/Chicago",
}.to_json
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts resp.body
```

### Response

A `201 Created` response returns the new user.

```json
{
  "id": "USER-5NvxCyMmeKxIv8jz39b4urQb",
  "object": "user",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@example.com",
  "phone": "+15559876543",
  "time_zone": "America/Chicago",
  "is_mfa_active": false,
  "is_active": true,
  "is_locked": false,
  "correlation_id": "c3d4e5f6-a7b8-9012-cdef-123456789abc"
}
```

## Step 2: List existing users

To see all users on the client account, send `GET /v1/users`.

```shell
curl https://api.dev.paradisegateway.net/v1/users \
  -H "APIKEY: CLIENT-API-KEY"
```

The response is an array of user objects associated with the client whose API key you used.

## User states

| Field | Description |
|  --- | --- |
| `is_active` | `true` = the user can log in and make API calls |
| `is_locked` | `true` = the account is locked (too many failed login attempts) |
| `is_mfa_active` | `true` = multi-factor authentication is enabled |


## Next steps

* [Update a user profile](/docs/how-tos/clients-users/update-user) — modify name, email, or phone
* [Reset a user password](/docs/how-tos/clients-users/reset-password)
* [Enable MFA](/docs/how-tos/clients-users/enable-mfa)
* [About users and roles](/docs/concepts/account-hierarchy/users-and-roles)