Nut_Api_Core Class Reference

---

Description

Core API methods revealed via web services.

Core methods revealed via web services (currently SOAP and JSON-RPC).

Date fields in the API are either NULL or strings. Dates are accepted/returned in Zend_Date::ATOM format. Info on Zend_Date::ATOM here: http://framework.zend.com/manual/en/zend.date.constants.html

Public Member Functions
	add ($num1, $num2)
	For testing.
	addEmail ($emailString)
	Saves the given e-mail message.
	deleteAccount ($accountId, $rev)
	Delete an account.
	deleteActivity ($activityId, $rev)
	Delete an activity.
	deleteContact ($contactId, $rev)
	Delete a contact.
	deleteLead ($leadId, $rev)
	Delete a lead.
	deleteProduct ($productId, $rev)
	Delete a product.
	deleteTeam ($teamId, $rev)
	Delete a team.
	deleteUser ($userId, $rev)
	Delete a user.
	describeCustomFields ()
	Gets all of the custom fields available for Leads, Accounts and Contacts, including appropriate meta-information.
	editAccount ($accountId, $rev, $account)
	Edit an account.
	editActivity ($activityId, $rev, $activity)
	Edit an activity.
	editContact ($contactId, $rev, $contact)
	Edit a contact.
	editLead ($leadId, $rev, $lead)
	Edit a lead.
	editProduct ($productId, $rev, $product)
	Edit a product.
	editStep ($stepId, $rev, $step)
	Update a process step.
	editTeam ($teamId, $rev, $team)
	Edit a team.
	editUser ($userId, $rev, $user)
	Edit a user.
	findAccounts ($query, $orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1, $stubResponses=true)
	Find accounts matching a specified query.
	findAccountTypes ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all active account types (to be applied to an account)
	findActivities ($query, $orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1, $stubResponses=true)
	Find activities matching a specified query.
	findActivityTypes ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all active activity types.
	findCompetitors ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all active Competitors.
	findContacts ($query=null, $orderBy= 'id', $orderDirection= 'ASC', $limit=50, $page=1, $stubResponses=true)
	Find contacts associated with a specified account or lead.
	findDelays ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all active Delays (seen in Step responses in availableDelayIds)
	findIndustries ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all active Industries (to be applied to an account)
	findLead_Outcomes ($orderBy= 'description', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all possible outcomes for a closed lead.
	findLeads ($query, $orderBy= 'id', $orderDirection= 'ASC', $limit=50, $page=1, $stubResponses=true)
	Find leads matching a specified query.
	findMarkets ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all active markets.
	findMilestones ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all active milestones.
	findOrigins ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all active Origins.
	findProducts ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1, $stubResponses=true)
	Get all active products.
	findSettings ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
	Return all publicly-visible settings.
	findSources ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all active Sources.
	findTags ()
	Get all active tags.
	findTeams ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all active Teams.
	findTerritories ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all territories.
	findTimeline ($query, $orderBy= 'time', $orderDirection= 'ASC', $limit=50, $page=1, $stubResponses=true)
	Find timeline events (Activities, Emails and Notes) for an Entity.
	findUsers ($orderBy= 'last_name', $orderDirection= 'ASC', $limit=50, $page=1)
	Get all active Users.
	getAccount ($accountId, $rev=null)
	Get the specified Account.
	getActivity ($activityId, $rev=null)
	Get the specified Activity.
	getAnalyticsReport ($reportType, $period, $filter=null, $options=null)
	Returns graph data and overview information for various sales analytics reports.
	getContact ($contactId, $rev=null)
	Get the specified Contact.
	getEmail ($emailId, $rev=null)
	Get the specified Email.
	getLead ($leadId, $rev=null)
	Get the specified lead.
	getMobileSettings ()
	Return all mobile-related settings in a simple key-value array.
	getNote ($noteId, $rev=null)
	Get the specified Note.
	getProduct ($productId, $rev=null)
	Get all information for a product (including full price list).
	getTeam ($teamId, $rev=null)
	Get the specified Team.
	getUpdateTimes ()
	Gets the last-updated times of each of the provisioning bins.
	getUser ($userId, $rev=null)
	Get all info about a user.
	listBackups ()
	List available and running backups.
	newAccount ($account)
	Create a new account.
	newActivity ($activity)
	Create a new activity.
	newContact ($contact)
	Create a new contact.
	newLead ($lead)
	Create a new Lead.
	newProduct ($product)
	Create a new product.
	newTag ($tag)
	Create a new tag.
	newTeam ($team)
	Create a new team.
	newUser ($user)
	Create a new user.
	searchAccounts ($string, $limit=10)
	Return a list of Account stubs matching a given search string.
	searchByEmail ($emailAddressString)
	Works just like searchUniversal, but only searches by email address.
	searchCompetitors ($string, $limit=10)
	Return a list of Competitor stubs matching a given search string.
	searchContacts ($string, $limit=10)
	Return a list of Contact stubs matching a given search string.
	searchContactsAndUsers ($string, $limit=10)
	Return a list of Contact and User stubs matching a given search string.
	searchLeads ($string, $limit=40)
	Return a list of Lead stubs matching a given search string.
	searchProducts ($string, $limit=10)
	Return a list of Product stubs matching a given search string.
	searchSources ($string, $limit=10)
	Return a list of Source stubs matching a given search string.
	searchUniversal ($string)
	Return a list of Contact, Lead, and Account stubs matching a given search string.
	searchUsersAndTeams ($string, $limit=10)
	Return a list of User and Team stubs matching a given search string.
	startBackup ()
	Initiate downloadable backup.

---

Member Function Documentation

add	(	$	num1,
		$	num2
	)

For testing.

Parameters:

int	$num1
int	$num2

Returns:

int

addEmail

(

$

emailString

)

Saves the given e-mail message.

Parameters:

string

$emailString

E-mail in RFC 822 format

Returns:

Email

deleteAccount	(	$	accountId,
		$	rev
	)

Delete an account.

Parameters:

int	$accountId	account ID to delete
string	$rev

Returns:

Boolean

deleteActivity	(	$	activityId,
		$	rev
	)

Delete an activity.

Parameters:

int	$activityId	activity ID to delete
string	$rev

Returns:

Boolean

deleteContact	(	$	contactId,
		$	rev
	)

Delete a contact.

Parameters:

int	$contactId	contact ID to delete
string	$rev

Returns:

Boolean

deleteLead	(	$	leadId,
		$	rev
	)

Delete a lead.

Parameters:

int	$leadId	lead ID to delete
string	$rev

Returns:

Boolean

deleteProduct	(	$	productId,
		$	rev
	)

Delete a product.

Parameters:

int	$productId	product ID to delete
string	$rev

Returns:

Boolean

deleteTeam	(	$	teamId,
		$	rev
	)

Delete a team.

Parameters:

int	$teamId	team ID to delete
string	$rev

Returns:

Boolean

deleteUser	(	$	userId,
		$	rev
	)

Delete a user.

Parameters:

int	$userId	user ID to delete
string	$rev

Returns:

Boolean

describeCustomFields

(

)

Gets all of the custom fields available for Leads, Accounts and Contacts, including appropriate meta-information.

Example output:

 {
    'Leads': [ CustomEavEntityAttribute, ... ],
    'Contacts': [ CustomEavEntityAttribute, ... ],
    'Accounts': [ CustomEavEntityAttribute, ... ]
 }

See also:

Nut_Api_Render_Model_CustomEavEntityAttribute for CustomEavEntityAttribute output format

Returns:

array

editAccount	(	$	accountId,
		$	rev,
		$	account
	)

Edit an account.

See newAccount() for input specification.

Fields which allow multiples (phone, email, URL, etc.) will be completely replaced by whatever data you supply, if you supply any data for the field. (Eg. the new phone array replaces all previously known phone numbers.) If you are updating a multi-value field, you must include all values you wish to keep (not just the new values) for the field.

If a note is specified, it will be added to the existing notes (preexisting notes are not affected).

Tags can be edited as well -- the specified array of tags will replace all existing tags, so you should retrieve and include existing tags if you only want to add a new one. Note that the tags must already exist (see `newTag()` )

 account: {
    'name': 'New Account Name',
    'industryId': '2',
    'phone': [ '717-555-0467', {'office': '877-000-9237'} ],
    'tags': ['some tag name', 'some other tag'],
    
    // Include keys and values to be updated
 }

Returns the updated account; see Nut_Api_Render_Model_Account for output details.

Parameters:

int	$accountId	account ID to edit
string	$rev
array	$account	updated account information

Returns:

Account

See also:

newAccount() for input specification

Nut_Api_Render_Model_Account for output details

editActivity	(	$	activityId,
		$	rev,
		$	activity
	)

Edit an activity.

See newActivity() for input specification.

These fields can be edited with this method:

• name (string)
• description (string)
• lead (see example below)
• status (int)
• location (see example below)
• startTime (Zend_Date::ATOM)
• endTime (Zend_Date::ATOM)
• activityTypeId
• isAllDay (boolean)
• isTimed (boolean)
• participants (see example below)
• logNote (array containing key 'note')

All fields are optional. Any parameters which are not included in the API request will be left untouched.

Participants specified here will replace all curently existing ones; if you include a 'participants' key, you must include any existing participants you'd like to keep. If you don't include a 'participants' key, the activity's participants will not be modified.

An activity is logged by setting 'status' to 1 and optionally including a logNote.

Possible values for the status field:

  0 = not logged
  1 = logged

 activity: {
    'name': 'NewName',
    'lead': {
         'entityType': 'Leads',
         'id': 1001
     },
    'endTime': '2011-02-13T14:53:27+01:00',
    'activityTypeId': 1,
    'participants': [
        {  'id': 42,
           'entityType': 'Users'
        },
        {  'id': 32,
           'entityType': 'Contacts'
        }
     ],
    'status': 1,
    'logNote': {
          'note': 'Meeting went swimmingly!'
    }
 }

Returns the updated activity; see Nut_Api_Render_Model_Activity for output details.

Parameters:

int	$activityId	activity ID to edit
string	$rev
array	$activity	updated activity information

Returns:

array Activity

See also:

newActivity() for input specification

Nut_Api_Render_Model_Activity for output details

editContact	(	$	contactId,
		$	rev,
		$	contact
	)

Edit a contact.

See newContact() for input specifications.

Fields which allow multiples (phone, email, URL, etc.) will be completely replaced by whatever data you supply, if you supply any data for the field. (Eg. the new phone array replaces all previously known phone numbers.) If you are updating a multi-value field, you must include all values you wish to keep (not just the new values) for the field.

If a note is specified, it will be added to the existing notes (preexisting notes are not affected).

Tags can be edited as well -- the specified array of tags will replace all existing tags, so you should retrieve and include existing tags if you only want to add a new one. Note that the tags must already exist (see `newTag()` )

 contact: {
     'name': 'Andy Fowler',
     'phone': [ '717-555-0480', '+216 717-555-6633', {'work': '877-555-5001'} ],
     'tags': ['some tag name', 'some other tag'],
 }

Returns the updated contact; see Nut_Api_Render_Model_Contact for output details. Note that if an e-mail address is modified, added, or removed, then the 'lastContactedDate' and the 'contactedCount' values in the returned contact may be inaccurate.

Parameters:

int	$contactId	the contact ID to update
string	$rev
array	$contact	the updated contact information

Returns:

Contact

See also:

newContact() for input specifications

Nut_Api_Render_Model_Contact for output details

editLead	(	$	leadId,
		$	rev,
		$	lead
	)

Edit a lead.

Also used for adding, deleting, and editing related entities.

The assignee specified here will replace the existing one.

Similarly, specifying any related entity (e.g. a product or contact) via the applicable key will replace all existing relationships. Adding a related entity is done by appending the new relationship to the end of the list, and deletion is possible by removing the relationship from the list.

Tags can be edited as well -- the specified array of tags will replace all existing tags, so you should retrieve and include existing tags if you only want to add a new one. Note that the tags must already exist (see `newTag()` )

A note specified here will be added to the preexisting notes. You cannot remove notes.

Possible values for the competitor->status field:

 0 = STATUS_POTENTIAL
 1 = STATUS_STOLE  // they stole from us
 2 = STATUS_BEAT   // we beat them

Any values to be updated should be specified in an array like the following (all fields are optional):

 "lead": {
     'primaryAccount': {'id': '1234'},
     'market': {'id': '1'},
     'tags': ['some tag name', 'some other tag'],
     'confidence': 50,
     'assignee': { 'entityType': 'Teams', 'id': 12 },
     'contacts': [
         {
             'id': 2,
             'rev': 0,
             'relationship': 'First Contact'
         } , ...
     ],
     'accounts': [
         array(
             'id': 6,
             'rev': 7,
             'relationship': 'Secondary account'
         ) , ...
     },
     'products': [
         {
             'id': 900,
             'rev': 4,
             'relationship': 'Principal product',
             'quantity': 12,
             'price': {
                 'amount': '100.50',
                 'currency': 'USD'
             },
         } , ...
     ],
     'competitors': [
         {
             'id': 9001,
             'rev': 2,
             'relationship': 'Up-and-coming',
             'status': 0
         } , ...
     ],
     'sources': [
         {
             'id': 5,
             'rev': 5,
         } , ...
     ],
     "note": "new note (string value)",
     'customFields': {
         'Tracking #': '4212'
     }
 }

Leads can be closed by specifying an outcome and optionally a closing value and closing time. API clients should use the findLead_Outcomes() to retrieve a list of possible outcomes.

 "lead": {
    'outcome': {
        'id': '1',
        'entityType': 'Lead_Outcomes',
        'rev': '0',
        'type': 10,
        'description': 'Won'
     },
     'closedTime': '2011-03-13T14:53:27-05:00',  // optional. Zend_Date::ATOM format

To set the lead as pending, pass a true value as isPending.

 "lead": {
    'isPending': true
 }

Multiple outcomes of the same type can be configured company-wide in the Nutshell Setup interface. Outcome types:

  10 = Won
  11 = Lost
  12 = Cancelled

To reopen a lead, set the status to 0

See newLead() for input formatting specification.

You can upload files to the lead by adding sparse objects to the 'file' property. See http://www.nutshell.com/api/files.html for more information on uploading and downloading files

Returns the updated lead; see Nut_Api_Render_Model_Lead for output details.

Parameters:

int	$leadId	lead ID to update
string	$rev
array	$lead	new lead information

Returns:

array Lead

See also:

newLead() for input formatting specification

findLead_Outcomes() to find possible outcomes

Nut_Api_Render_Model_Lead for output details

editProduct	(	$	productId,
		$	rev,
		$	product
	)

Edit a product.

The name field is required. Products must have a price set for each market to be available for that market. The parameter "sku" and "unit" are dependent on "type" (product or service respectively). See Nut_Api_Render_Model_Product for details.

Parameters:

int	$productId	product ID to update
string	$rev
array	$product	new product information

Returns:

array Product

See also:

newProduct() for input formatting specification

Nut_Api_Render_Model_Product for output details

editStep	(	$	stepId,
		$	rev,
		$	step
	)

Update a process step.

All fields (of the step) are optional. Any values which are not included in the API request will be left untouched.

The following fields can be edited with this method:

• assignee
• delay
• status
• choice

Possible values for the status field:

 0 = STATUS_NEW
 1 = STATUS_DELAYED  // DEPRECATED
 2 = STATUS_COMPLETED
 3 = STATUS_SKIPPED

Sample input for the step paramater:

 "step": {
     'assignee': {
         'entityType': 'Users',
         'id': 12
     },
     'status': 2,
     'choice': {
         'entityType': 'Contacts',
         'id': '13',
         'rev': 5,
         'fieldName': 'phone',
         'fieldIndex': 'cell'
     },
     'delay': {
         'entityType': 'Delays',
         'id': 40,
         'rev': 5,
         'note': 'Going on vacation'
     }
 }

Returns the updated step; see Nut_Api_Render_Model_Step for output details.

Parameters:

int	$stepId	step ID to update
string	$rev
array	$step	updates step information

Returns:

array Step

See also:

Nut_Api_Render_Model_Step for output details

editTeam	(	$	teamId,
		$	rev,
		$	team
	)

Edit a team.

Parameters:

int	$teamId	team ID to update
string	$rev
array	$team	new team information

Returns:

array Team

See also:

newTeam() for input formatting specification

Nut_Api_Render_Model_Team for output details

editUser	(	$	userId,
		$	rev,
		$	user
	)

Edit a user.

See newUser() for input specifications.

Fields which allow multiples ("emails" and "teams") will be completely replaced by whatever data you supply, if you supply any data for the field. (Eg. the teams array replaces all previously known team memberships.) If you are updating these fields, you must include all values you wish to keep (not just the new values) for the field.

 user: {
     'emails': [
         'jhalpert@dundermifflin.com',
         'jim.halpert@dundermifflin.com'
     ],
     'teams': {
         'viewAll': [],
         'viewOwn': [teamId, teamId],
         'viewTeam': []
     },
     'sendInvite': true // optional
 }

Returns the updated user; see Nut_Api_Render_Model_User for output details.

Parameters:

int	$userId	the user ID to update
string	$rev
array	$user	the updated user information

Returns:

User

See also:

newUser() for input specifications

Nut_Api_Render_Model_User for output details

findAccounts	(	$	query,
		$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1,
		$	stubResponses = true
	)

Find accounts matching a specified query.

Currently implemented query keys:

• accountType -> An account type id. See findAccountTypes()
• industry -> An array of industry ids. See findIndustries()
• origin -> An array of origin ids. See findOrigins()
• hasOpenLeads -> boolean. If true, only return accounts associated with open leads.

Example query:

 // Look for all accounts associated with industries 1 or 2 that have open leads:
 "query": {
     "industry": [ 1, 2 ],
     "hasOpenLeads": true
 }

Returns an array of Account stubs, or if $stubResponses is false, an array of full Account objects.

Example output (with Account stubs):

 "result": [
   {
      "stub": true, 
      "id": 80, 
      "entityType": "Accounts", 
      "rev": "2", 
      "name": "3M", 
      "regions": [ "Rexburg, ID" ]
   }, 
   {
      "stub": true, 
      "id": 176, 
      "entityType": "Accounts", 
      "rev": "0", 
      "name": "Abbott Laboratories", 
      "regions": [ "Tallahassee, FL" ]
   }
 ]

See Nut_Api_Render_Model_Account for output detail.

Parameters:

array	$query	query keys and values
string	$orderBy
string	$orderDirection
int	$limit	(max 100)
int	$page
bool	$stubResponses	whether to return stub responses instead of full responses (default true)

Returns:

array Account

See also:

Nut_Api_Render_Model_Account for output detail

findAccountTypes	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all active account types (to be applied to an account)

Example output:

 "result": [
    {
       "id": 1, 
       "name": "Customer"
    }, 
    {
       "id": 2, 
       "name": "Vendor"
    }
 ]

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array array of AccountTypes

findActivities	(	$	query,
		$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1,
		$	stubResponses = true
	)

Find activities matching a specified query.

Currently implemented query keys:

• leadId -> An optional lead ID that the activity is associated with
• contactId -> An optional array of contact IDs who are participants in the activity
• userId -> An optional array of user IDs who are participants in the activity
• status -> An optional status constant.
• activityTypeId -> An optional array of activity type IDs

Possible values for the "status" key:

  0 = STATUS_SCHEDULED
  1 = STATUS_LOGGED
  2 = STATUS_CANCELLED
 -1 = STATUS_OVERDUE (note: STATUS_OVERDUE implies STATUS_SCHEDULED)

Example query:

 // Find all scheduled activities associated with lead 42
 "query": {
     "leadId": 42,
     "status": 0
 }

Returns an array of Activity stubs, or if $stubResponses is false, an array of full Activity objects.

Example output (with Activity stubs):

 "result": [
    {
       "stub": true, 
       "id": 70, 
       "entityType": "Activities", 
       "rev": "0", 
       "name": "Chat with HQ", 
       "startTime": "2010-09-11T11:00:00+0000", 
       "endTime": "2010-09-11T13:00:00+0000", 
       "activityType": {
          "stub": true, 
          "id": 2, 
          "entityType": "Activity_Types", 
          "rev": "0", 
          "name": "Meeting"
       }, 
       "status": 0
    }
 ]

See Nut_Api_Render_Model_Activity for output details.

Parameters:

array	$query	query keys and values
string	$orderBy
string	$orderDirection
int	$limit	(max 100)
int	$page
bool	$stubResponses	whether to return stub responses instead of full responses (default true)

Returns:

array Activity

See also:

Nut_Api_Render_Model_Activity for output details

findActivityTypes	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all active activity types.

Example output:

 "result": [
    {
       "stub": true, 
       "id": 2, 
       "entityType": "Activity_Types", 
       "rev": "0", 
       "name": "Meeting"
    }, 
    {
       "stub": true, 
       "id": 1, 
       "entityType": "Activity_Types", 
       "rev": "0", 
       "name": "Phone Call"
    }
 ]

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array array of Activity_Types

See also:

Nut_Api_Render_Model_Activity_Type

findCompetitors	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all active Competitors.

Returns stubs for all active Competitors

Example output:

 "result": [
    {
       "stub": true, 
       "id": 26, 
       "entityType": "Competitors", 
       "rev": "0", 
       "name": "AK Steel Holding"
    }, 
    {
       "stub": true, 
       "id": 44, 
       "entityType": "Competitors", 
       "rev": "0", 
       "name": "Amazon.com"
    }
 ]

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array array of Competitors

findContacts	(	$	query = null,
		$	orderBy = 'id',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1,
		$	stubResponses = true
	)

Find contacts associated with a specified account or lead.

Query parameters:

• accountId
• leadId

Example query:

 // Find contacts associated with lead 42
 "query": {
     "leadId": 42
 }

Returns an array of Contact stubs, or if $stubResponses is false, an array of full Contact objects.

Example response (with Contact stubs):

 "result": [
    {
       "stub": true, 
       "id": 33, 
       "entityType": "Contacts", 
       "rev": "5", 
       "name": "Julie Branch", 
       "jobTitle": "Lead Designer, DuPont"
    }, 
    {
       "stub": true, 
       "id": 40, 
       "entityType": "Contacts", 
       "rev": "5", 
       "name": "Vivian Carver", 
       "jobTitle": ""
    }
 ]

See Nut_Api_Render_Model_Contact for additional output details.

Parameters:

array	$query	query keys and values
string	$orderBy
string	$orderDirection
int	$limit	(max 100)
int	$page
bool	$stubResponses	whether to return stub responses instead of full responses (default true)

Returns:

array Contacts

See also:

Nut_Api_Render_Model_Contact for additional output details

findDelays	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all active Delays (seen in Step responses in availableDelayIds)

Returns stubs for all active Delays.

Example output:

 "result": [
    {
       "stub": true, 
       "id": 1, 
       "entityType": "Delays", 
       "rev": "0", 
       "name": "Away from desk"
    }
    {
       "stub": true, 
       "id": 2, 
       "entityType": "Delays", 
       "rev": "0", 
       "name": "On vacation"
    }
 ]

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array Delays

findIndustries	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all active Industries (to be applied to an account)

Returns stubs for all active Industries.

Example output:

 [
    {
       "stub": true, 
       "id": 1, 
       "entityType": "Industries", 
       "rev": "0", 
       "name": "Accounting"
    }, 
    {
       "stub": true, 
       "id": 2, 
       "entityType": "Industries", 
       "rev": "0", 
       "name": "Aerospace"
    }
 ]

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array array of Industries

findLead_Outcomes	(	$	orderBy = 'description',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all possible outcomes for a closed lead.

Example output:

 [
    {
       "id": 1006, 
       "entityType": "Lead_Outcomes", 
       "rev": "0", 
       "description": "Cancelled - Other", 
       "type": "12"
    },
    {
       "id": 1001, 
       "entityType": "Lead_Outcomes", 
       "rev": "0", 
       "description": "Lost - Too expensive", 
       "type": "11"
    }, 
    {
       "id": 1, 
       "entityType": "Lead_Outcomes", 
       "rev": "0", 
       "description": "Won", 
       "type": "10"
    }
 ]

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array Lead_Outcomes

See also:

Nut_Api_Render_Model_Lead_Outcome

findLeads	(	$	query,
		$	orderBy = 'id',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1,
		$	stubResponses = true
	)

Find leads matching a specified query.

Query parameters:

 {
   'status': 10,  // STATUS_OPEN = 0; STATUS_WON = 10; STATUS_LOST = 11; STATUS_CANCELLED = 12;
   'filter': 1,   // MY_LEADS = 0; MY_TEAM_LEADS = 1; ALL_LEADS = 2
   'accountId': 10,
   'contactId': 4,
   'dueTime': '> 2010-09-15',  // or '< 2009-02-02'
   'assignee': [ Team, User, User ],  // Team, User: { 'entityType': 'Teams', 'id': 12 }
   'origin': [ originId, originId ],
   'source': [ sourceId, sourceId ]
 }

These parameters are ANDed in the query. For parameters which accept multiple values, the values are ORed together.

If you use the 'filter' parameter, the only other parameter allowed is 'status'.

Possible comparison operators for the 'dueTime' comparison are '<', '>', '=', '<=', '>='

Returns an array of Lead stubs, or an array of full Leads if $stubResponses is false. See Nut_Api_Render_Model_Lead for output details.

See also:

Nut_Api_Render_Model_Lead for output details

Parameters:

array	$query	query keys and values
string	$orderBy
string	$orderDirection
int	$limit	(max 100 for non-stub responses)
int	$page
bool	$stubResponses	whether to return stub responses instead of full responses (default true)

Returns:

array Lead

findMarkets	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all active markets.

Returns stubs for all active Markets.

Example output:

 "result": [
    {
       "stub": true, 
       "id": 2, 
       "entityType": "Markets", 
       "rev": "0", 
       "name": "U.K."
    }, 
    {
       "stub": true, 
       "id": 1, 
       "entityType": "Markets", 
       "rev": "0", 
       "name": "U.S."
    }
 ]

See also:

Nut_Api_Render_Model_Market for output details

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array Markets

findMilestones	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all active milestones.

Example output:

 "result": [
    {
       "id": 2, 
       "entityType": "Milestones", 
       "rev": "0", 
       "name": "Contacting", 
       "position": 2
    }, 
    {
       "id": 3, 
       "entityType": "Milestones", 
       "rev": "0", 
       "name": "Decision", 
       "position": 3
    }
 ]

See also:

Nut_Api_Render_Model_Milestone for output details

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array Milestones

findOrigins	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all active Origins.

Returns stubs for all active Origins.

Example output:

 "result": [
    {
       "stub": true, 
       "id": 2, 
       "entityType": "Origins", 
       "rev": "2334", 
       "name": "API"
    },
    {
       "stub": true, 
       "id": 1, 
       "entityType": "Origins", 
       "rev": "0", 
       "name": "Web"
    }
 ]

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

See also:

Nut_Api_Render_Model_Origin for output details

Returns:

array Origins

findProducts	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1,
		$	stubResponses = true
	)

Get all active products.

Example output (with Product stubs):

 "result": [
    {
       "stub": true, 
       "id": 4, 
       "entityType": "Products", 
       "rev": "274", 
       "name": "EconoLight Paper"
    }, 
    {
       "stub": true, 
       "id": 1, 
       "entityType": "Products", 
       "rev": "291", 
       "name": "Sabre Laserwriter"
    }
 ]

For more output details (especially for full Product objects), see Nut_Api_Render_Model_Product.

See also:

Nut_Api_Render_Model_Product for output details

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page
bool	$stubResponses	whether to return Product stubs instead of full Product objects. default true.

Returns:

array Products

findSettings	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Return all publicly-visible settings.

If currently impersonating a user, the values for settings that have been set for that user will override the global values.

Example response:

 "result": {
   "auto_provision_mobiles":"1",
   "businesshours_end":"17:00:00",
   "businesshours_start":"09:00:00",
   "country_calling_code":"1",
   "default_country_code":"US",
   "default_market_id":"1",
   "fiscal_year":"1-1",
   "inception_date":"2006-1-1",
   "mobile_login_preference":"passcode",
   "work_week_start":"7"
 }

See also:

Nut_Api_Render_Model_Setting for additional output details

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array Setting

findSources	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all active Sources.

Returns stubs for all active Sources.

Example output:

 "result": [
    {
       "stub": true, 
       "id": 2, 
       "entityType": "Sources", 
       "rev": "88", 
       "name": "Cold call"
    },
    {
       "stub": true, 
       "id": 1, 
       "entityType": "Sources", 
       "rev": "97", 
       "name": "Midatlantic Office Supplies Convention"
    }
 ]

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array Sources

findTags

(

)

Get all active tags.

Tags can be added to leads, accounts, and contacts via their respective edit methods

Example output:

 "result": {
    'Leads': ['tag1', 'tag2'],
    'Contacts': [],
    'Accounts': ['tag1']
 }

Returns:

array

findTeams	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all active Teams.

Returns stubs for all active Teams

Example output:

 "result": [
    {
       "stub": true, 
       "id": 1000, 
       "entityType": "Teams", 
       "rev": "0", 
       "name": "East Coast"
    }, 
    {
       "stub": true, 
       "id": 1001, 
       "entityType": "Teams", 
       "rev": "0", 
       "name": "West Coast"
    }
 ]

See also:

Nut_Api_Render_Model_Team for output details

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array Teams

findTerritories	(	$	orderBy = 'name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all territories.

Example output:

 "result": [
    {
       "id": 1,
       "name": "North West"
    },
    {
       "id": 2,
       "name": "East coast"
    }
 ]

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array array of Territories

findTimeline	(	$	query,
		$	orderBy = 'time',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1,
		$	stubResponses = true
	)

Find timeline events (Activities, Emails and Notes) for an Entity.

Example query:

 // Find timeline for Lead ID 1000:
 "query": {
     "entityType": "Leads",
     "id": 1000
 }

Returns an array of Entity stubs, or if $stubResponses is false, an array of full Entity objects.

Example output (with stubs):

 "result":[
    {
       "stub":true,
       "id":1351,
       "entityType":"Activities",
       "rev":"2",
       "name":"Skype call",
       "startTime":"2011-02-16T14:30:00+0000",
       "endTime":"2011-02-16T15:30:00+0000",
       "activityType":{
          "stub":true,
          "id":3,
          "entityType":"Activity_Types",
          "rev":"0",
          "name":"Virtual Meeting"
       },
       "status":1,
       "logNote":{
          "id":2661,
          "entityType":"Notes",
          "rev":"1",
          "note":"Got a great vibe from this.",
          "user":{
              "stub": true,
              "id": 1,
              "entityType": "Users",
              "rev": "0",
              "name": "Andy Fowler"
          },
          "originId":2,
          "files":[
             {
                "entityType":"Files",
                "id":13245,
                "uri":"https:\/\/dev.nutshell.com\/file\/api\/13245",
                "name":"video_file2.mov",
                "mime":"video\/quicktime",
                "rev":"dd69db4f79fba9c316f388fd500269fafc1808a6",
                "size":1006108,
                "clientType":"video\/iphone",
                "duration":10123
             },
          ]
       }
    },
    {
       "id":1711,
       "entityType":"Notes",
       "rev":"0",
       "note":"This client has strict security requirements - see the RFP for details.",
       "user":{
           "stub": true,
           "id": 1,
           "entityType": "Users",
           "rev": "0",
           "name": "Andy Fowler"
       },
       "originId":2,
       "date":"2011-02-14T00:00:00+0000"
    },
    {
       "stub":true,
       "id":47,
       "entityType":"Emails",
       "subject":"Re: Would like to hear more",
       "sentTime":"2011-01-05T15:30:00+0000",
       "createdTime":"2011-02-21T19:36:12+0000",
       "bodyExcerpt":"Hello Mr Barclay,\n\nThank you for your interest...",
       "to":[
          "bspender@fortune500.com"
       ],
       "from":[
          "sales@nutshell.com"
       ],
       "cc":[
       ]
    },
 ],

Returns an array of Activities, Emails and Notes entities. See Nut_Api_Render_Model_Activity, Nut_Api_Render_Model_Email, Nut_Api_Render_Model_Note for output details.

See also:

Nut_Api_Render_Model_Lead for output details

Parameters:

array	$query	query keys and values
string	$orderBy
string	$orderDirection
int	$limit
int	$page
bool	$stubResponses	whether to return stub responses instead of full responses (default true)

Returns:

array

See also:

Nut_Api_Render_Model_Activity, Nut_Api_Render_Model_Email, Nut_Api_Render_Model_Note for output detail

findUsers	(	$	orderBy = 'last_name',
		$	orderDirection = 'ASC',
		$	limit = 50,
		$	page = 1
	)

Get all active Users.

Returns stubs for all active Users

Example output:

 "result": [
    {
       "stub": true, 
       "id": 3, 
       "entityType": "Users", 
       "rev": "1", 
       "name": "Chris Dzombak"
       "isEnabled": true,
       "isAdministrator": false,
    }, 
    {
       "stub": true, 
       "id": 1, 
       "entityType": "Users", 
       "rev": "1", 
       "name": "Andy Fowler",
       "isEnabled": true,
       "isAdministrator": false,
    }
 ]

See also:

Nut_Api_Render__Model_User

Parameters:

string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns:

array Users

getAccount	(	$	accountId,
		$	rev = null
	)

Get the specified Account.

See Nut_Api_Render_Model_Account for output details.

Parameters:

int	$accountId	account ID to get
string	$rev

Returns:

Account

See also:

Nut_Api_Render_Model_Account for output details

getActivity	(	$	activityId,
		$	rev = null
	)

Get the specified Activity.

See Nut_Api_Render_Model_Activity for output details.

See also:

Nut_Api_Render_Model_Activity for output details

Parameters:

int	$activityId	activity ID to get
string	$rev

Returns:

Activity

getAnalyticsReport	(	$	reportType,
		$	period,
		$	filter = null,
		$	options = null
	)

Returns graph data and overview information for various sales analytics reports.

These are the reports that are visible on the home page of the Reports tab.

Valid reportType strings:

• Effort (Activities + activities on won leads)
• NewLeads (# of new leads)
• Pipeline (# of open leads + open lead value)
• SalesCycle (Avg. # of days to close a lead)
• SalesProcess (Leads on time)
• Success (statistics about won leads)

Valid period strings:

• "yyyy" for specific whole years (e.g. "2009")
• "yyyy-mm" for specific months (e.g. "2009-10")
• "yyyy-Q#" for specific quarters (e.g. "2009-Q3" for 3rd quarter of 2009)
• "timestamp-timestamp" for exact ranges (e.g. "1277930662-1277956800")
• "w" for current week
• "m" for current month
• "y" for current year
• "-d30" for past 30 (or x) days

The filter is an optional array of entity dictionaries (entityName and entityId). Valid entityNames:

• Users
• Teams
• Products
• Sources

"filter": [ { "entityId" : 2, "entityName" : "Products" }, { "entityId" : 5, "entityName" : "Sources" } ]

Some reportTypes may have specific options. For all types, a timezone can be specified.

Options: { "timezone": "America/New_York", // if omitted and authenticated as a user, user default will be used "useEmails": (bool), // only valid for Effort reports. "includeCanceled": (bool) // only valid for Success reports. }

Response looks like: { "seriesData": { "total_effort": [[1318982400000,3],[1319068800000,5]], "successful_effort": [[1318982400000,3],[1319068800000,5]], } "summaryData": { "total_effort": { "sum": 0, "avg": 0, "min": 0, "max": 0, "sum_delta": 0, "avg_delta": 0, "min_delta": 0, "max_delta": 0 }, "successful_effort": { "sum": 0, "avg": 0, "min": 0, "max": 0, "sum_delta": 0, "avg_delta": 0, "min_delta": 0, "max_delta": 0 }, "periodDescription": "between March 1 and today" "deltaPeriodDescription": "between February 1 and March 1" }

Parameters:

string	$reportType
string	$period
array	$filter	(optional)
array	$options	(optional)

Returns:

array

getContact	(	$	contactId,
		$	rev = null
	)

Get the specified Contact.

See Nut_Api_Render_Model_Contact for output details.

Parameters:

int	$contactId	contact ID to get
string	$rev

Returns:

Contact

See also:

Nut_Api_Render_Model_Contact for output details

getEmail	(	$	emailId,
		$	rev = null
	)

Get the specified Email.

See Nut_Api_Render_Model_Email for output details.

Parameters:

int	$emailId	email ID to get
string	$rev

Returns:

Email

See also:

Nut_Api_Render_Model_Email for output details

getLead	(	$	leadId,
		$	rev = null
	)

Get the specified lead.

See Nut_Api_Render_Model_Lead for output details.

See also:

Nut_Api_Render_Model_Lead for output details

Parameters:

int	$leadId	lead ID to get
string	$rev

Returns:

Lead

getMobileSettings

(

)

Return all mobile-related settings in a simple key-value array.

Example response:

 "result":
 {
   "auto_provision_mobiles":"1",
   "mobile_login_preference":"passcode"
 }

Returns:

array Setting

getNote	(	$	noteId,
		$	rev = null
	)

Get the specified Note.

See Nut_Api_Render_Model_Note for output details.

Parameters:

int	$noteId	note ID to get
string	$rev

Returns:

Note

See also:

Nut_Api_Render_Model_Note for output details

getProduct	(	$	productId,
		$	rev = null
	)

Get all information for a product (including full price list).

See Nut_Api_Render_Model_Product for output details.

See also:

Nut_Api_Render_Model_Product for output details

Parameters:

int	$productId	ID of product to get
string	$rev

Returns:

Product

getTeam	(	$	teamId,
		$	rev = null
	)

Get the specified Team.

See Nut_Api_Render_Model_Team for output details.

See also:

Nut_Api_Render_Model_Team for output details

Parameters:

int	$teamId	ID of team to get
string	$rev

Returns:

Team

getUpdateTimes

(

)

Gets the last-updated times of each of the provisioning bins.

Returns array mapping entityNames to date/times. Time stamp is NULL if never changed.

Example output snippet:

 {
     'Industries': '2009-02-13T14:53:27+01:00',
     'Products': '2009-02-13T14:53:27+01:00',
     // ...
 }

Provisioning bins:

• Industries
• Products
• Outcomes
• Account_Types
• Milestones
• Origins
• Competitors
• Sources
• Teams
• Activity_Types

As with all API methods, date/times are returned in Zend_Date::ATOM format.

Returns:

array array of UpdateTimes

getUser	(	$	userId,
		$	rev = null
	)

Get all info about a user.

If no user ID is provided, returns logged-in user.

See Nut_Api_Render_Model_User for output details.

Parameters:

int	$userId	ID of user to get
string	$rev

Returns:

User

See also:

Nut_Api_Render_Model_User for output details

listBackups

(

)

List available and running backups.

Example output:

 "result": [
     {
       "date": "2012-01-18T22:25:20+0000",
       "status": "0",
       "percentComplete": "76",
       "file": ""
     },
     {
       "date": "2012-01-17T21:44:26+0000",
       "status": "1",
       "percentComplete": "100",
       "file": {
         "uri": "http://app01.nutshell.com/file/api/15160",
         "name": "2012-01-18_21:44:26-Nutshell-backup.zip",
         "mime": "application/zip",
         "size": 185013
       }
     }
   ]

Returns:

array

See also:

Nut_Api_Render_Model_Backup for output details

newAccount

(

$

account

)

Create a new account.

All fields are technically optional (it is possible to create a nameless account with no useful information).

account parameter:

 account: {
     'name': 'New Account Name',
     'industryId': '3',
     'accountTypeId': '1',
     'territoryId': '10',
     'url': [ 'http://www.andyfowler.com/', {'facebook': 'facebook.com/andy'} ],
     'phone': [ '717-555-0480', '717-555-0055', {'work': '877-555-9988'} ],
     'leads': [
         {
             'relationship': 'First account',
             'id': 12
         }, ...
     ],
     'contacts': [
         {
             'relationship': 'First contact',
             'id': 12,
         }, ...
     ],
     'address': [ 
         {
             'address_1':  '100 Second St.',
             'address_2':  'Apt. 4',
             'address_3':  'c/o Barclay Fowler',
             'city':       'Ann Arbor',
             'state':      'MI',
             'postalCode': '48103',  // or '48103-1234'
             'country': 'US',
         }
     ],
     'customFields': {
         'Number of Employees': '142',
     }
 }

Returns the new account; see Nut_Api_Render_Model_Account for output details.

Parameters:

array

$account

new account

Returns:

array Account

See also:

Nut_Api_Render_Model_Account for output details

newActivity

(

$

activity

)

Create a new activity.

The following fields are optional:

• lead (see example below)
• isAllDay (boolean)
• isTimed (boolean)
• location (see example below)
• participants (see example below)
• status (int)
• logNote (array containing key 'note')

Possible values for the status field:

  0 = not logged
  1 = logged

Example activity:

 activity: {
     'name': 'string value',
     'description': 'string value',
     'activityTypeId': 1, // int value
     'lead': {
          'entityType': 'Leads',
          'id': 1001
      },
     'startTime': '2009-02-13T14:53:27+01:00', // Zend_Date::ATOM format
     'endTime': '2009-02-13T14:53:27+01:00',   // Zend_Date::ATOM format
     'isAllDay': true
     'location': { 
         'name': 'Conference Room',
         'address_1': '229 Depot Street',
         'city': 'Ann Arbor',
         'state': 'Michigan',
         'country': 'US',
         'postal_code': 48104
     },
     'participants': [
         {  'id': 42,
            'entityType': 'Users'
         },
         {  'id': 32,
            'entityType': 'Contacts'
         }
     ]
 }

Returns the new activity; see Nut_Api_Render_Model_Activity for output details.

Parameters:

array

$activity

new activity

Returns:

Activity

See also:

Nut_Api_Render_Model_Activity for output details

newContact

(

$

contact

)

Create a new contact.

No specific field is required, but you must include a name, phone number, or email address - Nutshell won't create a totally empty contact.

contact parameter:

 contact: {
     'name': 'Andy Fowler',
     'phone': [ '717-555-0480', '+216 707-555-2903', {'work': '877-555-5555'} ],
     'email': ['andy@gmail.com', {'personal': 'fowler@charter.net'} ],
     'address': [
         {
             'address_1':  '100 Main St.',
             'address_2':  'Apt. 1',
             'address_3':  'c/o Barclay Fowler',
             'city':       'Ann Arbor',
             'state':      'MI',
             'postalCode': '48103',  // or '48103-1234'
             'country':    'US'
         }
     ],
     'leads': [
         {
             'relationship': 'First contact at company',
             'id': 24,
         }, ...
     ],
     'accounts': [
         {
             'relationship': 'Lead Developer',
             'id': 111,
         }, ...
     ],
     'customFields': {
         'Job Title': 'Lead Developer',
     },
     'territoryId': '10'
 }

The 'name' field may be a string (as shown above), or it may be a more complex object to provide more detailed information:

 "name": {
    'salutation': 'Mr.',
    'givenName': 'Andy',
    'familyName': 'Fowler'
 }

Returns the new contact; see Nut_Api_Render_Model_Contact for output details.

Parameters:

array

$contact

Returns:

array Contact

See also:

Nut_Api_Render_Model_Contact for output details

newLead

(

$

lead

)

Create a new Lead.

All fields are technically optional (it is possible to create a nameless lead with no useful information). Even if you create an "empty" lead, the default sales process will be attached to it.

Leads are created as Open status unless isPending is set to true.

Possible values for the competitor->status field:

 0 = STATUS_POTENTIAL
 1 = STATUS_STOLE  // they stole from us
 2 = STATUS_BEAT   // we beat them

Sample new lead:

 "lead": {
     'primaryAccount': {'id': '1234'},
     'dueTime': '2010-11-13T15:23:19-05:00',
     'market': {'id': '1'},
     'accounts': [
         {
             'relationship': 'Referred to us',
             'id': 111
         } , ...
     ],
     'contacts': [
         {
             'relationship': 'First contact',
             'id': 12
         } , ...
     ],
     'products': [
         {
             'relationship': 'Potentially interested',
             'quantity': 2,
             'price': {
                 'currency_shortname': 'USD',
                 'amount': '5000'
             },
             'id': 5,
         } , ...
     ],
     'competitors': [
         {
             'status': 2,
             'relationship': 'Might be cheaper than us',
             'id': 12,
         }
     ],
     'sources': [
         { 'id': 12 } , ...
     ],
     'confidence': 50,
     'assignee': {
         'entityType': 'Users',
         'id': 12
     },
     'customFields': {
         'Tracking #': '32ab',
         'Discount': {
             'currency_shortname': 'USD',
             'amount': '5000'
         },
     }
 }

Returns the new lead; see Nut_Api_Render_Model_Lead for output details.

Parameters:

array

$lead

new lead information

Returns:

array Lead

See also:

Nut_Api_Render_Model_Lead for output details

newProduct

(

$

product

)

Create a new product.

The name field is required. Products must have a price set for each market to be available for that market. The parameter "sku" and "unit" are dependent on "type" (product or service respectively). See Nut_Api_Render_Model_Product for details.

product parameter:

 product: {
     'name': 'Mac Mini',
     'type': 0,    // 0 = product, 1 = service
     'sku': 'MM0123',
     'prices': [  // only one price per market
         {'marketId': 1, 'amount': 299},
         {'marketId': 2, 'amount': 349}
     ]
 }

Service example:

 product: {
     'name': 'Consulting',
     'type': 1,    // 0 = product, 1 = service
     'unit': 'hour',
     'prices': [  // only one price per market
         {'marketId': 1, 'amount': 100},
         {'marketId': 2, 'amount': 130}
     ]
 }

Returns the new product; see Nut_Api_Render_Model_Product for output details.

Parameters:

array

$product

Returns:

array Product

See also:

Nut_Api_Render_Model_Product for output details

newTag

(

$

tag

)

Create a new tag.

Both the entityType and name fields are required. Possible values for the entityType field:

 'Accounts'
 'Leads'
 'Contacts'

tag parameter:

 tag: {
     'name': 'Some new tag',
     'entityType': 'Accounts'
 }

Returns the new tag; see Nut_Api_Render_Model_Tag for output details.

Parameters:

array

$tag

Returns:

array Tag

See also:

Nut_Api_Render_Model_Tag for output details

newTeam

(

$

team

)

Create a new team.

The name field is required.

team parameter:

 team: {
     'name': 'East Coast',
     'division': 'Sales'
 }

Returns the new team; see Nut_Api_Render_Model_Team for output details.

Parameters:

array

$team

Returns:

array Team

See also:

Nut_Api_Render_Model_Team for output details

newUser

(

$

user

)

Create a new user.

user parameter:

 user: {
     'firstName': 'Jim',
     'lastName': 'Halpert',
     'password': 'secret',
     'emails': [
         'jhalpert@dundermifflin.com',
         'jim@dundermifflin.com'
     ],
     'isEnabled': true,
     'isAdministrator': false,
     'teams': {
         'viewAll': [],
         'viewOwn': [teamId, teamId],
         'viewTeam': []
     },
     'sendInvite': true // optional
 }

Team parameter keys:

• viewAll - User can view all data, no restrictions
• viewOwn - User can only view their data
• viewTeam - User can view all data in the team

The optional "sendInvite" parameter will trigger a welcome email to the user's first email address. Defaults to false.

Parameters:

array

$user

Returns:

array User

See also:

Nut_Api_Render_Model_User for output details

searchAccounts	(	$	string,
		$	limit = 10
	)

Return a list of Account stubs matching a given search string.

Parameters:

string	$string	Query
int	$limit

Returns:

array

searchByEmail

(

$

emailAddressString

)

Works just like searchUniversal, but only searches by email address.

Will return up to 5 accounts or contacts with the specified email address. Results are organized by entity type.

Example output:

 "result": {
   "contacts": [
      {
         "stub": true, 
         "id": 6, 
         "entityType": "Contacts", 
         "name": "Andrew Lucas", 
         "jobTitle": "Engineer, Inergy Holdings"
      }, 
   ], 
   "accounts": [ ]
 }

Parameters:

string

$emailAddressString

Query

Returns:

array

searchCompetitors	(	$	string,
		$	limit = 10
	)

Return a list of Competitor stubs matching a given search string.

Parameters:

string	$string	Query
int	$limit

Returns:

array

searchContacts	(	$	string,
		$	limit = 10
	)

Return a list of Contact stubs matching a given search string.

Parameters:

string	$string	Query
int	$limit

Returns:

array

searchContactsAndUsers	(	$	string,
		$	limit = 10
	)

Return a list of Contact and User stubs matching a given search string.

The results are not organized by type; use the 'entityType' field of each stub returned if you need to sort by type.

Example output:

 "result": [
    {
       "stub": true, 
       "id": 1, 
       "entityType": "Users", 
       "name": "Andy Fowler"
    }, 
    {
       "stub": true, 
       "id": 242, 
       "entityType": "Contacts", 
       "name": "Jenette Leblanc", 
       "jobTitle": ""
    }
 ]

Parameters:

string	$string	Query
int	$limit

Returns:

array

searchLeads	(	$	string,
		$	limit = 40
	)

Return a list of Lead stubs matching a given search string.

Parameters:

string	$string	Query
int	$limit

Returns:

array

searchProducts	(	$	string,
		$	limit = 10
	)

Return a list of Product stubs matching a given search string.

Parameters:

string	$string	Query
int	$limit

Returns:

array

searchSources	(	$	string,
		$	limit = 10
	)

Return a list of Source stubs matching a given search string.

Parameters:

string	$string	Query
int	$limit

Returns:

array

searchUniversal

(

$

string

)

Return a list of Contact, Lead, and Account stubs matching a given search string.

Results are organized by entity type.

Example output:

 "result": {
   "contacts": [
      {
         "stub": true, 
         "id": 6, 
         "entityType": "Contacts", 
         "name": "Andrew Lucas", 
         "jobTitle": "Engineer, Inergy Holdings"
      }, 
      {
         "stub": true, 
         "id": 242, 
         "entityType": "Contacts", 
         "name": "Jenette Leblanc", 
         "jobTitle": "Head Engineer, Scholastic"
      }
   ], 
   "leads": [
      {
         "stub": true, 
         "id": 45, 
         "entityType": "Leads", 
         "name": "Lead–45", 
         "status": 0, 
         "completion": 0, 
         "value": {
            "currency": "USD", 
            "amount": 30728
         }, 
         "primaryAccountName": "Brown-Forman", 
         "dueTime": "2010-09-04T10:00:00+0000"
      }, 
      {
         "stub": true, 
         "id": 163, 
         "entityType": "Leads", 
         "name": "Lead–163", 
         "status": 10, 
         "completion": 100, 
         "value": {
            "currency": "USD", 
            "amount": 1383
         }, 
         "primaryAccountName": "Cracker Barrel Old Country Store", 
         "dueTime": "2010-02-19T09:00:00+0000", 
         "closedTime": "2010-02-19T09:00:00+0000"
      }
   ],
   "accounts": [
      {
         "stub": true, 
         "id": 229, 
         "entityType": "Accounts", 
         "name": "Sherwin-Williams", 
         "regions": [ "San Marcos, TX" ]
      }, 
      {
         "stub": true, 
         "id": 264, 
         "entityType": "Accounts", 
         "name": "Cephalon", 
         "regions": [ "Providence, NC" ]
      }
   ]
 }

Parameters:

string

$string

Query

Returns:

array

searchUsersAndTeams	(	$	string,
		$	limit = 10
	)

Return a list of User and Team stubs matching a given search string.

The results are not organized by type; use the 'entityType' field of each stub returned if you need to sort by type.

Example output:

 "result": [
    {
       "stub": true, 
       "id": 45, 
       "entityType": "Users", 
       "name": "Westley Smith"
    },
    {
       "stub": true, 
       "id": 3, 
       "entityType": "Teams", 
       "name": "West Coast Sales"
    }
 ]

Parameters:

string	$string	Query
int	$limit

Returns:

array

startBackup

(

)

Initiate downloadable backup.

Only one backup may be running at a time.

Returns:

Backup

See also:

Nut_Api_Render_Model_Backup for output details