Mozenda API Documentation

Using the Mozenda Web Services Rest API, customers can programmatically connect to their Mozenda account. This provides complete automation capabilities for setting search parameters, gathering results, updating collections, etc. This connection is made by sending a standard Http request that includes variables and other settings for interacting with the system.

Configuring your account to be accessible via the API is a simple process:
1. Login to your account at http://login.mozenda.com
2. Click the Account link located in the top right corner of the web page.
3. Click the Users tab in the Account area.
4. Click the wrench symbol for the user you would like to configure an 'API Web Service Key' for.
5. Look for the 'API Web Service Key' section and then click Generate a New Key. You will be required to provide this key in all requests to the API.
6. Learn the syntax of the API requests using the documentation below and you are ready to go!

After you have enabled your account for API access you will want to determine what functions you need to accomplish programmatically. Most of the actions you can perform via the Web Console can also be initiated through the API. Use the rest of this document as a reference for the different functions that you will need to perform.

Mozenda API Syntax

With every API request there is some standard information that must be passed. First is the base url, which is:

https://api.mozenda.com/rest?

Next, each request made to the API requires your Web Service Key (described above) to authenticate your account. This value is passed in using the WebServiceKey parameter:

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E

Next, each request needs to provide the Service parameter. This parameter specifies the version of the API being used. Right now the only accepted value is Mozenda10:

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10

Finally, each request needs to provide the Operation parameter. This parameter tells the API what operation you want performed. A list of the available operations follows, along with a sample URL showing how to use the operation.

Important Note: All API requests must comply with the the specification for URLs RFC 1738. This means some parameters need to be encoded before they are passed via the API. For Example, if you wanted to add a ViewParameter.Name parameter with the value of "Sport Camera" to your View.GetItems API call, then the correct encoding for this call is "ViewParameter.Name=Sport%20Camera", because spaces are not allowed in URLs and should be replaced with a %20 in the encoding step of your process.


Collection.Add

Description

Adds an empty collection in your account.

Required parameters

Name

Optional parameters

Description

Returns

The result of the operation and the CollectionID if it was successful.

Example request url

https://api.mozenda.com/rest?WebServiceKey=3FE7221C-9097-4B64-AED6-0950F675F398&Service=Mozenda10&Operation=Collection.Add&Name=MyFirstCollection&Description=My%20description
<?xml version="1.0" encoding="utf-8" ?>
<CollectionAddResponse
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <CollectionID>2259</CollectionID>
 </CollectionAddResponse>
		
back to top

Collection.AddItem

Description

Adds an item to a collection with the values specified. Instead of including the single item to be added in the request it is also possible to add items in bulk by attaching a file with the request.

Required parameters

CollectionID

Optional parameters

Field.<FieldName>,

Returns

The ItemID of the newly added item, or an error message stating why it could not be added.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Collection.AddItem&CollectionID=1099&Field.FirstName=John&Field.LastName=Smith
<?xml version="1.0" encoding="utf-8" ?>
<CollectionAddItemResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <ItemID>1098</ItemID>
</CollectionAddItemResponse>
		

Bulk Insertion

In addition to adding items one at a time, there is a method that can be used to add items in bulk. Below is some sample C# code that will demonstrate how this is done. This same technique can be used in many different programming languages to add multiple items to a Mozenda collection at one time. This option should be used whenever a large number of items need to be inserted all at once.
string webServiceKey = C70E1F84-E12B-4e73-B199-2EE6D43AF44E; //Your Account WebServiceKey.
string collectionID = 1001; //The ID of the destination Collection.
string url = string.Format(
"https://api.mozenda.com/rest?WebServiceKey={0}&Service=Mozenda10&Operation=Collection.AddItem&CollectionID={1}",
webServiceKey, collectionID);
string fileName = "C:\\Temp\\NewItems.xml"; //Path to the file containing the items to be uploaded.

WebClient client = new WebClient();
byte[] responseBinary = client.UploadFile(url, fileName);
string response = Encoding.UTF8.GetString(responseBinary);
		
The image below illustrates the format for each item in the uploaded file.

back to top

Collection.AddField

Description

Adds a field to the desired Collection. This field is created with the default format of "Text". This operation can only be performed on Collections that are created by a user.

Required parameters

CollectionID, Name

Optional parameters

Description

Returns

The result of the operation and the FieldID if it was successful.

Example request url

https://api.mozenda.com/rest?WebServiceKey=3FE7221C-9097-4B64-AED6-0950F675F398&Service=Mozenda10&Operation=Collection.AddField&CollectionID=1052&Field=Col7&FieldDescription=My%20col7%20description
<?xml version="1.0" encoding="utf-8" ?>
<CollectionAddField
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <FieldID>2259</FieldID>
 </CollectionAddField>
		
back to top

Collection.Clear

Description

Clears the contents of a collection but leaves the collection intact. WARNING: This operation is permanent!

Required parameter

CollectionID

Optional parameter

RetainCollectionHistory ('Yes', 'No' - Yes to only mark items as deleted. Default is No)

Returns

A message indicating whether or not the command was successful.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Collection.Clear&CollectionID=1099
<?xml version="1.0" encoding="utf-8" ?>
<CollectionClearResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
</CollectionClearResponse>
		
back to top

Collection.Delete

Description

Deletes the collection and all data within it. WARNING: This operation is permanent!

Required parameters

CollectionID

Returns

A message detailing whether or not the requested command was successful.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Collection.Delete&CollectionID=1009
<?xml version="1.0" encoding="utf-8" ?>
<CollectionDeleteResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
</CollectionDeleteResponse>
		
back to top

Collection.DeleteField

Description

Deletes a field from the Collection. This operation can only be performed on Collections that are created by a user.

Required parameters

CollectionID, Field

Returns

A message detailing whether the delete field command executed successfully.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Collection.DeleteField&CollectionID=1009&Field=ExampleFieldName
<?xml version="1.0" encoding="utf-8" ?>
<ApiResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
</ApiResponse>
		
back to top

Collection.DeleteItem

Description

Deletes an item from a collection

Required parameters

CollectionID, ItemID

Returns

A message detailing whether the delete item command executed successfully.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Collection.DeleteItem&CollectionID=1009&ItemID=1922
<?xml version="1.0" encoding="utf-8" ?>
<CollectionDeleteItemResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
</CollectionDeleteItemResponse>
		
back to top

Collection.GetFields

Description

Returns a list of fields that are in that collection with their details

Required parameters

CollectionID

Optional parameter

Include (Can be set to All or Unique. It defaults to All.)

Returns

A list of fields for a collection.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Collection.GetFields&CollectionID=1001&Include=Unique
<?xml version="1.0" encoding="utf-8" ?>
<CollectionGetFieldsResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <FieldList>
	 <Field>
		<FieldID>418</FieldID>
		<CollectionID>1003</CollectionID>
		<Name>ID</Name>
		<Description>Unique number identifying the Default.</Description>
		<IsSystem>True</IsSystem>
		<IsMatchUp>False</IsMatchUp>
	 </Field>
	 <Field>
		<FieldID>430</FieldID>
		<CollectionID>1003</CollectionID>
		<Name>AgentID</Name>
		<Description />
		<IsSystem>True</IsSystem>
		<IsMatchUp>False</IsMatchUp>
	 </Field>
  </FieldLists>
</CollectionGetFieldsResponse>
		
back to top

Collection.GetList

Description

Returns a list of collections for an account

Required parameters

None

Returns

A List of the collections in an account

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Collection.GetList
<?xml version="1.0" encoding="utf-8" ?>
<CollectionGetListResponse
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <CollectionList>
	 <Collection>
		<CollectionID>1005</CollectionID>
		<Name>My First Collection</Name>
		<Description>Sample description of 'My 1st Collection'.</Description>
		<DefaultViewID>1003</DefaultViewID>
		<AgentID>1002</AgentID>
	 </Collection>
	 <Collection>
		<CollectionID>1067</CollectionID>
		<Name>ZipCodes</Name>
		<Description>Sample description of the 'ZipCodes' repository.</Description>
		<DefaultViewID>1036</DefaultViewID>
	 </Collection>
  </CollectionList>
</CollectionGetListResponse>
		
back to top

Collection.GetViews

Description

Gets a list of views for a particular collection

Required parameters

CollectionID

Returns

A list of the views that is currently in the system for a particular collection.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Collection.GetViews&CollectionID=1008
<?xml version="1.0" encoding="utf-8" ?>
<CollectionGetViewsResponse
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <ViewList>
	 <View>
		<ViewID>801</ViewID>
		<CollectionID>801</CollectionID>
		<Name>All ZipCodes</Name>
		<Description>All items in the ZipCodes collection.</Description>
	 </View>
  </ViewList>
</CollectionGetViewsResponse>
		
back to top

Collection.GetPublisher

Description

Returns a list of collections and their current publishing configuration.
Note: The PublishWhenAgentCompletes field will be removed if the collection is publishing on a schedule.

Required parameters

CollectionID or AgentID (comma separated lists)

Returns

A list of collections with their current publishing configuration.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Collection.GetPublisher&CollectionID=1099&AgentID=1002
<?xml version="1.0" encoding="utf-8" ?>
<GetPublisherResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <Result>Success</Result>
 <CollectionList>
  <Collection>
	<CollectionName>Lowes</CollectionName>
	<CollectionID>1099</CollectionID>
	<AgentID>1001</AgentID>
	<PublishWhenAgentCompletes>1001</PublishWhenAgentCompletes>
	<Created>2012-01-01 10:50:45</Created>
	<CreatedBy>John</CreatedBy>
	<Description>Collection for Lowes</Description>
	<ViewID>1036</ViewID>
	<FileFormat>CSV</FileFormat>
	<FileName />
	<Method>Ftp</Method>   
	<IncludePackages>Yes</IncludePackages>	   
	<FtpServer>test.myserver.com</FtpServer>
	<FtpPort>21</FtpPort>
	<FtpDirectory />
	<FtpUser />
	<FtpPassword />
	<FtpUsePassive>Yes</FtpUsePassive>
	<FtpProtocol>SFTP</FtpProtocol>
  </Collection>
  <Collection>
	<CollectionName>Home Depot</CollectionName>
	<CollectionID>1100</CollectionID>
	<AgentID>1002</AgentID>
	<Created>2012-01-01 10:45:45</Created>
	<CreatedBy>John</CreatedBy>
	<Description>Collection for Home Depot</Description>
	<ViewID>1036</ViewID>
	<FileFormat>CSV</FileFormat>
	<FileName />
	<Method>Email</Method>
	<EmailAddress>john.doe@gmail.com<EmailAddress>
	<EmailSubject />		
  </Collection>
 </CollectionList>  
</GetPublisherResponse>
		
back to top

Collection.Publish

Description

Publishes the collection according to the publishing information setup for the collection. Currently, this can be entered via the Web Console or using the Collection.SetPublisher call. For more information about configuring your collection for FTP publishing please click here.

Required parameters

CollectionID

Optional Parameters

Job.StatusUrl - A url that Mozenda will request when the job finishes processing. The url needs to begin with either the http:// or https:// protocol and needs to be url encoded. It can contain any of the following replacement values anywhere in the querystring. To include a replacement value enclose it in percentage signs (e.g. %JobID%).
  • JobID
  • Job.Status
  • Job.Created
  • Job.Ended
Note: The status url may be requested multiple time for the Running status.

Returns

The result of the operation and the jobID if the request was successful.

Example request url

https://api.mozenda.com/rest?WebServiceKey=3FE7221C-9097-4B64-AED6-0950F675F398&Service=Mozenda10&Operation=Collection.Publish&CollectionID=1005
<?xml version="1.0" encoding="utf-8" ?>
<CollectionPublishResponse
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>  
  <JobID>EE64EC0E-F233-4549-8DF0-852298965F81</JobID>
 </CollectionPublishResponse>
		
back to top

Collection.SetUniqueFields

Description

Sets the Unique Fields on the Collection. WARNING: This operation will delete any duplicates in the collection based on the new unique fields being set.

Required parameters

CollectionID, Fields (comma-separated list of field names to be set as unique)

Returns

A message detailing whether the command executed successfully and also the number of duplicate items removed.

Example request url

https://api.mozenda.com/rest?WebServiceKey=3FE7221C-9097-4B64-AED6-0950F675F377&Service=Mozenda10&Operation=Collection.SetUniqueFields&Fields=Col1,Col2,Col3&CollectionID=1052
<?xml version="1.0" encoding="utf-8" ?>
<CollectionSetUniqueFieldsResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
  <DuplicateItemsRemoved>0</DuplicateItemsRemoved>
</CollectionSetUniqueFieldsResponse>
		
back to top

Collection.SetPublisher

Description

Updates or creates a new publisher for the specified collection.

Required parameters

CollectionID, Method

Required parameters by Method

Email: EmailAddress
Ftp: FtpServer
AmazonS3:
AmazonS3AuthenticationToken (AWS Access Key ID)
AmazonS3SignRequestToken (AWS Secret Access Key)
AmazonS3BucketPath
AmazonS3BucketRegion (The Amazon S3 endpoint for the selected bucket. Click here to see a list of valid endpoints)

Optional parameters

ViewID (An empty viewID is the default and will use "Everything" from the collection)
FileFormat (CSV, TSV, XML. Default is CSV)
FileName
FileIncludeHeader ('Yes', 'No' - Yes to add field headers to row one in the published file. Default is Yes.)
PublishWhenAgentCompletes ('Yes', 'No' - Yes to publish whent the Agent completes. Default is Yes)
ItemStatusIncludeColumn ('Yes', 'No' - Yes to include the column in the data file. Default is No)

Optional parameters for ItemStatusInclude

ItemStatusIncludeAdded ('Yes', 'No')
ItemStatusIncludeChanged ('Yes', 'No')
ItemStatusIncludeUnchanged ('Yes', 'No')
ItemStatusIncludeDeleted ('Yes', 'No')
Note: These item status filtering options have no effect unless ItemStatusIncludeColumn is true.

Optional parameters by Method

Email:
EmailSubject
Ftp:
FtpPort (Default is 21),
FtpProtocol (FTP, SFTP. Default is FTP),
FtpDirectory,
FtpUser,
FtpPassword,
FtpUsePassive ('Yes', 'No'. Yes to use passive transer mode. Default is Yes.),
IncludePackages ('Yes', 'No'. Yes to include images/files when publishing to FTP. Default is No.)

Returns

Returns a message specifying whether or not the add/update was successful.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Collection.SetPublisher&CollectionID=1099&Method=Email&EmailAddress=MyEmail@Provider.com
<?xml version="1.0" encoding="utf-8" ?>
<SetPublisherResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
</SetPublisherResponse>
		

Additional Information

  • A publisher cannot be created with a Method of "None", it must be Ftp, Email, or AmazonS3.
  • A publisher will only update the fields related to your Method (i.e - If Method is Ftp, only the common optional fields and the Ftp fields will be updated).
  • If you are creating a new publisher any fields you don't provide (that are not required) will be set to default values.
  • If you have manually setup a schedule for your publisher in the web console's publish dialog, then do not provide the 'PublishWhenAgentCompletes' parameter or the schedule will be deleted.
back to top

Collection.UpdateField

Description

Modifies a field in a collection.

Required parameters

FieldID

Optional parameters

Description, Format (currently supported options are Text, File, and DateTime), Name

Returns

Returns a message specifying whether or not the update was successful

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Collection.UpdateField&CollectionID=1008&FieldID=1098&Name=MyNewFieldName&Description=My%20new%20field%20description&Format=File
<?xml version="1.0" encoding="utf-8" ?>
<CollectionUpdateFieldResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
</CollectionUpdateFieldResponse>
		
back to top

Collection.UpdateItem

Description

Updates an item in the collection.

Required parameters

CollectionID, ItemID

Optional parameters

Field.<FieldName>

Returns

Returns a message specifying whether or not the update was successful

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Collection.UpdateItem&CollectionID=1008&ItemID=1098&Field.FirstName=Harry&Field.LastName=Johnson&Field.Age=27
<?xml version="1.0" encoding="utf-8" ?>
<CollectionUpdateItemResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
</CollectionUpdateItemResponse>
		
back to top

View.DeleteItems

Description

Deletes all the items in the View. WARNING: This operation is permanent!

Required parameters

ViewID

Returns

A message detailing whether or not the requested command was successful and the number of items that have been deleted.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=View.DeleteItems&ViewID=1009
<?xml version="1.0" encoding="utf-8" ?>
<ViewDeleteItemsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <Result>Success</Result> <ItemsDeleted>67</ItemsDeleted> </ViewDeleteItemsResponse>
back to top

View.GetItems

Description

Returns items from a view. To learn how to setup a view for a collection click here

Required parameters

ViewID

Optional parameters

ItemStatusIncludeColumn ('Yes', 'No' - Yes to include the column in the data file. Default is No)
PageNumber
PageItemCount
ViewParameter.JobID
ViewParameter.<ViewParameterName>

Optional parameters for ItemStatusInclude

ItemStatusIncludeAdded ('Yes', 'No')
ItemStatusIncludeChanged ('Yes', 'No')
ItemStatusIncludeUnchanged ('Yes', 'No')
ItemStatusIncludeDeleted ('Yes', 'No')
ItemStatusRangeStart (YYYY-MM-DD HH:mm:ss - The beginning date to calculate the items that should be included with the view.)
ItemStatusRangeEnd (YYYY-MM-DD HH:mm:ss - The ending date to calculate the items that should be included with the view.)
Note: These item status filtering options have no effect unless ItemStatusIncludeColumn is true. See the Additional Information section below for usage.

Returns

The number of items that were requested according to the PageItemCount parameter
Note: A maximum of 1,000 items will be returned even if the specified PageItemCount parameter is greater than 1,000.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=View.GetItems&ViewID=1022&ViewParameter.JobID=04E2DA-DF22-4239-A343-DE685AF54EC6&PageNumber=1&PageItemCount=20&ViewParameter.Name=Michael
<?xml version="1.0" encoding="utf-8" ?>
<ViewGetItemsResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
  <PageItemCount>2</PageItemCount> 
  <PageNumber>2</PageNumber> 
  <PageCount>106</PageCount>
  <ItemList>
	 <Item>
		<ItemID>1092</ItemID> 
		<Year>2000</Year>
		<Make>BMW</Make>
		<Model>328CI</Model> 
		<Price>$7490</Price> 
		<Telephone>4049141131</Telephone> 
		<AreaCode>404</AreaCode> 
		<Source>A1Cars</Source> 
	 </Item>
	 <Item>
		<ItemID>1103</ItemID> 
		<Year>2003</Year> 
		<Make>BMW</Make>
		<Model>525i</Model> 
		<Price>$14850</Price> 
		<Telephone>8606342015</Telephone> 
		<AreaCode>860</AreaCode> 
		<Source>A1Cars</Source> 
	 </Item>
  </ItemList>
</ViewGetItemsResponse>
		

Additional Information

ItemStatusInclude options
  • If any item status filtering options are set to true, the results will only include items with those statuses.
  • If no item status filtering option is set to true, and any are set to false, the results will include items with all statuses not set to false.
  • Finally, if no item status filtering options are set at all, the results will include items with statuses of Added, Changed, and UnChanged, but not Deleted.
ItemStatusRange options
  • If the ItemStatusRangeStart and ItemStatusRangeEnd values are not provided, the system uses the start and end times of the supplied JobID.
  • If no JobID is supplied, the system will get this range from the most recently created job for this Agent.
back to top

View.SetFields

Description

Sets the fields that are included in the view and also their order. To setup a view for a collection click here

Required parameters

ViewID, Fields (Comma-separated list of field names to be included in the view)

Returns

The result of the operation

Example request url

https://api.mozenda.com/rest?WebServiceKey=3FE7221C-9097-4B64-AED6-0950F675F377&Service=Mozenda10&Operation=View.SetFields&Fields=Col6,Col5,Col4&ViewID=1054
<?xml version="1.0" encoding="utf-8" ?>
<ViewSetFieldsResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
</ViewSetFieldsResponse>
		
back to top

Agent.Add

Description

Adds a new Agent. Cannot be used to overwrite an existing Agent. The existing Agent must be deleted first using the Agent.Delete request.

Required parameters

Name, Definition (Needs to be attached as a file)

Optional parameters

AgentID, Description

Returns

The AgentID and CollectionID for the new Agent if the request was successful.

Example request

string agentDefinitionfileName = @"C:\Temp\AgentDefinition.xml"; //Path to the Agent definition file to be uploaded.
string url = @"https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&
Operation=Agent.Add&AgentID=1009&Name=MyTestAgent";
WebClient client = new WebClient();
byte[] responseBinary = client.UploadFile(url, agentDefinitionfileName);
string response = Encoding.UTF8.GetString(responseBinary);			
		
<?xml version="1.0" encoding="utf-8" ?>
<AgentSaveResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <AgentID>1009</AgentID>
  <CollectionID>1009</CollectionID>
</AgentSaveResponse>
		
back to top

Agent.Delete

Description

Deletes an agent and all associated schedules for that agent.

Required parameters

AgentID

Returns

A confirmation message describing whether or not the request was successful.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Agent.Delete&AgentID=1008
<?xml version="1.0" encoding="utf-8" ?>
<AgentDeleteResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
</AgentDeleteResponse>
		
back to top

Agent.Get

Description

Gets the Agent definition and meta data for an Agent.

Required parameters

AgentID

Returns

A response containing the AgentID, Name, CollectionID, Description, Domain, and Definition for an Agent.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Agent.Get&AgentID=1005
<?xml version="1.0" encoding="utf-8" ?>
<AgentGetResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>  
	<AgentID>1005</AgentID>
	<Name>My First Agent</Name>
	<CollectionID>1005</CollectionID>
	<Description>Extracts new lead information</Description>
	<Domain>myleadwebsite.com</Domain>
	<Definition>
<![CDATA[<!-- Copyright (C) 2014 Mozenda, Inc. All rights reserved. --> <Agent> <Version>1.0i</Version> <IeVersion>8.0</IeVersion> <AgentDefinition> <!--- - - - - - - - Actions - - - - - - - - --> <ActionList> <Action> <ActionType>LoadPage</ActionType> <Page>0</Page> <DestinationPage>1</DestinationPage> <TopLevelNav>True</TopLevelNav> <TopLevelNavCount>1</TopLevelNavCount> <PageUrl>http://www.mozenda.com/builderwelcome</PageUrl> </Action> <!-- Page 1 --> <Action> <ActionType>PagePlaceHolder</ActionType> <Page>1</Page> <ItemType>PlaceHolder</ItemType> <LoadUrl>http://www.mozenda.com/builderwelcome</LoadUrl> <BaseUrl>http://www.mozenda.com/builderwelcome</BaseUrl> <CaptureScreenShot>False</CaptureScreenShot> <NonScrollingScreenShot>False</NonScrollingScreenShot> </Action> <Action> <ActionType>BeginAnchorList</ActionType> <Page>1</Page> <ItemType>PlaceHolder</ItemType> <ItemXPath>//div[1]/div[2]/div/div/h3[1]/a[1]</ItemXPath> <ItemXPath>/html[1]/body[1]/div[1]/div[1]/div[2]/div/div/h3[1]/a[1]</ItemXPath> <ListName>LeadNameList</ListName> </Action> <Action> <ActionType>GetElementValue</ActionType> <Description>Captures the text of the list item</Description> <Page>1</Page> <ItemType>PlaceHolder</ItemType> <ItemXPath>.</ItemXPath> <FieldExpression>%LeadName%</FieldExpression> </Action> <Action> <ActionType>GetElementValue</ActionType> <Page>1</Page> <ItemType>PlaceHolder</ItemType> <ItemXPath>../..</ItemXPath> <FieldExpression>%ContactEmail%</FieldExpression> </Action> <Action> <ActionType>EndList</ActionType> <Page>1</Page> <ListName>LeadNameList</ListName> </Action> </ActionList> </AgentDefinition> </Agent>]]>
</Definition> </AgentGetResponse>
back to top

Agent.GetList

Description

Returns a list of your agents with their ID, Name, Settings, Description, and other important information.

Required parameters

None

Optional parameters

IncludeStartingURL (true or false)

Returns

A list of agents for an account.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Agent.GetList
<?xml version="1.0" encoding="utf-8" ?>
<AgentGetListResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <AgentList>
	 <Agent>
		<Created>2008-06-21 08:45:32</Created>
		<Modified />
		<AgentID>1001</AgentID>
		<Name>My First Agent</Name>
		<Description>This is my first agent</Description>
		<Settings />
		<StartingURL>http://mozenda.com/builderwelcome</StartingURL>
	 </Agent>
	 <Agent>
		<Created>2008-06-23 14:20:49</Created>
		<Modified />
		<AgentID>1003</AgentID>
		<Name>Scraped Data</Name>
		<Description />
		<Settings />
		<StartingURL>http://mozenda.com/builderwelcome</StartingURL>
	 </Agent>
  </AgentList>
</AgentGetListResponse>
		
back to top

Agent.GetCombinedCollections

Description

Returns a list of Agents and the combined collections they source.

Required parameters

AgentID (comma separated list)

Returns

A list of Agents and the combined collections they source.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Agent.GetCombinedCollections&AgentID=1001,1002
<?xml version="1.0" encoding="utf-8" ?>
<AgentGetCombinedCollectionsResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <AgentList>
	 <Agent>            
		<AgentID>1001</AgentID>            
		<SourcesCollections>1145</SourcesCollections>      
	 </Agent>
	 <Agent>            
		<AgentID>1002</AgentID>            
		<SourcesCollections>1145,1146</SourcesCollections>      
	 </Agent>
  </AgentList>
</AgentGetListResponse>
		
back to top

Agent.GetJobs

Description

Returns a list of your agent's jobs with detailed information.

Required parameters

AgentID

Optional parameters

Job.Created (YYYY-MM-DD. Returns jobs that were created greater than or equal to the date specified), Job.Started (YYYY-MM-DD. Returns jobs that were started greater than or equal to the date specified), Job.Ended (YYYY-MM-DD. Returns jobs that ended less than or equal to the date specified), Job.State (Active, Archived, All)

Returns

A list of current jobs in the system for this agent in descending order.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Agent.GetJobs&AgentID=1001&Job.Started=2009-02-06&Job.Ended=2009-02-07&Job.State=Active
<?xml version="1.0" encoding="utf-8" ?>
<AgentGetJobsResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <JobList>
	 <Job>
		<Created>2008-11-13 16:41:26</Created>
		<Modified>2008-11-13 16:41:27</Modified>
		<JobID>EE64EC0E-F233-4549-8DF0-852298965F81</JobID>
		<JobType>WebPageHarvest</JobType>
		<Status />
		<Started />
		<Ended />
		<AgentID>1002</AgentID>
		<ErrorCode />
		<ErrorMessage />
		<ErrorFirst />
		<ErrorLast />
		<ErrorCount />
		<WarningFirst />
		<WarningLast />
		<WarningCount />
	 </Job>
  </JobList>
</AgentGetJobsResponse>
		
back to top

Agent.Run

Description

Starts a new job for an Agent

Required parameters

AgentID

Optional parameters

AgentParameter.<AgentParameterName>
(To learn more about how to set the parameters of an agent using the API, please visit
the Using Agent Parameters page in our Help Center)
Job.Description
Job.Name
Job.StatusUrl - A url that Mozenda will request when the job finishes processing. The url needs to begin with either the http:// or https:// protocol and needs to be url encoded. It can contain any of the following replacement values anywhere in the querystring. To include a replacement value enclose it in percentage signs (e.g. %AgentID%).
  • AgentID
  • Agent.Name
  • Agent.Description
  • Agent.Domain
  • JobID
  • Job.Status
  • Job.Created
  • Job.Ended
  • Job.Name
  • Job.Description
Note: The status url may be requested multiple time for the Running status.

Returns

The result of the operation and the jobID if the request was successful.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Agent.Run&AgentID=1009&AgentParameter.Zip=90210&Job.StatusUrl=http%3A%2F%2Fmydomain.com%3FStatus%3D%25Job.Status%25%26JobID%3D%25JobID%25
<?xml version="1.0" encoding="utf-8" ?>
<AgentRunResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <AgentID>1002</AgentID>
  <JobID>EE64EC0E-F233-4549-8DF0-852298965F81</JobID>
</AgentRunResponse>
		
back to top

Job.Cancel

Description

Cancels a Job in the system.
Note: A job must be in a Paused or Error State to cancel a job

Required parameters

JobID

Returns

A message indicating whether the command was successful

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Job.Cancel&JobID=EE64EC0E-F233-4549-8DF0-852298965F81
<?xml version="1.0" encoding="utf-8" ?>
<JobCancelResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
</JobCancelResponse>
		
back to top

Job.Get

Description

Gets the details of a job by the Job ID.

Required parameters

JobID (comma-separated list of JobID's)

Returns

A response containing the Status, Command, CreatedDate, CreatedBy, AccountID, AgentID, and ErrorMessage of a particular job in the system.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Job.Get&JobID=EE64EC0E-F233-4549-8DF0-852298965F81
<?xml version="1.0" encoding="utf-8" ?>
<JobGetResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <Job>
	 <ActiveJob>True</ActiveJob>
	 <JobID>EE64EC0E-F233-4549-8DF0-852298965F81</JobID>
	 <JobType>WebPageHarvest</JobType>
	 <Created>2008-11-05 17:04:36</Created>
	 <Modified>2008-11-14 13:20:19</Modified>
	 <Status>Running</Status>
	 <Started />
	 <Ended />
	 <ScheduleID />
	 <ScheduleItemType>WebPageHarvest</ScheduleItemType>
	 <ScheduleItemID>1001</ScheduleItemID>
	 <ErrorCode />
	 <ErrorMessage />
	 <ErrorFirst />
	 <ErrorLast />
	 <ErrorCount />
	 <WarningFirst />
	 <WarningLast />
	 <WarningCount />
  </Job>
</JobGetResponse>
		
back to top

Job.GetAgentProgress

Description

Gets the progress of the Agent.

Required parameters

JobID

Returns

A response containing the progress of each list in the Agent. If there are DataLists then it will return the currently processing item from the view.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Job.GetAgentProgress&JobID=EE64EC0E-F233-4549-8DF0-852298965F81
<?xml version="1.0" encoding="utf-8" ?>
<JobGetAgentProgressResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <AgentID>1029</AgentID>
  <JobID>1B869E2F-06CA-48D4-B7D9-CECC7DE28DA6</JobID>
  <BeginListList>
	<BeginList>
	 <ListName>ForumTitleList</ActiveJob>
	 <AgentPage>1</AgentPage>
	 <Type>BeginAnchorList</Type>
	 <RestartItemIndex>5</RestartItemIndex>
	</BeginList>
  </BeginListList>
</JobGetResponse>
		
back to top

Job.GetList

Description

Gets all the active jobs for the account.

Required parameters

None

Optional parameters

Job.Created (Returns jobs that were created greater than or equal to the date specified), Job.Started (Returns jobs that were started greater than or equal to the date specified), Job.Ended (Returns jobs that ended less than or equal to the date specified), Job.State (All, Active, Archived)

Returns

A response containing the Status, Command, CreatedDate, CreatedBy, AccountID, AgentID, and ErrorMessage of all jobs for a particular account in the system.

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Job.GetList&Job.State=Archived
<?xml version="1.0" encoding="utf-8" ?>
<JobGetResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result>
  <JobCount>Success</JobCount>
  <JobList>
	<Job>
	 <ActiveJob>True</ActiveJob>
	 <JobID>EE64EC0E-F233-4549-8DF0-852298965F81</JobID>
	 <JobType>WebPageHarvest</JobType>
	 <Created>2008-11-05 17:04:36</Created>
	 <Modified>2008-11-14 13:20:19</Modified>
	 <Status>Running</Status>
	 <Started />
	 <Ended />
	 <ScheduleID />
	 <ScheduleItemType>WebPageHarvest</ScheduleItemType>
	 <ScheduleItemID>1001</ScheduleItemID>
	 <ErrorCode />
	 <ErrorMessage />
	 <ErrorFirst />
	 <ErrorLast />
	 <ErrorCount />
	 <WarningFirst />
	 <WarningLast />
	 <WarningCount />
	</Job>
	<Job>
	 <ActiveJob>True</ActiveJob>
	 <JobID>FF64EC0E-F233-4549-8DF0-852298965F82</JobID>
	 <JobType>WebPageHarvest</JobType>
	 <Created>2008-11-06 16:04:36</Created>
	 <Modified>2008-11-14 14:20:19</Modified>
	 <Status>Running</Status>
	 <Started />
	 <Ended />
	 <ScheduleID />
	 <ScheduleItemType>WebPageHarvest</ScheduleItemType>
	 <ScheduleItemID>1002</ScheduleItemID>
	 <ErrorCode />
	 <ErrorMessage />
	 <ErrorFirst />
	 <ErrorLast />
	 <ErrorCount />
	 <WarningFirst />
	 <WarningLast />
	 <WarningCount />
	</Job>
  </JobList>
</JobGetResponse>
		
back to top

Job.Pause

Description

Issues the 'Pause' command for a job currently running in the system

Required parameters

JobID

Returns

A message indicating whether the command was successful

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Job.Pause&JobID=EE64EC0E-F233-4549-8DF0-852298965F81
<?xml version="1.0" encoding="utf-8" ?>
<JobPauseResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
</JobPauseResponse>
		
back to top

Job.Resume

Description

Resumes a job that is in a Paused or Error state.

Required parameters

JobID

Returns

A message indicating whether the command was successful

Example request url

https://api.mozenda.com/rest?WebServiceKey=C70E1F84-E12B-4e73-B199-2EE6D43AF44E&Service=Mozenda10&Operation=Job.Resume&JobID=EE64EC0E-F233-4549-8DF0-852298965F81
<?xml version="1.0" encoding="utf-8" ?>
<JobResumeResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Result>Success</Result> 
</JobResumeResponse>
		
back to top

Automate your data extraction

Get the data you need without all the hassle. Mozenda gets more accurate data in less time and for lower cost. Start a FREE Account today and enjoy the wonders of automation.