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
orexternalId
. - 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 customerexternalId
: 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 fromgetFields
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"}