(Quick Reference) Service: Create a customer

Description: Returns the created customer in json format when successful. Returns a json response, describing the failure condition when unsuccessful.

URL:

https://BASE_URL/api/VERSION/customers

Method: POST

Request content type: application/x-www-form-urlencoded or multipart/form-data

Parameters:

NameDescriptionTypeRequiredExample values
reference Stringyes 
name Stringyes 
reference2 Stringno 
barcode Stringno 
isActiveBy default, it is set to trueBooleannotrue, false
categoryIdThe ID of the customer category. By default, if this parameter is not specified, customer will be added to the root customer category.Long/String- 
isSubCustomerBy default, it is equal to falseBooleannotrue, false
parentCustomerIdentifier of parent customer. Required if isSubCustomer is equal to trueLong/String- 
billWithParentBy default, it is equal to false.Booleanno 
customerSegmentationId Long/String- 
userIduser who created the customerLong/String- 
isSameAddressIf shipping address is the same as billing address.By default, this parameter is equal to true.Booleanno 
billingCountryISO county code or country name of billingStringnoFR, France
billingCityBilling cityStringno 
billingPostalCodeBilling postal codeStringno 
billingAddressBilling addressStringno 
billingLatBilling latitudeDoubleno 
billingLngBilling longitudeDoubleno 
countryISO county code or country name of shippingStringnoFR, France
cityShipping cityStringno 
postalCodeShipping postal codeStringno 
addressShipping addressStringno 
latitudeShipping latitudeDoubleno 
longitudeShipping longitudeDoubleno 
email Stringno 
phone Stringno 
mobile Stringno 
fax Stringno 
comment Stringno 
website Stringno 
creditLimit Doubleno 
dueDateConfigNumberNumber of daysIntegerrequired if dueDateConfigType is specified 
dueDateConfigTypeShould be equal to 1 if "after the invoice date" or 2 if "after the end of the invoice month"Stringno1 or 2
taxNumberTax / VAT numberStringno 
companyRegistrationNumberCompany registration numberStringno 
currencyISO code of configured currency(with exchange rate). By default, it is set as the organization currency.StringnoEUR
imageFileImage can be in jpg, gif, png or bmp formatMultipartno 
paymentTypeslist of the id of payment typeJSON structurenopaymentTypes=[{"id"=7},{"id"=8}]
regionIdthe numeric value of the region's IDLongno 
customerRisk Stringno 
customerRiskColor Stringno#FFFFFF, #1BE9D8
onHoldBy default, it is set to falseBooleannotrue, false
onHoldReason Stringno 
useExternalIdBy default, it is set to false. set it to true if you want to use external ids.Booleannotrue , false

Reference must be unique
Region is used only if geographical locations is activated, it should be at the same level as the configured level in organization, or below (sub-levels).

Success Output

Success case: response.status=201

{
  "id": 256,
  "reference": "NC-3",
  "reference2": null,
  "name": "Marie's Jewelry",
  "categoryReference": "jewelry",
  "customerCategory": {
    "id": 2,
    "reference": "jewelry",
    "name": "Jewelry and accessories",
    "href": "/api/v1.0/customerCategories/2"
  },
  "isSubCustomer": false,
  "parentCustomer": null,
  "billWithParent": true,
  "customerSegmentationReference": "seg_a",
  "customerSegmentation": {
    "id": 1,
    "reference": "seg_a",
    "name": "Segmentation A",
    "href": "/api/v1.0/customerSegmentations/1"
  },
  "pocTenus": null,
  "email": null,
  "logo": "BASE_URL/entity1-1450169988465/photoCustomer/1471338230737_logo_color_272x92dp.png",
  "phone": null,
  "mobile": null,
  "fax": null,
  "comment": null,
  "barcode": null,
  "isSameAddress": true,
  "billingCountry": "FR",
  "billingCity": "Nice",
  "billingPostalCode": null,
  "billingAddress": null,
  "billingLat": null,
  "billingLng": null,
  "country": null,
  "city": null,
  "postalCode": null,
  "address": null,
  "latitude": null,
  "longitude": null,
  "isCredit": null,
  "creditLimit": 5000,
  "balance": null,
  "maxChequePeriod": null,
  "maxChequeValue": null,
  "appliedCashBackOutput": null,
  "returnDiscount": null,
  "invoicesPerRoute": null,
  "isActive": true,
  "onHold": false,
  "onHoldReason": null,
  "paymentTerm": null,
  "createdBy": {
    "userId": 2,
    "reference": "emp-002",
    "href": "/api/v1.0/users/2"
  },
  "dueDateConfigNumber": 7,
  "dueDateConfigType": "daysAfterInvoiceDate",
  "paymentTypes": [
    {
      "id": 7,
      "reference": "cash",
      "name": "cash",
      "href": "/api/v1.0/paymentTypes/7"
    },
    {
      "id": 8,
      "reference": "cheque",
      "name": "cheque",
      "href": "/api/v1.0/paymentTypes/8"
    }
  ],
  "website": null,
  "taxNumber": null,
  "companyRegistrationNumber": null,
  "contacts": [],
  "currency": "USD",
  "customerRisk": null,
  "customerRiskColor": null,
  "organization": "entity1",
  "dateCreated": "2015-12-17T23:00:00Z",
  "lastUpdated": "2015-12-17T23:00:00Z",
  "region": {
    "id": 3,
    "name": "New York",
    "href": "/api/v1.0/regions/3"
  }
}

To get resized images, add prefix small_ or medium_ to the link url before the image's name, for example:
<BASE_URL>/entity1-1450169988465/photoCustomer/small_471338230737_logo_color_272x92dp.png

Failure Output

Failure case:response.status = 400

{
	"error": "missing_param",
	"error_description": "reference parameter is missing"
}
{
	"error": "not_unique",
 	"error_description": "reference already used"
}
{
	"error":"invalid_param_type",
 	"error_description": "The type of parameter payment type id you provided is not valid for this request."
}
{
  	"error": "save_failed",
  	"error_description": "Failed to save instance."
}
{
	"error": "exceeded_file_size",
	"error_description": "image size should not exceed 2Mo"
}
{
	"error": "unsupported_file_type",
 	"error_description": "image format not supported."
}

Failure case:response.status = 404

{
	"error":"not_found",
 	"error_description": "The payment type with the id 999 doesn't exist."
}

{
  "error": "not_found",
  "error_description": "The currency with name GmBP doesn't exist."
}

{
  "error": "not_found",
  "error_description": "The currency with name GBP is not configured."
}

{
    "error": "not_found",
    "error_description": "The parent customer with the id 188911 doesn't exist."
}
Failure case:response.status = 500

{
	"error": "server_error",
	"error_description": "Oops! Something went wrong..."
}