Retrieving the List of Accounts, Paginated
curl http://hostname/webservice/accounts \ -u webservice:apikey \ -G \ -d filter[per_page]='2' \ -d filter[page]='1'
By means of the per_page filter the maximum number of accounts to be returned can be limited. The maximum value that can be specified for per_page is 1000 (this is also the default). By means of page, the account list section to be returned can be specified, based on the section size, per_page.
The result is an XML document that contains in its accounts root element up to per_page accounts, depending on the existing amount of data and on the page filter values specified. Each account is contained in an account element. Only the most important account fields are returned:
<?xml version="1.0" encoding="UTF-8"?> <accounts type="array"> <account> <home_page>www.example.org</home_page> <id type="integer">5</id> <name>ADSL Telecomm Ltd.</name> <parent_id nil="true"></parent_id> <phone>099-99 99 99 99</phone> <responsible1 nil="true"></responsible1> <responsible2 nil="true"></responsible2> </account> <account> <home_page nil="true"></home_page> <id type="integer">7</id> <name>Fantasia Ltd.</name> <parent_id nil="true"></parent_id> <phone nil="true"></phone> <responsible1 nil="true"></responsible1> <responsible2 nil="true"></responsible2> </account> </accounts>
Retrieving the List of Accounts, with Locations Included
It is posibile to have the locations included when querying the accounts:
curl http://hostname/webservice/accounts \ -u webservice:apikey \ -G \ -d include[]="locations"
The XML result document will look like this:
<?xml version="1.0" encoding="UTF-8"?> <accounts type="array"> <account> <home_page>www.example.org</home_page> <id type="integer">5</id> <name>ADSL Telecomm Ltd.</name> <parent_id nil="true"></parent_id> <phone>099-99 99 99 99</phone> <locations type="array"> <location> <city>Berlin</city> <address1 nil="true"></address1> <address2>Unter den Linden 20</address2> <country>Germany</country> <postal_code>10117</postal_code> <account_id type="integer">1</account_id> <lng nil="true"></lng> <id type="integer">1</id> <want_assign_geoloc type="boolean">false</want_assign_geoloc> <lat nil="true"></lat> <state nil="true"></state> <address0 nil="true"></address0> </location> ... </locations> <responsible1 nil="true"></responsible1> <responsible2 nil="true"></responsible2> </account> <account> <home_page nil="true"></home_page> <id type="integer">7</id> <name>Fantasia Ltd.</name> <phone nil="true"></phone> <parent_id nil="true"></parent_id> <locations type="array"/> <responsible1 nil="true"></responsible1> <responsible2 nil="true"></responsible2> </account> </accounts>
Finding an Account
The data of a particular account can be directly retrieved by specifying its ID:
curl http://hostname/webservice/accounts/id \ -u webservice:apikey
If the desired account exists, the OMC returns an XML document containing its data in the account element. Example:
<?xml version="1.0" encoding="UTF-8"?> <account> <home_page>www.example.org</home_page> <id type="integer">1</id> <name>Example AG</name> <parent_id type="integer" nil="true"></parent_id> <phone nil="true"></phone> <responsible1 nil="true"></responsible1> <responsible2 nil="true"></responsible2> </account>
Using -d include[]="locations", you can have the OMC include the locations of the accounts.
If no account with the specified ID exists, the OMC returns the status code 404 as well as a corresponding message in the hash element.
Creating an Account
An account can be created by means of a POST request. Specify at least its name using the account[name] parameter:
curl http://hostname/webservice/accounts \ -u webservice:apikey \ -X POST \ --form-string account[name]='New Webservice AG' \ --form-string account[home_page]='http://nws.ag' \ --form-string account[phone]='+49-123-56789-0' \ --form-string account[responsible1]='first_responsible' \ --form-string account[responsible2]='another_responsible'
The OMC returns the complete account:
<?xml version="1.0" encoding="UTF-8"?> <account> <name>New Webservice AG</name> <home_page>http://nws.ag</home_page> <id type="integer">5</id> <phone>+49-123-56789-0</phone> <parent_id nil="true"></parent_id> <responsible1>first_responsible</responsible1> <responsible2>another_responsible</responsible2> </account>
Modifying an Account
To modify the fields of an account, use a PUT request and specify the account ID in the URL and the fields to be modified in the body of the request:
curl curl http://hostname/webservice/accounts/id \ -u webservice:apikey \ -X PUT \ --form-string account[home_page]='http://nws.ag' \ --form-string account[phone]='+49-123-56789-0'
As with account creation, the OMC returns the account data.