# CreateCustomers

Create customers for this company

`POST /api/v2/companies/{companyId}/customers`

**API:** AvaTax API
**Tag:** Customers
**API Version:** v2
**Base URL:** https://sandbox-rest.avatax.com/
**Content-Type:** `application/json`
**Accepts:** `application/json`
**Authentication:** API Key (`Authorization` in header) or OAuth 2.0 or Basic (username + license key)

Source: https://developer.avalara.com/products/crossborder/api/methods/Customers/CreateCustomers/

## Description

Create one or more customers for this company.
            
A customer object defines information about a person or business that purchases products from your
company.  When you create a tax transaction in AvaTax, you can use the `customerCode` from this
record in your `CreateTransaction` API call.  AvaTax will search for this `customerCode` value and
identify any certificates linked to this `customer` object.  If any certificate applies to the transaction,
AvaTax will record the appropriate elements of the transaction as exempt and link it to the `certificate`.
            
A nested object such as CustomFields could be specified and created along with the customer object. To fetch the
nested object, please call 'GetCustomer' API with appropriate $include parameters.
            
Before you can use any exemption certificates endpoints, you must set up your company for exemption certificate data storage.
Companies that do not have this storage system set up will see `CertCaptureNotConfiguredError` when they call exemption
certificate related APIs. To check if this is set up for a company, call `GetCertificateSetup`.  To request setup of exemption
certificate storage for this company, call `RequestCertificateSetup`.

### Security Policies

* This API requires one of the following user roles: AccountAdmin, AccountOperator, AccountUser, AvaTaxOnlyAccountAdmin, AvaTaxOnlyAccountUser, AvaTaxOnlyCompanyAdmin, AvaTaxOnlyCompanyUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPTester, SSTAdmin, TechnicalSupportAdmin.
* This API depends on the following active services:*Required* (all):  AvaTaxPro, ECMEssentials, ECMPro, ECMPremium, VEMPro, VEMPremium, ECMProComms, ECMPremiumComms.

## Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `companyId` | integer | path | Yes | The unique ID number of the company that recorded this customer |
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/) . |

## Request Body

**Schema:** `CustomerModel[]`

Represents a customer to whom you sell products and/or services.

| Property | Type | Required | Description |
|---|---|---|---|
| `id` | integer | No | The unique ID number of this customer. |
| `companyId` | integer | **Yes** | The unique ID number of the AvaTax company that recorded this customer. Example: `0`. |
| `customerCode` | string | **Yes** | The unique code identifying this customer.  Must be unique within your company.
            
This code should be used in the `customerCode` field of any call that creates or adjusts a transaction
in order to ensure that all exemptions that apply to this customer are correctly considered.
            
Note: This field is case sensitive. Example: `d2425ec5-0e8c-4d1c-bed1-4614e039e282`. |
| `alternateId` | string | No | A customer-configurable alternate ID number for this customer.  You may set this value to match any
other system that would like to reference this customer record. Example: `987654321`. |
| `name` | string | **Yes** | A friendly name identifying this customer. Example: `Dr. Bob Example`. |
| `attnName` | string | No | Indicates the "Attn:" component of the address for this customer, if this customer requires mailings to be shipped
to the attention of a specific person or department name. Example: `Attn: Receiving`. |
| `line1` | string | **Yes** | First line of the street address of this customer. Example: `645 Main Street`. |
| `line2` | string | No | Second line of the street address of this customer. |
| `city` | string | **Yes** | City component of the street address of this customer. Example: `Irvine`. |
| `postalCode` | string | **Yes** | Postal Code / Zip Code component of the address of this customer. Example: `92614`. |
| `phoneNumber` | string | No | The main phone number for this customer. Example: `(949) 555-1212`. |
| `faxNumber` | string | No | The fax phone number for this customer, if any. Example: `949.555.1213`. |
| `emailAddress` | string | No | The main email address for this customer. Example: `dr.bob.example@example.org`. |
| `contactName` | string | No | The name of the main contact person for this customer. Example: `Alice Smith`. |
| `lastTransaction` | string | No | Date when this customer last executed a transaction. Example: `2008-10-08T00:00:00Z`. |
| `createdDate` | string | No | The date when this record was created. |
| `modifiedDate` | string | No | The date/time when this record was last modified. |
| `country` | string | **Yes** | Name or ISO 3166 code identifying the country.
            
This field supports many different country identifiers:
 * Two character ISO 3166 codes
 * Three character ISO 3166 codes
 * Fully spelled out names of the country in ISO supported languages
 * Common alternative spellings for many countries
            
For a full list of all supported codes and names, please see the Definitions API `ListCountries`. Example: `US`. |
| `region` | string | No | ISO 3166 code identifying the region within the country.
Two and three character ISO 3166 region codes.
This is a required field if the country is US or CA. For other countries, this is an optional field.
For a full list of all supported codes, please see the Definitions API `ListRegions`. Example: `CA`. |
| `isBill` | boolean | No | True if this customer record is specifically used for bill-to purposes. |
| `isShip` | boolean | No | True if this customer record is specifically used for ship-to purposes. |
| `taxpayerIdNumber` | string | No | For customers in the United States, this field is the federal taxpayer ID number.  For businesses, this is
a Federal Employer Identification Number.  For individuals, this will be a Social Security Number. |
| `certificates` | CertificateModel[] | No | A list of exemption certficates that apply to this customer.  You can fetch this data by specifying
`$include=certificates` when calling a customer fetch API. |
| `customFields` | CustomFieldModel[] | No | A list of custom fields defined on this customer.
            
For more information about custom fields, see the [Avalara Help Center article about custom fields](https://help.avalara.com/0021_Avalara_CertCapture/All_About_CertCapture/Edit_or_Remove_Details_about_Customers). |
| `exposureZones` | ExposureZoneModel[] | No | A list of exposure zones where you do business with this customer.
            
To keep track of certificates that are needed for each customer, set this value to a list of all exposure zones where you
sell products to this customer.  You can find a list of exposure zones by calling `ListExposureZones`.
            
This field is often called "Ship-To States" or "Ship-To Zones", since it generally refers to locations where you ship products
when this customer makes a purchase.
            
This field is useful for audit purposes since it helps you ensure you have the necessary certificates for each customer. |
| `billTos` | CustomerModel[] | No | A list of bill-to customer records that are connected to this ship-to customer.
            
Customer records represent businesses or individuals who can provide exemption certificates.  Some customers
may have certificates that are linked to their shipping address or their billing address.  To group these
customer records together, you may link multiple bill-to and ship-to addresses together to represent a single
entity that has multiple different addresses of different kinds. |
| `shipTos` | CustomerModel[] | No | A list of ship-to customer records that are connected to this bill-to customer.
            
Customer records represent businesses or individuals who can provide exemption certificates.  Some customers
may have certificates that are linked to their shipping address or their billing address.  To group these
customer records together, you may link multiple bill-to and ship-to addresses together to represent a single
entity that has multiple different addresses of different kinds. |
| `attributes` | CustomerAttributeModel[] | No | A list of attributes that apply to this customer.
            
You can fetch this data by specifying `$include=attributes` when calling a customer fetch API. |
| `activeCertificates` | ActiveCertificateModel[] | No | A list of active certificates with exemption reasons. |
| `histories` | HistoryModel[] | No | A list of field update histories for this customer. |
| `logs` | CertificateLogModel[] | No | A list of logs for this customer. |
| `shipToStates` | StateModel[] | No | A list of states where this customer ships to. |

## Responses

| Status | Description | Schema |
|---|---|---|
| 200 | Success |  |
| 400 | Bad Request | `ProblemDetails` |
| 401 | Unauthorized | `ProblemDetails` |
| 404 | Not Found | `ProblemDetails` |

## Example Request

```bash
curl -X POST "https://sandbox-rest.avatax.com/api/v2/companies/{companyId}/customers" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '[
  {
    "companyId": 0,
    "customerCode": "d2425ec5-0e8c-4d1c-bed1-4614e039e282",
    "alternateId": "987654321",
    "name": "Dr. Bob Example",
    "attnName": "Attn: Receiving",
    "line1": "645 Main Street",
    "city": "Irvine",
    "postalCode": "92614",
    "phoneNumber": "(949) 555-1212",
    "faxNumber": "949.555.1213",
    "emailAddress": "dr.bob.example@example.org",
    "contactName": "Alice Smith",
    "lastTransaction": "2008-10-08T00:00:00Z",
    "country": "US",
    "region": "CA",
    "exposureZones": [
      {
        "name": "Washington"
      }
    ]
  }
]'
```