## Create a customer

`customers.create(**kwargs) -> CustomerV1`

**post** `/v1/customers`

Creates a new customer record and automatically initiates identity, fraud, and risk assessment scores. This endpoint allows you to create a customer profile and associate it with paykeys and payments.

### Parameters

- `device: DeviceUnmaskedV1`

  - `ip_address: String`

    The customer's IP address at the time of profile creation. Use `0.0.0.0` to represent an offline customer registration.

- `email: String`

  The customer's email address.

- `name: String`

  Full name of the individual or business name.

- `phone: String`

  The customer's phone number in E.164 format. Mobile number is preferred.

- `type: :individual | :business`

  - `:individual`

  - `:business`

- `address: CustomerAddressV1`

  An object containing the customer's address. **This is optional.** If used, all required fields must be present.

  - `address1: String`

    Primary address line (e.g., street, PO Box).

  - `city: String`

    City, district, suburb, town, or village.

  - `state: String`

    Two-letter state code.

  - `zip: String`

    Zip or postal code.

  - `address2: String`

    Secondary address line (e.g., apartment, suite, unit, or building).

- `compliance_profile: { dob, ssn} | { ein, legal_business_name, representatives, website}`

  An object containing the customer's compliance profile. **This is optional.** If all required fields must be present for the appropriate customer type.

  - `class IndividualComplianceProfile`

    Individual PII data required to trigger Patriot Act compliant KYC verification.

    - `dob: Date`

      Date of birth (YYYY-MM-DD). Required for Patriot Act-compliant KYC verification.

    - `ssn: String`

      Social Security Number (format XXX-XX-XXXX). Required for Patriot Act-compliant KYC verification.

  - `class BusinessComplianceProfile`

    Business registration data required to trigger Patriot Act compliant KYB verification.

    - `ein: String`

      Employer Identification Number (format XX-XXXXXXX). Required for Patriot Act-compliant KYB verification.

    - `legal_business_name: String`

      Official registered business name as listed with the IRS. This value will be matched against the 'legal_business name'.

    - `representatives: Array[{ name, email, phone}]`

      A list of people related to the company. Only valid where customer type is 'business'.

      - `name: String`

      - `email: String`

      - `phone: String`

    - `website: String`

      Official business website URL. Optional but recommended for enhanced KYB.

- `config: { processing_method, sandbox_outcome}`

  - `processing_method: :inline | :background | :skip`

    - `:inline`

    - `:background`

    - `:skip`

  - `sandbox_outcome: :standard | :verified | :rejected | :review`

    - `:standard`

    - `:verified`

    - `:rejected`

    - `:review`

- `external_id: String`

  Unique identifier for the customer in your database, used for cross-referencing between Straddle and your systems.

- `metadata: Hash[Symbol, String]`

  Up to 20 additional user-defined key-value pairs. Useful for storing additional information about the customer in a structured format.

- `correlation_id: String`

- `idempotency_key: String`

- `request_id: String`

- `straddle_account_id: String`

### Returns

- `class CustomerV1`

  - `data: { id, created_at, email, 11 more}`

    - `id: String`

      Unique identifier for the customer.

    - `created_at: Time`

      Timestamp of when the customer record was created.

    - `email: String`

      The customer's email address.

    - `name: String`

      Full name of the individual or business name.

    - `phone: String`

      The customer's phone number in E.164 format.

    - `status: :pending | :review | :verified | 2 more`

      - `:pending`

      - `:review`

      - `:verified`

      - `:inactive`

      - `:rejected`

    - `type: :individual | :business`

      - `:individual`

      - `:business`

    - `updated_at: Time`

      Timestamp of the most recent update to the customer record.

    - `address: CustomerAddressV1`

      An object containing the customer's address. This is optional, but if provided, all required fields must be present.

      - `address1: String`

        Primary address line (e.g., street, PO Box).

      - `city: String`

        City, district, suburb, town, or village.

      - `state: String`

        Two-letter state code.

      - `zip: String`

        Zip or postal code.

      - `address2: String`

        Secondary address line (e.g., apartment, suite, unit, or building).

    - `compliance_profile: { dob, ssn} | { ein, legal_business_name, representatives, website}`

      PII required to trigger Patriot Act compliant KYC verification.

      - `class IndividualComplianceProfile`

        PII required to trigger Patriot Act compliant KYC verification.

        - `dob: Date`

          Masked date of birth in ****-**-** format.

        - `ssn: String`

          Masked Social Security Number in the format ***-**-*\***.

      - `class BusinessComplianceProfile`

        Business registration data required to trigger Patriot Act compliant KYB verification.

        - `ein: String`

          Masked Employer Identification Number in the format **-**\*****

        - `legal_business_name: String`

          The official registered name of the business. This name should be correlated with the `ein` value.

        - `representatives: Array[{ name, email, phone}]`

          A list of people related to the company. Only valid where customer type is 'business'.

          - `name: String`

          - `email: String`

          - `phone: String`

        - `website: String`

          Official business website URL. Optional but recommended for enhanced KYB.

    - `config: { processing_method, sandbox_outcome}`

      - `processing_method: :inline | :background | :skip`

        - `:inline`

        - `:background`

        - `:skip`

      - `sandbox_outcome: :standard | :verified | :rejected | :review`

        - `:standard`

        - `:verified`

        - `:rejected`

        - `:review`

    - `device: { ip_address}`

      - `ip_address: String`

        The customer's IP address at the time of profile creation. Use `0.0.0.0` to represent an offline customer registration.

    - `external_id: String`

      Unique identifier for the customer in your database, used for cross-referencing between Straddle and your systems.

    - `metadata: Hash[Symbol, String]`

      Up to 20 additional user-defined key-value pairs. Useful for storing additional information about the customer in a structured format.

  - `meta: ResponseMetadata`

    Metadata about the API request, including an identifier and timestamp.

    - `api_request_id: String`

      Unique identifier for this API request, useful for troubleshooting.

    - `api_request_timestamp: Time`

      Timestamp for this API request, useful for troubleshooting.

  - `response_type: :object | :array | :error | :none`

    Indicates the structure of the returned content.

    - "object" means the `data` field contains a single JSON object.
    - "array" means the `data` field contains an array of objects.
    - "error" means the `data` field contains an error object with details of the issue.
    - "none" means no data is returned.

    - `:object`

    - `:array`

    - `:error`

    - `:none`

### Example

```ruby
require "straddle"

straddle = Straddle::Client.new(
  api_key: "My API Key",
  environment: "production" # defaults to "sandbox"
)

customer_v1 = straddle.customers.create(
  device: {ip_address: "192.168.1.1"},
  email: "ron.swanson@pawnee.com",
  name: "Ron Swanson",
  phone: "+12128675309",
  type: :individual
)

puts(customer_v1)
```

#### Response

```json
{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "created_at": "2019-12-27T18:11:19.117Z",
    "email": "ron.swanson@pawnee.com",
    "name": "Ron Swanson",
    "phone": "+12128675309",
    "status": "pending",
    "type": "individual",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "address": {
      "address1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "12345",
      "address2": "Apt 1"
    },
    "compliance_profile": {
      "dob": "2019-12-27",
      "ssn": "***-**-****"
    },
    "config": {
      "processing_method": "inline",
      "sandbox_outcome": "standard"
    },
    "device": {
      "ip_address": "192.168.1.1"
    },
    "external_id": "external_id",
    "metadata": {
      "foo": "string"
    }
  },
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z"
  },
  "response_type": "object"
}
```