# Retrieve a Client

Retrieve details of a specific client account.

Endpoint: GET /v1/clients/{clientId}
Version: 1.0.0-beta.54
Security: ApiKeyAuth

## Security:

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

## Path parameters:

  - `clientId` (string, required)

## 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.

## Response 200:

  - `200` (unknown)
    Client details retrieved successfully

## Response 200 fields (application/json):

  - `client_details` (object, required)
    Detailed representation of a client account including audit metadata.

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

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

  - `client_details.user_id` (string | null)
    Identifier of the admin user associated with this client.

  - `client_details.parent_id` (string | null)
    Unique identifier of the parent client account.

  - `client_details.effective` (string | null)
    ISO 8601 timestamp of when the client account became effective.

  - `client_details.expiry` (string | null)
    ISO 8601 timestamp of when the client account expires. Null if no expiry.

  - `client_details.active` (boolean, required)
    Whether the client account is active.

  - `client_details.modified` (string | null)
    ISO 8601 timestamp of the last modification to this record.

  - `client_details.modified_by` (integer | null)
    Internal ID of the user who last modified this record.

  - `client_details.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.

  - `client_details.website` (string | null)
    URL of client website. Null when the client has none — the gateway returns the field rather than omitting it.

  - `client_details.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.

  - `client_details.address` (array | null)
    The client's addresses, one per `type`. Null for a client created before an address was required, which has none on record.

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

  - `client_details.address.line1` (string | null)
    Primary street address line.

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

  - `client_details.address.city` (string | null)
    City name.

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

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

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

  - `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 404:

  - `404` (unknown)
    Not Found

## Response 404 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 404 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)

  - `A required field is absent` (unknown)

  - `The transaction's state does not allow this operation` (unknown)

  - `A single amount is outside the allowed range` (unknown)

  - `A count or dollar cap over a period is spent` (unknown)
    details names the limit: limit_type is COUNT or AMOUNT, window is DAILY or MONTHLY, and scope is ACCOUNT, one payer's bank account, or MERCHANT, everything the merchant submits. A key whose value is not known is left out. No limit figure or reset time is sent.

## Response 401 examples:

  - `Missing or invalid API key` (unknown)

## Response 403 examples:

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

  - `The merchant is not boarded to the processor this transaction routes to` (unknown)
    A card transaction routes to TSYS and an ACH transaction to VeriCheck. Both details keys are always present. The condition lasts until the merchant is boarded, so retrying does not help.

## Response 404 examples:

  - `Resource ID does not exist` (unknown)

## Response 500 examples:

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

  - `The merchant's stored integration record is wrong` (unknown)
    The processor rejected an identifier that came from boarding, not from the request. Retrying does not help until the integration is corrected.

