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 include variables and other settings for interacting with the system.

Configuring your account to be accessible via the API is a quick four step 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. Look for the 'API Web Service Key' section under the 'Account Details' tab, then click 'Generate a New Key'. You will be required to provide this key in all requests to the API.
4. 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:

Next, there also needs to be a Web Service Key (described above) that is passed using the WebServiceKey parameter:

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:

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.

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

<?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>
    </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

<?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 topic.</Description>
    </View>
  </ViewList>
</CollectionGetViewsResponse>
		

back to top

Collection.GetFields

Description

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

Required parameters

CollectionID

Returns

A list of fields for a collection.

Example request url

<?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.AddItem

Description

Adds an item to a collection with the values specified.

Required parameters

CollectionID

Optional parameters

Field.<FieldName>

Returns

The ItemID (Learn more) of newly added item, or an error message stating why it could not be added.

Example request url

<?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>
		

back to top

Collection.UpdateItem

Description

Updates an item in the collection.

Required parameters

CollectionID, ItemID (Learn more)

Optional parameters

Field.<FieldName>

Returns

Returns a message specifying whether or not the update was successful

Example request url

<?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

Collection.DeleteItem

Description

Deletes an item from a collection

Required parameters

CollectionID, ItemID (Learn more)

Returns

A message detailing whether the delete item command executed successfully.

Example request url

<?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.Clear

Description

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

Required parameters

CollectionID

Returns

A message indicating whether or not the command was successful.

Example request url

<?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

<?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

View.GetItems

Description

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

Required parameters

ViewID

Optional parameters

PageNumber, PageItemCount, ViewParameter.JobID, ViewParamater.<ViewParameterName>

Returns

The number of items that were requested according to the PageItemCount parameter

Example request url

<?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</PagesCount>
  <ItemList>
    <Item>
      <ItemID>1092</ItemID> 
      <Year>2000</Year>
      <Make>BMW</Make>
      <Model>328CI</Model> 
      <Price>$7490</Price> 
      <Telephone>4049141131</Telephone> 
      <AreaCode>404</AreaCode> 
      <Source>craigslist</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>craigslist</Source> 
    </Item>
  </ItemList>
</ViewGetItemsResponse>
		

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

Returns

A list of agents for an account.

Example request url

<?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 />
    </Agent>
    <Agent>
      <Created>2008-06-23 14:20:49</Created>
      <Modified />
      <AgentID>1003</AgentID>
      <Name>Scraped Data</Name>
      <Description />
      <Settings />
    </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

Agent.StartDate (YYYY-MM-DD), Agent.EndDate (YYYY-MM-DD)

Returns

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

Example request url

<?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 or resumes the Agent

Required parameters

AgentID

Optional parameters

AgentParameter.<AgentParameterName>

Returns

A message containing the Job Id of an agent.

Example request url

<?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

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

<?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

Job.Get

Description

Gets the details of a job by the Job ID

Required parameters

JobID

Returns

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

Example request url

<?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>
  <ActiveJob>True</ActiveJob>
  <Job>
    <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.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

<?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.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

<?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

<?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