# Create a Client

Create a new client account. Client types include `reseller` and `merchant`.

Endpoint: POST /v1/clients
Version: 1.0.0-beta.27
Security: ApiKeyAuth

## Security:

  - `ApiKeyAuth` (unknown)
    apiKey in header Api-Key

## Header parameters:

  - `Client-Id` (string, required)

  - `X-Acting-As-Client-Id` (string)
    The child client this request acts on behalf of. A reseller still authenticates as itself — `Api-Key` and `Client-Id` stay the reseller's — and names the child here.

This works only from a parent to its own children. Merchants have no children, so a merchant calling as itself omits the header. Sending your own client ULID here is not the same as omitting it, and is rejected on some operations.

## Request fields (application/json):

  - `parent_id` (string, required)
    Unique identifier of the parent client account (reseller or ISO).

  - `type` (string, required)
    The type of client account.
    Enum: "reseller", "merchant"

  - `dba` (string, required)
    Doing Business As (DBA) name for the new client.

  - `address` (array)
    One or more client addresses. Each address carries a `type` identifying its purpose (legal, billing, or physical).

  - `address.type` (string)
    The purpose of this address.
    Enum: "LEGAL", "BILLING", "PHYSICAL"

  - `address.line1` (string)
    Primary street address line.

  - `address.line2` (string)
    Secondary address line (suite, apt, floor, etc.).

  - `address.city` (string)
    City name.

  - `address.state` (string)
    Two-letter US state code (e.g. `VA`).

  - `address.postal_code` (string)
    ZIP or postal code.

  - `address.country` (string)
    Two-letter ISO 3166-1 alpha-2 country code (e.g. `US`).

  - `primary_phone` (any)
    Phone number. The phone number must contain between 10 and 12 digits and can contain spaces, a leading `+` symbol (when used with a country  code), and the special characters `(`, `)`, `-`, and `.`. Alphabetical  characters are not allowed.

  - `website` (string)
    URL of client website

  - `admin_contact_details` (object, required)
    Contact information for the primary admin user, supplied when creating a client. The four required properties must each carry a value — null is rejected, and so is an empty string.

  - `admin_contact_details.first_name` (string, required)
    First name of the admin contact.

  - `admin_contact_details.last_name` (string, required)
    Last name of the admin contact.

  - `admin_contact_details.email` (string, required)
    Email address of the admin contact. Used as the login username.

  - `admin_contact_details.time_zone` (string, required)
    The time zone of the account.
    Enum: "America/Los_Angeles", "America/Phoenix", "America/Denver", "America/Chicago", "America/New_York", "Pacific/Honolulu", "America/Anchorage"

  - `metadata` (object | null)
    Key-value pairs for storing additional information on the transaction. Send `null` to clear all metadata.
At most 50 keys. Keys may contain letters, digits, hyphens, and underscores, up to 40 characters. Values are strings up to 500 characters. Every limit below is enforced; a request that exceeds any of them is rejected.

## Response 200:

  - `200` (unknown)
    Client account created successfully

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique identifier for the newly created client assigned by the API server.

  - `parent_id` (string, required)
    Unique identifier of the parent client account.

  - `type` (string, required)
    The type of client account.
    Enum: "reseller", "merchant"

  - `dba` (string, required)
    Doing Business As (DBA) name of the newly created client.

  - `address` (array)
    One or more client addresses. Each address carries a `type` identifying its purpose (legal, billing, or physical).

  - `address.type` (string)
    The purpose of this address.
    Enum: "LEGAL", "BILLING", "PHYSICAL"

  - `address.line1` (string)
    Primary street address line.

  - `address.line2` (string)
    Secondary address line (suite, apt, floor, etc.).

  - `address.city` (string)
    City name.

  - `address.state` (string)
    Two-letter US state code (e.g. `VA`).

  - `address.postal_code` (string)
    ZIP or postal code.

  - `address.country` (string)
    Two-letter ISO 3166-1 alpha-2 country code (e.g. `US`).

  - `primary_phone` (any)
    Phone number. The phone number must contain between 10 and 12 digits and can contain spaces, a leading `+` symbol (when used with a country  code), and the special characters `(`, `)`, `-`, and `.`. Alphabetical  characters are not allowed.

  - `website` (string | null)
    URL of client website. Null when the client was created without one — the gateway returns the field rather than omitting it.

  - `admin_contact_details` (object, required)
    Contact information for the primary admin user of a client account, as returned on a response. The four required properties are always present and may be null, because a client created through an internal path is not held to the rules `ClientAdminContactDetailsInput` applies. A request uses `ClientAdminContactDetailsInput` to create and `ClientAdminContactDetailsUpdate` to amend.

  - `admin_contact_details.first_name` (string | null, required)
    First name of the admin contact.

  - `admin_contact_details.last_name` (string | null, required)
    Last name of the admin contact.

  - `admin_contact_details.email` (string | null, required)
    Email address of the admin contact. Used as the login username.

  - `admin_contact_details.time_zone` (string, required)
    The time zone of the account.
    Enum: "America/Los_Angeles", "America/Phoenix", "America/Denver", "America/Chicago", "America/New_York", "Pacific/Honolulu", "America/Anchorage"

  - `api_key` (string, required)
    API key issued for the new client. Returned once, on this response only — store it, because no later call returns it again.

  - `metadata` (object | null)
    Key-value pairs for storing additional information on the transaction. Send `null` to clear all metadata.
At most 50 keys. Keys may contain letters, digits, hyphens, and underscores, up to 40 characters. Values are strings up to 500 characters. Every limit below is enforced; a request that exceeds any of them is rejected.

  - `correlation_id` (string)
    Identifier the gateway assigns to the request and carries across the services that handled it. Quote it when reporting a problem.

## Response 200 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 400:

  - `400` (unknown)
    Bad request

## Response 400 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 400 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 401:

  - `401` (unknown)
    Not authenticated

## Response 401 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 401 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 403:

  - `403` (unknown)
    Forbidden

## Response 403 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 403 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 409:

  - `409` (unknown)
    Conflict

## Response 409 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 409 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 500:

  - `500` (unknown)
    Internal server error

## Response 500 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 500 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 400 examples:

  - `Invalid field value in the request body` (unknown)

## Response 401 examples:

  - `Missing or invalid API key` (unknown)

## Response 403 examples:

  - `Authenticated but not authorized for this action` (unknown)

## Response 409 examples:

  - `Duplicate or state-conflicting action` (unknown)

## Response 500 examples:

  - `Unhandled server fault or downstream processor error` (unknown)