## Create a customer

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

### Header Parameters

- `"Correlation-Id": optional string`

- `"Idempotency-Key": optional string`

- `"Request-Id": optional string`

- `"Straddle-Account-Id": optional string`

### Body 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" or "business"`

  - `"individual"`

  - `"business"`

- `address: optional 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: optional string`

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

- `compliance_profile: optional object { dob, ssn }  or object { 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.

  - `IndividualComplianceProfile = object { dob, ssn }`

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

    - `dob: string`

      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.

  - `BusinessComplianceProfile = object { ein, legal_business_name, representatives, website }`

    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: optional array of object { name, email, phone }`

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

      - `name: string`

      - `email: optional string`

      - `phone: optional string`

    - `website: optional string`

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

- `config: optional object { processing_method, sandbox_outcome }`

  - `processing_method: optional "inline" or "background" or "skip"`

    - `"inline"`

    - `"background"`

    - `"skip"`

  - `sandbox_outcome: optional "standard" or "verified" or "rejected" or "review"`

    - `"standard"`

    - `"verified"`

    - `"rejected"`

    - `"review"`

- `external_id: optional string`

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

- `metadata: optional map[string]`

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

### Returns

- `CustomerV1 = object { data, meta, response_type }`

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

    - `id: string`

      Unique identifier for the customer.

    - `created_at: string`

      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" or "review" or "verified" or 2 more`

      - `"pending"`

      - `"review"`

      - `"verified"`

      - `"inactive"`

      - `"rejected"`

    - `type: "individual" or "business"`

      - `"individual"`

      - `"business"`

    - `updated_at: string`

      Timestamp of the most recent update to the customer record.

    - `address: optional 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: optional string`

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

    - `compliance_profile: optional object { dob, ssn }  or object { ein, legal_business_name, representatives, website }`

      PII required to trigger Patriot Act compliant KYC verification.

      - `IndividualComplianceProfile = object { dob, ssn }`

        PII required to trigger Patriot Act compliant KYC verification.

        - `dob: string`

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

        - `ssn: string`

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

      - `BusinessComplianceProfile = object { ein, legal_business_name, representatives, website }`

        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: optional array of object { name, email, phone }`

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

          - `name: string`

          - `email: optional string`

          - `phone: optional string`

        - `website: optional string`

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

    - `config: optional object { processing_method, sandbox_outcome }`

      - `processing_method: optional "inline" or "background" or "skip"`

        - `"inline"`

        - `"background"`

        - `"skip"`

      - `sandbox_outcome: optional "standard" or "verified" or "rejected" or "review"`

        - `"standard"`

        - `"verified"`

        - `"rejected"`

        - `"review"`

    - `device: optional object { 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: optional string`

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

    - `metadata: optional map[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: string`

      Timestamp for this API request, useful for troubleshooting.

  - `response_type: "object" or "array" or "error" or "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

```http
curl https://sandbox.straddle.com/v1/customers \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $STRADDLE_API_KEY" \
    -d '{
          "device": {
            "ip_address": "192.168.1.1"
          },
          "email": "ron.swanson@pawnee.com",
          "name": "Ron Swanson",
          "phone": "+12128675309",
          "type": "individual",
          "external_id": "customer_123"
        }'
```

#### 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"
}
```