# 

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
{
  "dba": "Acme Fine Jewelry"
}
```

**Nothing is required.** Send only the fields you are changing; everything you
omit is left alone. The same is true inside `admin_contact_details`, which has no
required fields on an update even though it has four on a create.

Three fields cannot be changed after creation: `parent_id`, 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)