Api/Customers/save creates or updates one customer.

What you need to do before

If you need to change existing customer, you need customer id or externalId.
Call getFields to get customer data

API user must have customer module enabled, otherwise it gets error no permissions.

Setting up customers

If you want to update customers by ExternalId, you need one column, what has system type "ID".
If you want to refer customers with name, you need one column, what has system type "name".

Syntax

Api/Customers/save (id | externalId, location, fields)

id: unique database number of that customer
externalId: unique customer identificator defined by user. This may be some unique string or number in third party service, and can be used to refer to unique customers. See separate chapter for using it together with id.
location: JSON array, what may contain following keys:
- name of customer
- latitude, longitude: world coordinates in format D.DDD
- rawaddress: textual address, what is turned into coordinates using geocoding
fields: other custom fields in JSON format, where keys are numeric strings taken from getFields response.

ID and externalId

Here is overview, what happens, if you leave one of them empty or fill it.

ID/CustomerId	missing	filled
missing	create new customer	try to update existing customer with that externalId, and create new customer, if no such customer is found
filled	update customer with specified Id	Update customer with given ID and change CustomerId to specified value

Location

name parameter sets value to column, what has system type name.

Here is one example of JSON:

{
"name":"Name-for-some-good-customer",
"rawaddress":"fancy address of where that customer lives"
}

Fields

getFields gives list of field id-s with names and definitions. Those ID-s must be used in JSON fields here.

Suppose that we got following fields:

xml:

<?xml version="1.0" encoding="utf-8" ?>
<nodes>
  <status>0</status>
  <meta></meta>
  <response>
    <fields>
      <field>
        <id>35467</id>
        <type>id</type>
        <name>id</name>
      </field>
      <field>
        <id>33096</id>
        <type>name</type>
        <name>name</name>
      </field>
      <field>
        <id>33097</id>
        <type>address-1</type>
        <name>address</name>
      </field>
      <field>
        <id>33098</id>
        <type>phone</type>
        <name>phone</name>
      </field>
      <field>
        <id>33099</id>
        <type>link</type>
        <name>website</name>
      </field>
    </fields>
  </response>
</nodes>

json:

{
"status":0,
"meta":{},
"response":{
  "fields":{
    "___xmlNodeValues":[{
        "___xmlNodeName":"field",
        "field":{
          "id":35467,
          "type":"id",
          "name":"id"
        }
      },{
        "___xmlNodeName":"field",
        "field":{
          "id":33096,
          "type":"name",
          "name":"name"
        }
      },{
        "___xmlNodeName":"field",
        "field":{
          "id":33097,
          "type":"address-1",
          "name":"address"
        }
      },{
        "___xmlNodeName":"field",
        "field":{
          "id":33098,
          "type":"phone",
          "name":"phone"
        }
      },{
        "___xmlNodeName":"field",
        "field":{
          "id":33099,
          "type":"link",
          "name":"website"
        }
      }]
  }
}
}

id	35467	33096	33097	33098	33099
type	id	name	address-1	phone	link
name	id	name	address	phone	website

Fields JSON value is following:

{
"35467":"externalId-value",
"33096":"company-name",
"33097":"company-address-in-text-format",
"33098":"+some_number",
"33099":"http://some-website"
}

Skipping fields with system types

Some system fields are covered with other parameters, so it's recommended to use those parameters instead:

field type	use this parameter instead
id	externalId
name	location:name
address-x	location:rawaddress
latitude	location:latitude
longitude	location:longitude

so previous example shrinks into something like this:

externalId=unique-identifier&
location={
  "name":"company-name",
  "rawaddress":"company-address-in-text-format"
}&fields={
  "33098":"+some_number",
  "33099":"http://some-website"}

But remember: for name and externalId, system still needs field, where to save that data, so don't remove those columns from field descriptions.

Examples

Create new customer

Simplest way, what actually creates customer with name and geocoded address, is just use location parameter:

Api/Customers/save?
  externalId=12345678&
  location={"name":"Company AS","rawaddress":"Kastani 42, Tartu"}

Creating with fields

Api/Customers/save?
  fields={"33096":"Company AS",
          "33097":"Kastani 42, Tartu",
          "33098":"+37256789012",
          "33099":"https://company.ee",
          "35467":"12345678"}

Note that creating user only with fields does not guarantee, that it is geocoded, even if address-related fields are filled. Use location parameter for setting name and location, and other fields for setting additional data, so more preferred form for previous call is following:

Api/Customers/save?
 externalId=12345678&
 location={"name":"Company AS","rawaddress":"Kastani 42, Tartu"}&
 fields={"33098":"+37256789012",
 "33099":"https://company.ee"}

Changing address for existing customer

Api/Customers/Save?
  externalId=12345678&
  location={"rawaddress":"Kuperjanovi 44, Tartu"}