= Customers resource methods =
== Customer creation (POST) ==
To create a new customer the client needs to send a HTTP <code>POST</code> request on the customer collection resource URI <code>https://api.example.com/v1/customers</code> (also see [[Application_Programming_Interface_(API)#Base_URI|Base URI]]), including the associated customer informationsinformation.The service will generate a new customer and responds with a HTTP status code <code>201</code> (Created) on success. The newly created customer URI is returned within the HTTP location header, which can be used by the client to gather informations information about the new customer.
=== Customer creation request message ===
|}
==== Customer creation request message body (Company Customer) ====
{| class="wikitable sortable" style="width: 100%;" id="customer_object"
|-
|string
|yes
|The customer's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|UTF-8 {64}
|
|
|<source lang="javascript">"customerName": "Super-duper Hosting"</source> |-|<code>id</code>|integer|yes|The identification number the newly created customer resource should belong toCustomer Ltd.||@TODO add regex||<source lang="javascript">"belongsToResellerID": 4000001</source>
|-
|object
|yes
|An object holding the billing address informations information for the given customer. Refer to the [[#billingAddress_object|billingAddress object table]] for more informationsinformation.
|
|
|object
|no
|An object holding the shipping address informations information for the given customer. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informationsinformation.
|
|
</source>
|}
{| class="wikitable sortable" style="width: 100%;" id="billingAddress_object"
|-
|+ align="top" style="text-align:left;"|billingAddress Object!Parameter name!Data type!Mandatory!Description!Valid content![http://www.pcre.org/ PCRE]!Default value!Example |-|<code>organizationNameexternalID</code>
|string
|no
|The name of An optional external ID the organizationcustomer belongs to (is used for the mapping to external databases).
|
|@TODO: Add add regex
|
|<source lang="javascript">"organizationNameexternalID": "Customer Ltd."12345</source>
|-
|<code>gender</code>|string|yes|The gender of the address holder|Either <code>f</code> for female, <code>m</code> for male or <code>n</code> for neutral.|||<source lang="javascript">"gender": "f"</source> |-|<code>givenName</code>|string|yes|The given name (first name or forename) of the address holder.|UTF-8 {64}|@TODO: Add regex||<source lang="javascript">"givenName": "Name"</source> |-|<code>surname</code>|string|yes|The surname (last name or family name) of the address holder.|UTF-8 {64} |@TODO: Add regex||<source lang="javascript">"surname": "Surname"</source> |-|<code>postalAddress</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"postalAddress": ""</source> |-|<code>countryCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"countryCode": ""</source> |-|<code>postalCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"postalCode": ""</source> |-|<code>localityName</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"localityName": ""</source> |-|<code>preferredLanguage</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"preferredLanguage": ""</source> |-|<code>mail</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"mail": ""</source> |-|<code>telephoneNumber</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"telephoneNumber": ""</source> |-|<code>mobileTelephoneNumber</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"mobileTelephoneNumber": ""</source> |-|<code>websiteURL</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"websiteURL": ""</source> |} {| class="wikitable sortable" style="width: 100%;" id="shippingAddress_object"|-|+ align="top" style="text-align:left;"|shippingAddress Object!Parameter name!Data type!Mandatory!Description!Valid content![http://www.pcre.org/ PCRE]!Default value!Example |-|<code>organizationName</code>|string|no|The name of the organization.||@TODO: Add regex||<source lang="javascript">"organizationName": "Customer Ltd."</source> |-|<code>gender</code>|string|yes|The gender of the address holder|Either <code>f</code> for female, <code>m</code> for male or <code>n</code> for neutral.|||<source lang="javascript">"gender": "f"</source> |-|<code>givenName</code>|string|yes|The given name (first name or forename) of the address holder.||@TODO: Add regex||<source lang="javascript">"givenName": "Name"</source> |-|<code>surname</code>|string|yes|The surname (last name or family name) of the address holder.||@TODO: Add regex||<source lang="javascript">"surname": "Surname"</source> |-|<code>postalAddress</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"postalAddress": ""</source> |-|<code>countryCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"countryCode": ""</source> |-|<code>postalCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"postalCode": ""</source> |-|<code>localityName</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"localityName": ""</source> |-|<code>preferredLanguage</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"preferredLanguage": ""</source> |-|<code>mail</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"mail": ""</source> |-|<code>telephoneNumber</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"telephoneNumber": ""</source> |-|<code>mobileTelephoneNumber</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"mobileTelephoneNumber": ""</source> |-|<code>websiteURL</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"websiteURL": ""</source> |} ==== Customer creation request message body (Private Customer) ===={| class="wikitable sortable" style="width: 100%;" id="customer_object"|-|+ align="top" style="text-align:left;"|Customer Object! Parameter name! Data type! Mandatory! Description! Valid content![http://www.pcre.org/ PCRE]! Default value! Example |-|<code>isCompany</code>|boolean|yes|<code>true</code> if the customer represents a company, <code>false</code> if it's an individual person.|<code>true</code> or <code>false</code>|||<source lang="javascript">"isCompany": true</source> |-|<code>isActive</code>|boolean|yes||<code>true</code> or <code>false</code>||<code>true</code>|<source lang="javascript">"isActive": true</source> |-|<code>customerName</code>|string|yes|The customer's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.|UTF-8 {64}|||<source lang="javascript">"customerName": "Super-duper Hosting"</source> |-|<code>idbelongsToResellerID</code>
|integer
|yes
|The reseller identification number the newly created customer resource should must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"belongsToResellerID": 4000001</source> |-|[[#billingAddress_object|<code>billingAddress</code>]]|object|yes|An object holding the billing address informations for the given customer. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.||||<source lang="javascript">"billingAddress":{ "organizationName": "Customer Ltd.", "gender": 'm', "givenName": "Name", "surname": "Surname", "postalAddress": "Street Number", "countryCode": "CH", "postalCode": "1234", "localityName": "Locality", "preferredLanguage": "en-GB", "mail": "name.surname@example.com", "telephoneNumber": "+41 00 000 00 00", "mobileTelephoneNumber": "+41 00 000 00 00", "websiteURL": "https://www.example.com/"}</source> |-|[[#shippingAddress_object|<code>shippingAddress</code>]]|object|no|An object holding the shipping address informations for the given customer. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.||||<source lang="javascript">"shippingAddress":{ "organizationName": "Customer Ltd.", "gender": 'm', "givenName": "Name", "surname": "Surname", "postalAddress": "Street Number", "countryCode": "CH", "postalCode": "1234", "localityName": "Locality", "preferredLanguage": "en-GB", "mail": "name.surname@example.com", "telephoneNumber": "+41 00 000 00 00", "mobileTelephoneNumber": "+41 00 000 00 00", "websiteURL": "https://www.example.com/"}4000000</source>
|}
|object
|no
|In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more informationsinformation.
|
|
"isCompany": true,
"isActive": true,
"customerName": "Customer Ltd."
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern", "belongsToResellerID": 4000000
},
{
|object
|no
|In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more informationsinformation.
|
|
|string
|yes
|The customer's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"customerName": "SuperCustomer Ltd."</source> |-duper Hosting|<code>countryCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"countryCode": "CH"</source> |-|<code>postalCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"postalCode": "3012"</source> |-|<code>localityName</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"localityName": "Bern</source> |-|<code>belongsToResellerID</code>|integer|yes|The reseller identification number the customer resource must belong to.||@TODO add regex||<source lang="javascript">"belongsToResellerID": 4000000</source>
|}
=== Customer element retrieval (GET) ===
To retrieve an existing customer and fetch the informations information associated with it, the client needs to send a HTTP <code>GET</code> request on the customer's element resource URI (such as <code>https://api.example.com/v1/customers/5000001</code>.The service responds with a HTTP status code 200 (OK) on success and returns the associated customer informationsinformation.
==== Customer element retrieval request message ====
|string
|yes
|The customer's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"customerName": "SuperCustomer Ltd."</source> |-duper Hosting|<code>externalID</code>|string|no|An optional external ID the customer belongs to (is used for the mapping to external databases).||@TODO add regex||<source lang="javascript">"externalID": 12345</source> |-|<code>belongsToResellerID</code>|integer|yes|The reseller identification number the customer resource must belong to.||@TODO add regex||<source lang="javascript">"belongsToResellerID": 4000000</source>
|-
|object
|yes
|An object holding the billing address informations information for the given customer. Refer to the [[#billingAddress_object|billingAddress object table]] for more informationsinformation.
|
|
|object
|no
|An object holding the shipping address informations information for the given customer. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informationsinformation.
|
|
}
</source>
|-
|<code>customers</code>
|string
|yes
|The location URI of the customers belonging to this customer resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"customers": "https://api.example.com/v1/customers/5000001/customers"</source>
|-
|object
|no
|In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more informationsinformation.
|
|
==== Customer update response message body ====
On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further informations information about the failure.
== Customer partly update (PATCH) ==
==== Customer partly update response message body ====
On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further informations information about the failure.
== Customer deletion (DELETE) ==
==== Customer deletion response message body ====
On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further informations information about the failure.
== Customer search ==