save

Follow

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"}

 

Was this article helpful?
0 out of 0 found this helpful