# 

## Prerequisites

* A valid API key for your parent account — see [Obtain API credentials](/docs/how-tos/setup/obtain-credentials)
* The `parent_id` of the account under which the new client will be created


## Onboarding flow

![image](https://files.modern-mermaid.live/images/1776276286307-mermaid-diagram-1776276286546.png)

## Step 1: Create the client account

Send `POST /v1/clients` with the client details.

| Field | Required | Description |
|  --- | --- | --- |
| `dba` | Yes | Doing-business-as name |
| `parent_id` | Yes | ID of the parent client or reseller account |
| `type` | Yes | `merchant` or `reseller` |
| `admin_contact_details.first_name` | Yes | Admin first name |
| `admin_contact_details.last_name` | Yes | Admin last name |
| `admin_contact_details.email` | Yes | Admin email address |
| `admin_contact_details.phone` | Yes | Admin phone number |
| `admin_contact_details.time_zone` | Yes | IANA time zone (for example, `America/New_York`) |


curl
```shell
curl -X POST \
  https://api.dev.paradisegateway.net/v1/clients \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{
    "dba": "Acme Jewelry",
    "parent_id": "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
    "type": "merchant",
    "admin_contact_details": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+15551234567",
      "time_zone": "America/New_York"
    }
  }'
```

Python
```python
import requests

resp = requests.post(
    "https://api.dev.paradisegateway.net/v1/clients",
    headers={"Content-Type": "application/json", "APIKEY": "YOUR-API-KEY"},
    json={
        "dba": "Acme Jewelry",
        "parent_id": "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
        "type": "merchant",
        "admin_contact_details": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "phone": "+15551234567",
            "time_zone": "America/New_York",
        },
    },
)
data = resp.json()
print("Client ID:", data["id"])
```

JavaScript
```javascript
const resp = await fetch(
  "https://api.dev.paradisegateway.net/v1/clients",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "APIKEY": "YOUR-API-KEY",
    },
    body: JSON.stringify({
      dba: "Acme Jewelry",
      parent_id: "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
      type: "merchant",
      admin_contact_details: {
        first_name: "John",
        last_name: "Doe",
        email: "john.doe@example.com",
        phone: "+15551234567",
        time_zone: "America/New_York",
      },
    }),
  }
);
const data = await resp.json();
console.log("Client ID:", data.id);
```

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

var payload = new
{
    dba = "Acme Jewelry",
    parent_id = "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
    type = "merchant",
    admin_contact_details = new
    {
        first_name = "John", last_name = "Doe",
        email = "john.doe@example.com", phone = "+15551234567",
        time_zone = "America/New_York"
    }
};
var resp = await client.PostAsJsonAsync(
    "https://api.dev.paradisegateway.net/v1/clients", payload);
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```

Java
```java
HttpClient client = HttpClient.newHttpClient();
String body = """
    {
      "dba": "Acme Jewelry",
      "parent_id": "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
      "type": "merchant",
      "admin_contact_details": {
        "first_name": "John", "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone": "+15551234567",
        "time_zone": "America/New_York"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dev.paradisegateway.net/v1/clients"))
    .header("Content-Type", "application/json")
    .header("APIKEY", "YOUR-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(`{
  "dba": "Acme Jewelry",
  "parent_id": "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "type": "merchant",
  "admin_contact_details": {
    "first_name": "John", "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+15551234567",
    "time_zone": "America/New_York"
  }
}`)
req, _ := http.NewRequest("POST",
    "https://api.dev.paradisegateway.net/v1/clients", payload)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("APIKEY", "YOUR-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/clients");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Content-Type: application/json", "APIKEY: YOUR-API-KEY"],
    CURLOPT_POSTFIELDS => json_encode([
        "dba" => "Acme Jewelry",
        "parent_id" => "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
        "type" => "merchant",
        "admin_contact_details" => [
            "first_name" => "John", "last_name" => "Doe",
            "email" => "john.doe@example.com", "phone" => "+15551234567",
            "time_zone" => "America/New_York",
        ],
    ]),
]);
echo curl_exec($ch); curl_close($ch);
```

Ruby
```ruby
require "net/http"; require "json"
uri = URI("https://api.dev.paradisegateway.net/v1/clients")
req = Net::HTTP::Post.new(uri, {
  "Content-Type" => "application/json", "APIKEY" => "YOUR-API-KEY",
})
req.body = {
  dba: "Acme Jewelry",
  parent_id: "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
  type: "merchant",
  admin_contact_details: {
    first_name: "John", last_name: "Doe",
    email: "john.doe@example.com", phone: "+15551234567",
    time_zone: "America/New_York",
  },
}.to_json
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts resp.body
```

### Response example

A `200` response returns the new client, including credentials for the client's own API access.

```json
{
  "id": "CLIENT-3MtwBwLkdIwHu7ix28a3tqPa",
  "object": "client",
  "dba": "Acme Jewelry",
  "parent_id": "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "type": "merchant",
  "admin_contact_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+15551234567",
    "time_zone": "America/New_York"
  },
  "api_key": "KEY-...",
  "encryption_keys": { ... },
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

Store credentials securely
The `api_key` and `encryption_keys` are returned only in the creation response. Store them in a secrets manager and provide them to the client through a secure channel.

Save the `id` value — you need it in the next step.

## Step 2: Create the first user

Send `POST /v1/users` to create a user account linked to the new client.

| Field | Required | Description |
|  --- | --- | --- |
| `first_name` | Yes | User's first name |
| `last_name` | Yes | User's last name |
| `email` | Yes | User's email (also used as username) |
| `phone` | No | User's phone number |
| `time_zone` | No | IANA time zone |


curl
```shell
curl -X POST \
  https://api.dev.paradisegateway.net/v1/users \
  -H "Content-Type: application/json" \
  -H "APIKEY: KEY-..." \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+15551234567",
    "time_zone": "America/New_York"
  }'
```

Python
```python
resp = requests.post(
    "https://api.dev.paradisegateway.net/v1/users",
    headers={"Content-Type": "application/json", "APIKEY": "KEY-..."},
    json={
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone": "+15551234567",
        "time_zone": "America/New_York",
    },
)
print(resp.json())
```

JavaScript
```javascript
const resp = await fetch(
  "https://api.dev.paradisegateway.net/v1/users",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "APIKEY": "KEY-...",
    },
    body: JSON.stringify({
      first_name: "John",
      last_name: "Doe",
      email: "john.doe@example.com",
      phone: "+15551234567",
      time_zone: "America/New_York",
    }),
  }
);
console.log(await resp.json());
```

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

var userPayload = new
{
    first_name = "John", last_name = "Doe",
    email = "john.doe@example.com", phone = "+15551234567",
    time_zone = "America/New_York"
};
var resp = await userClient.PostAsJsonAsync(
    "https://api.dev.paradisegateway.net/v1/users", userPayload);
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```

Java
```java
String userBody = """
    {
      "first_name": "John", "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+15551234567",
      "time_zone": "America/New_York"
    }
    """;
HttpRequest userReq = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dev.paradisegateway.net/v1/users"))
    .header("Content-Type", "application/json")
    .header("APIKEY", "KEY-...")
    .POST(HttpRequest.BodyPublishers.ofString(userBody)).build();
HttpResponse<String> userResp = client.send(userReq,
    HttpResponse.BodyHandlers.ofString());
System.out.println(userResp.body());
```

Go
```go
payload := strings.NewReader(`{
  "first_name": "John", "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+15551234567",
  "time_zone": "America/New_York"
}`)
req, _ := http.NewRequest("POST",
    "https://api.dev.paradisegateway.net/v1/users", payload)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("APIKEY", "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: KEY-..."],
    CURLOPT_POSTFIELDS => json_encode([
        "first_name" => "John", "last_name" => "Doe",
        "email" => "john.doe@example.com",
        "phone" => "+15551234567",
        "time_zone" => "America/New_York",
    ]),
]);
echo curl_exec($ch); curl_close($ch);
```

Ruby
```ruby
uri = URI("https://api.dev.paradisegateway.net/v1/users")
req = Net::HTTP::Post.new(uri, {
  "Content-Type" => "application/json", "APIKEY" => "KEY-...",
})
req.body = {
  first_name: "John", last_name: "Doe",
  email: "john.doe@example.com",
  phone: "+15551234567", time_zone: "America/New_York",
}.to_json
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts resp.body
```

### Response example for creating a user

A `201 Created` response confirms the user was created.

```json
{
  "id": "USER-3MtwBwLkdIwHu7ix28a3tqPa",
  "object": "user",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+15551234567",
  "time_zone": "America/New_York",
  "is_mfa_active": false,
  "is_active": true,
  "is_locked": false,
  "correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
```

## Step 3: Verify the onboarding

Confirm the client and user exist by retrieving them.

```shell
# Verify client
curl https://api.dev.paradisegateway.net/v1/clients/CLIENT-3MtwBwLkdIwHu7ix28a3tqPa \
  -H "APIKEY: YOUR-API-KEY"

# Verify user
curl https://api.dev.paradisegateway.net/v1/users/USER-3MtwBwLkdIwHu7ix28a3tqPa \
  -H "APIKEY: KEY-..."
```

## Next steps

* [Add more users to the client](/docs/how-tos/clients-users/add-users-client)
* [Enable MFA for users](/docs/how-tos/clients-users/enable-mfa)
* [Set up the sandbox environment](/docs/how-tos/setup/setup-sandbox-env)
* [About clients and resellers](/docs/concepts/account-hierarchy/clients-and-resellers)