# 

Creating a client is the first step in boarding a merchant. It returns the credentials that merchant will authenticate with, and those credentials are shown exactly once.

## Before you start

* Your reseller `Api-Key` and `Client-Id` — see [Authentication](/docs/get-started/authentication)
* Your own client ID, which becomes the new client's `parent_id`


## Create a client

Four fields are required:

| Field | Notes |
|  --- | --- |
| `parent_id` | Your client ID. The reseller or ISO this account sits under |
| `type` | `merchant` or `reseller`, lowercase |
| `dba` | The doing-business-as name |
| `admin_contact_details` | An object, with four required fields of its own |


`admin_contact_details` on a create needs `first_name`, `last_name`, `email` and `time_zone`. `time_zone` comes from a fixed list of seven US zones, not the full IANA database — `America/New_York`, `America/Chicago`, `America/Denver`, `America/Los_Angeles`, `America/Phoenix`, `America/Anchorage`, `Pacific/Honolulu`.

## Store the API key now

The response carries `api_key`.

```json
{
  "id": "CLIENT-01KFDKXMQ637EKEAY410MSQSXB",
  "dba": "Acme Jewelry",
  "api_key": "pk_live_01KFDKXMQ637EKEAY410MSQSXB"
}
```

**This is the only response that ever contains it.** There is no endpoint that reads a key back and no way to recover one. Write it to your secret store before you do anything else with the response.

The `id` is the new client's `Client-Id`. The merchant sends both.

## Update a client

`POST /v1/clients/{clientId}` — a **POST**, not a PUT or a PATCH. The API uses POST for updates throughout.

```json
{
  "parent_id": "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "dba": "Acme Fine Jewelry",
  "admin_contact_details": {}
}
```

**Three fields are required on every update: `parent_id`, `dba` and `admin_contact_details`.** Send the current value of any you are not changing. Leave one out and the update returns `400` with `INVALID_REQUEST_DATA`, and `details` names each missing field.

`admin_contact_details` has to be present, but nothing inside it is required, even though it has four required fields on a create. Send `{}` when the contact details are not changing, or only the contact fields you are changing.

Every other field is optional. Send only the fields you are changing; everything you omit is left alone.

**`parent_id` is not read-only.** The gateway stores whatever you send as the client's parent, so a different value moves the client under that account. Two fields cannot be changed after creation: the client's `id` and its API key.

## There is no delete

Clients cannot be removed through the API. To stop a merchant processing, deactivate its integrations with `is_active: false` — see [Connect a processor](/docs/platforms/connect-a-processor).

## Field rules the schema does not state

Three constraints the service enforces and the description does not yet describe. They return `400` with `INVALID_REQUEST_DATA`.

| Field | What is rejected |
|  --- | --- |
| `website` | Anything over **30 characters**, though no maximum is published |
| `email` | Plus-addressing, and any top-level domain longer than four characters. `ops+paradise@example.com` and `ops@acme.agency` both fail |
| `admin_contact_details.phone` | A separator after the country code, even though the shared `Phone` schema publishes `+1-800-555-1234` as an example. Send `+18005551234` |


## Next steps

* [Connect a processor](/docs/platforms/connect-a-processor)
* [Act on behalf of a client](/docs/platforms/act-on-behalf-of-a-client)
* [Client reports](/docs/platforms/client-reports)