This document outlines the purpose, technology, use cases, methods, objects and examples for using the Customers API.
This document focuses on the SOAP interface to this API.
The Customers API provides programmatic access to the customer database and allows for control and maintenance of customer data within the system.
The Customers API exposes two primary native interfaces via .NET and SOAP.
Full documentation for this interface is available in the API Reference.
This section documents the SOAP interface to the API.
The SOAP API endpoint for any system is located at https://[siteurl]/global/api/customers.asmx
This endpoint is enabled for access via SOAP as well as HTTP GET and POST. The Service Description is also available directly via this endpoint.
Note: For systems with satellite sites, the API will be available only under the primary site URL.
The Customers API via SOAP uses the Permissions System to allow and deny access to users. Use of the API requires a user to be granted the various actions (under iSAMS / API / Customers) to be able to authenticate and perform the various actions available under this API.
The Customers API supports password protection through a number of common hashing algorithms as well as plaintext passwords. In general, any customer passwords submitted to the Customers API should be in plaintext, and the API will hash the password if and as required. However, if your passwords are protected with an unsupported hash algorithm, you will need to submit passwords in their hashed forms. This API does not currently support encrypted passwords.
The following hashing algorithms are supported:
The value of the Protected field on a Customer object determines how the Customers API handles customer passwords when creating or updating a customer.
If Protected is false, then the customer's Password is assumed to be in plaintext and will be protected according to the site's password policy (note that this may mean the password is left as plaintext).
If Protected is true, then the customer's Password is assumed to have already been protected according to the site's password policy and will be stored with no modifications.
If a customer's Password field is left blank during an update, then the customer's password will be left unchanged (for existing customers) or will have a random password created (for new customers).
It is up to the caller to ensure these attributes are set correctly for customer data updates.
Note: Plaintext customer passwords will never be returned in any bulk export.
Protected passwords are included in the XML and JSON bulk exports. Customer passwords (whether protected or plaintext) will never be included in the CSV bulk export.
Error handling is primarily left to the caller. Any methods that return an ApiResponse object will provide additional details that can be used to assist when debugging problems.
Where a "Call Identifier" is returned in the Message field of the ApiResponse, then a full exception trace will be available from http://[siteurl]/logs/api/{Call Identifier}.txt
Available methods are listed below.
Available objects are listed below.
Customers API usage examples are available. These examples demonstrate the use of the API via a SOAP interface and are available in C# and Java.
See Authenticate.
Lists the Customer IDs of all customers present in the system.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
Returns an IntegerArrayApiResponse containing the Customer IDs of all customers present in the system.
Lists the Customer IDs of all customers in the specified interest group.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| interestGroup | String | The name of the interest group to return customers for. |
Returns an IntegerArrayApiResponse containing the Customer IDs of all customers in the specified interest group.
Lists the Customer IDs of all customers matching the specified search term(s).
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| String | Customer email address search term. | |
| name | String | Customer name search term. |
| foreignIdentity | String | Customer foreign identity search term. |
| shippingAddress | String | Customer shipping address search term. |
| shippingCountry | String | Customer shipping country search term. |
| billingAddress | String | Customer billing address search term. |
| billingCountry | String | Customer billing country search term. |
Returns an IntegerArrayApiResponse containing the Customer IDs of all customers matching the specified search terms.
This method will return the Customer IDs of all customers with details matching the input search terms. Results are based on all or part of the individual search terms matching the appropriate customer data.
Where more than one search term is provided, the results will be filtered on all provided search terms.
The name search term will return results based on the customer's first and last names, combined and separated by a space.
The shippingAddress and billingAddress search terms will return results based on the customer's combined street, suburb, city, postcode, state, and extra information address fields, separated by spaces in that order.
The shippingCountry and billingCountry search terms should be standard three-letter country codes (e.g. 'NZL' for 'New Zealand').
Empty, null, or all-whitespace search terms are ignored when filtering results, with the exception of foreignIdentity (where an empty or all-whitespace search term will return all customers with no assigned foreign identity).
Lists the Customer IDs of all customers created in the specified date range.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| startDate | DateTime | The start of the date range (inclusive). |
| endDate | DateTime | The end of the date range (inclusive). |
Returns an IntegerArrayApiResponse containing the Customer IDs of all customers created in the specified date range.
Times must be supplied in UTC.
Lists the Customer IDs of all customers modified in the specified date range.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| startDate | DateTime | The start of the date range (inclusive). |
| endDate | DateTime | The end of the date range (inclusive). |
Returns an IntegerArrayApiResponse containing the Customer IDs of all customers modified in the specified date range.
Times must be supplied in UTC.
Retrieves a customer using the provided Customer ID.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customerID | Integer | Customer ID of the customer to retrieve. |
Returns a CustomerApiResponse containing a Customer object for the supplied Customer ID as the sole entry in the CustomerApiResponse.Data array.
Retrieves a set of customers using the Customer IDs provided.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customerIDs | Integer[] | Customer IDs of the customers to retrieve. |
Returns a CustomerApiResponse containing an array of Customer objects for the supplied Customer IDs in the CustomerApiResponse.Data field.
Adds or updates a single customer.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customer | Customer | Customer to add or update. |
Returns an ApiReponse indicating the outcome of the call.
This method is used to both add new and update existing customers. Customers will be added or updated based on their Customer ID. New customers will only be created if their ID field is 0 (zero).
Any fields in the Customer (and associated objects) with lengths longer than the maximum length for that field will be silently truncated. See the individual object documentation for maximum field lengths.
Input fields with invalid values will use default values for new customers and leave the field unchanged for existing customers.
See Password Requirements for information on how passwords are handled in the Customers API.
Adds or updates a set of customers.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customers | Customer[] | Customers to add or update. |
Returns an ApiReponse indicating the outcome of the call.
This method functions much like UpdateCustomer, but allows for adding and updating multiple customers at once.
Customers can both be created and updated in the same method call. There is no need to make separate calls to create some customers and update others.
Calling this method once with multiple customers is more efficient than calling UpdateCustomer once for each of those customers.
Deletes a single customer.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customerID | Integer | Customer ID of the customer to delete. |
Returns an ApiReponse indicating the outcome of the call.
Deleting a customer is permanent and cannot be undone.
Deletes a set of customers.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customerIDs | Integer[] | Customer IDs of the customers to delete. |
Returns an ApiReponse indicating the outcome of the call.
This method functions much like DeleteCustomer, but allows for deleting multiple customers at once.
Retrieves a URL that can be used by a customer to reset their password.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customerID | Integer | Customer ID of the customer whose password is to be reset. |
| websiteID | Integer | Website ID of the website the customer will use to reset their password. |
Returns an NVPApiReponse indicating the outcome of the call and containing data necessary to allow a customer to reset their password.
If a password reset URL cannot be generated for a customer for any reason, the operation will fail with a response code of 2000 (invalid data).
The Data field of the response contains NameValuePairs as follows:
| Name | Value |
|---|---|
| url | The URL a customer needs to visit in order to reset their password. |
| code | A code that the customer must enter in order to reset their password (may be optional - see below). |
Depending on a site's password reset settings, the 'code' may or may not be required. If 'code' is an empty string, then the code is not required to reset the customer's password. If it is populated, the customer will need to enter the supplied code when resetting their password.
Any password reset URL is only valid for one use.
Performs a bulk export of all customer data to a set of CSV/XML/JSON files that can be retrieved via HTTP, with the ability to specify number of records per file, path and file name prefix.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| exportSettings | ApiExportSettings | Settings for file export |
Returns a StringArrayApiResponse indicating the outcome of the call and the filenames of the files generated for the export.
All customers present in the system will be exported.
Passwords (whether hashed, encrypted, or plaintext) will never be exported as part of a CSV bulk export.
This will export all available customer data for ALL customers in the system, and should be used with caution on systems with large numbers of customers.
The CSV file format is available here. A sample of the CSV customer export is available here.
Performs a bulk export of specified customer data to a set of XML files that can be retrieved via HTTP.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customerIDs | Integer[] | Customer IDs of the customers to export. |
Returns a StringArrayApiResponse indicating the outcome of the call and the filenames of the files generated for the export.
The generated files will be retrievable via https://[siteurl]/data/customers/[filename], where [filename] is provided in the API call response.
All available customer data for the customers specified in customerIDs will be exported.
Each individual export file will contain data for no more than 100 customers. If more than 100 customers are present in an export batch, the export will split the exported customers into multiple export files.
A sample of the XML customer export is available here.
Performs a bulk export of all customer data to a set of XML files that can be retrieved via HTTP.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
Returns a StringArrayApiResponse indicating the outcome of the call and the filenames of the files generated for the export.
The generated files will be retrievable via https://[siteurl]/data/customers/[filename], where [filename] is provided in the API call response.
All customers present in the system will be exported.
Each individual export file will contain data for no more than 100 customers. If more than 100 customers are present in an export batch, the export will split the exported customers into multiple export files.
This will export all available customer data for ALL customers in the system, and should be used with caution on systems with large numbers of customers.
A sample of the XML customer export is available here.
Performs a bulk export of specified customer data to a set of JSON files that can be retrieved via HTTP.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customerIDs | Integer[] | Customer IDs of the customers to export. |
Returns a StringArrayApiResponse indicating the outcome of the call and the filenames of the files generated for the export.
The generated files will be retrievable via https://[siteurl]/data/customers/[filename], where [filename] is provided in the API call response.
All available customer data for the customers specified in customerIDs will be exported.
Each individual export file will contain data for no more than 100 customers. If more than 100 customers are present in an export batch, the export will split the exported customers into multiple export files.
A sample of the JSON customer export is available here.
Performs a bulk export of all customer data to a set of JSON files that can be retrieved via HTTP.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
Returns a StringArrayApiResponse indicating the outcome of the call and the filenames of the files generated for the export.
The generated files will be retrievable via https://[siteurl]/data/customers/[filename], where [filename] is provided in the API call response.
All customers present in the system will be exported.
Each individual export file will contain data for no more than 100 customers. If more than 100 customers are present in an export batch, the export will split the exported customers into multiple export files.
This will export all available customer data for ALL customers in the system, and should be used with caution on systems with large numbers of customers.
A sample of the JSON customer export is available here.
Performs a bulk export of specified customer data to a set of CSV files that can be retrieved via HTTP.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customerIDs | Integer[] | Customer IDs of the customers to export. |
Returns a StringArrayApiResponse indicating the outcome of the call and the filenames of the files generated for the export.
The generated files will be retrievable via https://[siteurl]/data/customers/[filename], where [filename] is provided in the API call response.
All available customer data for the customers specified in customerIDs will be exported.
The export file will contain data for ALL customers in ONE file.
Passwords (whether hashed, encrypted, or plaintext) will never be exported as part of a CSV bulk export.
The CSV file format is available here. A sample of the CSV customer export is available here.
Performs a bulk export of all customer data to a set of CSV files that can be retrieved via HTTP.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
Returns a StringArrayApiResponse indicating the outcome of the call and the filenames of the files generated for the export.
The generated files will be retrievable via https://[siteurl]/data/customers/[filename], where [filename] is provided in the API call response.
All customers present in the system will be exported.
The export file will contain data for ALL customers in ONE file.
Passwords (whether hashed, encrypted, or plaintext) will never be exported as part of a CSV bulk export.
This will export all available customer data for ALL customers in the system, and should be used with caution on systems with large numbers of customers.
The CSV file format is available here. A sample of the CSV customer export is available here.
All dates and times are in UTC.
File format for the exported file.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| CSV | int | To export file in CSV format. | Default |
| JSON | int | To export file in JSON format. | |
| XML | int | To export file in XML format. |
Settings for the records to export.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Path | String | Path to save files. | Default path is https://[siteurl]/data/customers/[filename], where [filename] is provided in the API call response. |
| RecordsPerFile | int | Number of records to be exported in one file. | Default is 100 for JSON and XML, unlimited for CSV. |
| Format | ApiExportFormat | File format for the exported file. | |
| FilenamePrefix | String | Prefix for the exported filename. | This can be an alphanumeric value, which will be prefixed to the generated file names.Default is blank. |
If RecordsPerFile value is not passed, the default limit for JSON and XML file formats is 100 customers per file and the export will generate multiple files. The default limit for CSV is unlimited, so all customers will be exported in one file.
Contains basic information about the result of a method call, along with an array of Customer objects.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | |
| Data | Customer[] | Array of Customer objects returned from the method call. |
Represents a Customer.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | Integer | The unique Customer ID of this customer. | This is a read-only field. |
| ForeignIdentity | String (50) | The foreign identity of this customer. | |
| String (100) | The email address of this customer. | ||
| Title | String (10) | The title of this customer. | |
| FirstName | String (50) | The first name of this customer. | |
| LastName | String (50) | The last name of this customer. | |
| Phone | String (50) | The main phone number for this customer. | |
| Fax | String (50) | The fax number for this customer. | |
| Mobile | String (50) | The mobile phone number for this customer. | |
| Password | String (70) | This customer's password. | See Password Requirements for more information on password handling within the Customer API. |
| Protected | Boolean | Indicates whether the supplied password has been protected (i.e. hashed or encrypted). | If false, the plaintext password will be protected appropriately (hashed, encrypted, or left as plaintext as required) when the customer is created/updated. |
| LpmStatus | Integer | Specifies if this customer is to receive email marketing. | Valid values are:
1 - Normal 2 - Referred - Pending Acceptance 3 - Suspended – Invalid Email 4 - Suspended – Client Request New clients default to 1 ('Normal') if not specified. |
| SmsStatus | Integer | Specifies if this customer is to receive SMS marketing. | Valid values are:
0 - Inactive 1 - Active New clients default to 0 ('Inactive') if not specified. |
| EmailFormat | String (5) | The customer's preferred email format. | Valid values are 'HTML' and 'Text'. New customers default to 'HTML' if not specified. |
| CustomerType | Integer | Specifies the customer type | This is a read-only field.
Valid values are: 1 - Registered 2 - Guest |
| PreferencesToken | String | The encrypted Customer ID of this customer. | This is a read-only field. |
| InterestGroups | String (100)[] | The names of the interest groups that this customer is subscribed to. | |
| Account | CustomerAccount | The customer's debit account. | |
| Notes | CustomerNote[] | The notes entered against this customer. | Notes cannot be modified, only created and deleted. |
| Addresses | CustomerAddress[] | The customer's addresses. | |
| Attributes | NameValuePair[] | Additional information attached to this customer. | These attributes are arbitrary key-value data pairs stored against a Customer. The Name and Value fields for these NameValuePairs are limited to a length of 100 characters each. |
| Websites | Integer[] | The website IDs of the websites to which a customer is linked. | Once a customer has been linked to a website, the link is permanent and cannot be removed. Linked websites are primarily used when sending CRM emails to customers. Linking a customer to a website does not affect a customer in any way. See Website ID for more information. |
| DateCreated | DateTime | The date this customer was created. | This is a read-only field. |
| DateModified | DateTime | The date this customer was last modified. | This is a read-only field. |
| AdditionalDetails | String | Contains arbitrary additional details. | This field is ignored unless custom processing is required. Expected to contain structured data (e.g. XML, JSON). |
Numbers in parentheses following a type indicate the maximum length of that field. Any values longer than the maximum length will be truncated.
A CustomerAccount allows a customer to purchase goods on credit, and may be used to give additional benefits such as discounts.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| AccountID | String (50) | An identifier for the CustomerAccount. | Multiple customers may have the same AccountID. |
| AccountType | String (100) | The type of the CustomerAccount. | The account type will be created if it does not exist. |
| AccountName | String (100) | The name of the CustomerAccount. | |
| DateCreated | DateCreated | The date this CustomerAccount was created. | This is a read-only field. |
| Discount | Double | A site-wide discount applied to purchases with this CustomerAccount. | This is a percentage, limited to the range 0% (i.e. no discount) to 100%. |
| FreeFreight | Boolean | Specifies if freight will be charged on orders through this CustomerAccount. |
Numbers in parentheses following a type indicate the maximum length of that field. Any values longer than the maximum length will be truncated.
A CustomerNote is a note placed against a customer by an admin user.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | Integer | The unique identifier of this CustomerNote | |
| Note | String (512) | The content of this CustomerNote. | |
| DateCreated | DateTime | The date this CustomerNote was created. | |
| DisplayLevel | Integer | Defines where this CustomerNote can be displayed. | Valid values are:
2 - Displayed in the admin and Customers API only. 3 - Displayed in all locations, including order progress emails and order history. This defaults to 2 if not specified when a CustomerNote is created. |
Numbers in parentheses following a type indicate the maximum length of that field. Any values longer than the maximum length will be truncated.
No update functionality is supported with CustomerNote. If a CustomerNote is created in error and should not be displayed then it may be deleted and a new CustomerNote created to correct the error if necessary.
Represents a customer address.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | Integer | A unique identifier for this CustomerAddress. | |
| Type | String (50) | The type of this CustomerAddress. | A customer can have multiple addresses of type "None". A customer can have either one "Shipping" and one "Billing" address, or one "Primary" address. |
| Title | String (10) | The title for this address. | An honorific to be used for this address e.g. Dr., Mrs. |
| FirstName | String (50) | The first name for this address. | |
| LastName | String (50) | The last name for this address. | |
| ContactPhone | String (50) | The contact phone number for this address. | The ContactPhone for an address is independent of the Phone, Fax, and Mobile fields on a Customer. |
| Company | String (50) | The company for this address. | |
| Street | String (50) | The street address portion of this address. | |
| Suburb | String (50) | The suburb portion of this address. | |
| City | String (50) | The city portion of this address. | |
| State | String (50) | The state or province portion of this address. | |
| Postcode | String (50) | The postcode portion of this address. | |
| Country | String (3) | The country portion of this address. | This is a standard three-letter country code. |
| ExtraInformation | String (50) | An additional address information line. |
Numbers in parentheses following a type indicate the maximum length of that field. Any values longer than the maximum length will be truncated.
An arbitrary number of different Types are supported. The 'Shipping', 'Billing', or 'Primary' Types should be used when adding a shipping or billing address to a Customer.
A 'Primary' address represents both a shipping and billing address.
Where the Type of the CustomerAddress is 'Billing' then any values entered into the FirstName and LastName fields will be ignored.
Addresses with invalid country codes in their Country fields will be silently ignored and not stored.
The Customers API returns standard API response codes.