# Create a sub-account

URL: https://docs.sparklayer.io/ignite/api/create-a-new-customer-sub-account
Operation: `POST /v1/{siteEnv}/{siteId}/sub-accounts` (operationId `createSubAccount`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Create a new "customer" on the eCommerce platform and designates it as a sub-account with `parent_customer_id` as an attribute.
The implementation should explicitly handle the possibility that a customer with the supplied email address already exists and return a 400 response as documented.
If the target platform has the ability to send an activation / invitation email to the new customer then this should be done.

`POST /v1/{siteEnv}/{siteId}/sub-accounts`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
POST /v1/live/bobs-store/sub-accounts HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "email": "bob@sparklayer.io",
  "first_name": "Bob",
  "last_name": "Jones",
  "parent_customer_external_id": "CU1234",
  "role": "limited-customer"
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | Yes | |
| `first_name` | string | Yes | Length: min 1, max 128. |
| `last_name` | string | Yes | Length: min 1, max 128. |
| `parent_customer_external_id` | string | Yes | Parent Customer ID of the Customer |
| `role` | string \| null | | A role that represents the users permissions |

```json
{
  "email": "bob@sparklayer.io",
  "first_name": "Bob",
  "last_name": "Jones",
  "parent_customer_external_id": "CU1234",
  "role": "limited-customer"
}
```

### Responses your service returns

#### 201: Successful operation

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_external_id` | string | | Platform ID of Customer |

```json
{
  "customer_external_id": "CU1234"
}
```

#### 400: Error handling request such as email already taken

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error_code` | "email-already-taken" | | Machine-readable error code such as email already taken |

```json
{
  "error_code": "email-already-taken"
}
```

#### 401: Auth Failure

#### 500: System Exception