Please refer Customer Fields Table for the meaning of individual field.

LIST (GET /customers.xml)

Retrieve list of active customers, both active and deleted are included. To exclude deleted customers, use active_only parameter.

Example 1: Listing of customers

Retrieve list of customers (only page 1 (first 100) of the customers will be returned). You can use page parameter to return more pages.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers.xml"

Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<customers type="array">
  <customer>
    ...
  </customer>
  <customer>
    ....
  </customer>
  ...
</customers>

Example 2: Listing with page and per_page parameter

To retrieve page 1 of customers with default page size of 100.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers.xml?page=1"

To retrieve page 2 of the customers list:

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers.xml?page=2"

To retrieve page 1 of the customers list with page size of 50

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers.xml?page=1&per_page=50"

Example 3: Listing of Active customers Only

Retrieve list of customers (only 1st 100 customers will be returned). This parameter is useful when you are retrieving a complete set of active customers only. If you are retrieving the updated customer list, it is important to include the delete customers so that you can also delete the local version of customers.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers.xml?active_only=1"

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful

GET (GET /customer/{id}.xml)

Retrieve information on single customer. Replace {id} with the customer id. Please refer this page for return field information and meaning.

Example 1:

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers/11.xml"

Sample result:
<?xml version="1.0" encoding="UTF-8"?>
<customer>
  <alternate_code nil="true"></alternate_code>
  <birthday nil="true"></birthday>
  <city nil="true"></city>
  <code>000001</code>
  <company_name nil="true"></company_name>
  <country nil="true"></country>
  <customer_type_id nil="true"></customer_type_id>
  <email nil="true"></email>
  <fax nil="true"></fax>
  <first_name>Customer</first_name>
  <id>11</id>
  <last_name>1</last_name>
  <mobile nil="true"></mobile>
  <name>Customer 1</name>
  <remark nil="true"></remark>
  <state></state>
  <status>D</status>
  <street nil="true"></street>
  <tax_exempt>false</tax_exempt>
  <telephone nil="true"></telephone>
  <tin nil="true"></tin>
  <zipcode nil="true"></zipcode>
  <customer_type_name nil="true"></customer_type_name>
  <discount_text></discount_text>
  <birthdate nil="true"></birthdate>
  <utc_created_at>2011-04-21T02:38:27Z</utc_created_at>
  <utc_updated_at>2011-04-21T02:54:55Z</utc_updated_at>
</customer>

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
404 Not Found	if no customer matches the id

CREATE: (POST /customers.xml)

Create a new customer. The minimum require format Please refer to this page for the supported fields.

Example 1:

Create an customer with name John Smith.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers.xml" \
-X POST \
-d "<customer><name>John Smith</name></customer>" 

Sample result:
<?xml version="1.0" encoding="UTF-8"?>
<customer>
  <alternate_code nil="true"></alternate_code>
  <birthday nil="true"></birthday>
  <city nil="true"></city>
  <code>000002</code>
  <company_name nil="true"></company_name>
  <country nil="true"></country>
  <customer_type_id nil="true"></customer_type_id>
  <email nil="true"></email>
  <fax nil="true"></fax>
  <first_name>John</first_name>
  <id>12</id>
  <last_name>Smith</last_name>
  <mobile nil="true"></mobile>
  <name>John Smith</name>
  <remark nil="true"></remark>
  <state></state>
  <status nil="true"></status>
  <street nil="true"></street>
  <tax_exempt>false</tax_exempt>
  <telephone nil="true"></telephone>
  <tin nil="true"></tin>
  <zipcode nil="true"></zipcode>
  <customer_type_name nil="true"></customer_type_name>
  <discount_text></discount_text>
  <birthdate nil="true"></birthdate>
  <utc_created_at>2011-04-21T03:01:51Z</utc_created_at>
  <utc_updated_at>2011-04-21T03:01:51Z</utc_updated_at>
</customer>

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
422 Un-processable Entity	if validation error occurred
500 Internal Server Error	if unexpected error occurred

UPDATE: (/customer/{id}.xml)

Example 1:

Change customer name to Eric. (Assume customer id is 14.)

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers/17.xml" \
-X PUT \
-d "<customer><first_name>Kevin B</first_name><last_name>Example</last_name></customer>"

Change customer to tax exempt. (Assume customer id is 13.)

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers/13.xml" \
-X PUT \
-d "<customer><tax_exempt>true</tax_exempt></customer>"

Change the country code to PH.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers/14.xml" \
-X PUT \
-d "<customer><country>PH</country></customer>"

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
404 Not Found	if no customer matches the id
422 Un-processable Entity	if validation error occurred
500 Internal Server Error	if unexpected error occurred

DELETE: (DELETE /customer/{id}.xml)

Use this command to mark a customer as deleted. When a customer is already deleted, server will simply ignore the command and return 200 (Ok). Server will return 404 (Not found) if there is no matching customer id.

Example 1:

Delete customer identified with id 13.

curl -I -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers/12.xml" \
-X DELETE

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
404 Not Found	if no customer matches the id

OTHER FEATURES (GET /customers.xml)

Example 1: Counting customers

To count on the total number of customers

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers.xml?q=count"

Sample Result:

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <count type="integer">7</count>
</hash>

To count on the total number of active customers only.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers.xml?q=count&active_only=1"

To count on the total number of updated after Jan 1, 2011.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers.xml?q=count&after=2012-01-01"

Example 2: Limiting customers Listing with Last updated date

To inquire on the total number of customers updated after April 1, 2011

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers.xml?q=count&after=2011-04-1"

Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <count type="integer">1</count>
</hash>

Retrieve list of customers updated after Dec 31, 2010.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers.xml?after=2010-12-31%2023:59"

Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<customers type="array">
  <customer>
    ...
  </customer>
  <customer>
    ....
  </customer>
  ...
</customers>

Note that we escaped space with %20 in "after=2010-12-31%2023:59".

Example 3: Last Updated At

To inquire on the last updated date, use q=last_udpated_at

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/customers.xml?q=last_updated_at"

Sample Result: 
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <last-updated-at>2011-04-13 04:37:45</last-updated-at>
</hash>

Parameters for LIST (GET /customers.xml) ##

Page Filters

Page filters are used in LIST to limit the customers to be retrieved. You can combined page filter with Date Filters (before, after, from and to).

page: default of 1 (eg. page=1)
per_page: any number between 1 to 100 (e.g. per_page=10)

Date Filters

Date filtered are used in LIST to limit the customers to be retrieved. Given date format is in "YYYY-MM-DDTHH:MM:SSZ" specified in UTC time.

before: updated date < given date
after: updated date > given date
from: updated date >= give date
to: updated date <= give date

Status Filter

active_only: when setup to 1 to true, the list will exclude deleted customers

Inquiry

q=count - returns a number of customers
q=last_updated_at - returns the last updated date for your customer database

Additional Notes for Developers

When a customer is deleted, the status will be "D"
Listing returns both active and deleted customers.
In case the XML is not corrected formatted, the server will return 500 (Internal server error)

Proposed Algorithm for synchronizing customer incrementally

Keep a local persistent variable: previous_last_updated_date (which is initially nil)
GET last_updated_date from server
GET customers after previous_last_updated_date to last_updated_date
Start with page 1 until customers return contains an empty array
Override local variable pervious_last_updated_date with last_updated_date

Note: When customers downloaded contains status D, you should delete the local copy of the customer if present.