API documentation

Core Class Reference

Description

Core API methods revealed via web services

Methods revealed via web services.

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. More...
 
 deleteAccount ($accountId, $rev)
 Delete an account. More...
 
 deleteActivity ($activityId, $rev)
 Delete an activity. More...
 
 deleteContact ($contactId, $rev)
 Delete a contact. More...
 
 deleteLead ($leadId, $rev)
 Delete a lead. More...
 
 deleteNote ($noteId, $rev)
 Deletes the given note. More...
 
 deleteProduct ($productId, $rev)
 Delete a product. More...
 
 deleteTask ($taskId, $rev)
 Delete a task. More...
 
 deleteTeam ($teamId, $rev)
 Delete a team. More...
 
 deleteUser ($userId, $rev)
 Delete a user. More...
 
 editAccount ($accountId, $rev, $account)
 Edit an account. More...
 
 editActivity ($activityId, $rev, $activity)
 Edit an activity. More...
 
 editContact ($contactId, $rev, $contact)
 Edit a contact. More...
 
 editLead ($leadId, $rev, $lead)
 Edit a lead. More...
 
 editNote ($noteId, $rev, $note)
 Edits the given note (note that notes can only be edited for 24 hours by the note author) More...
 
 editProduct ($productId, $rev, $product)
 Edit a product. More...
 
 editStep ($stepId, $rev, $step)
 Update a process step. More...
 
 editTask ($taskId, $rev, $task)
 Edit a task. More...
 
 editTeam ($teamId, $rev, $team)
 Edit a team. More...
 
 editUser ($userId, $rev, $user)
 Edit a user. More...
 
 findAccounts ($query=null, $orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1, $stubResponses=true)
 Find accounts matching a specified query. More...
 
 findAccountTypes ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
 Get all active account types (to be applied to an account) More...
 
 findActivities ($query, $orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1, $stubResponses=true)
 Find activities matching a specified query. More...
 
 findActivityTypes ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
 Get all active activity types. More...
 
 findBackups ()
 List available and running backups. More...
 
 findCompetitors ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
 Returns stubs for all active Competitors. More...
 
 findContacts ($query=null, $orderBy= 'id', $orderDirection= 'ASC', $limit=50, $page=1, $stubResponses=true)
 Find contacts associated with a specified account or lead. More...
 
 findCustomFields ()
 Gets all of the custom fields available for Leads, Accounts and Contacts, including appropriate meta-information. More...
 
 findDelays ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
 Returns stubs for all active Delays (seen in Step responses in availableDelayIds) More...
 
 findIndustries ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
 Returns stubs for all active Industries (to be applied to an account). More...
 
 findLead_Outcomes ($orderBy= 'description', $orderDirection= 'ASC', $limit=50, $page=1)
 Get all possible outcomes for a closed lead. More...
 
 findLeads ($query, $orderBy= 'id', $orderDirection= 'ASC', $limit=50, $page=1, $stubResponses=true)
 Find leads matching a specified query. More...
 
 findMarkets ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
 Returns stubs for all active Markets. More...
 
 findMilestones ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
 Get all active milestones. More...
 
 findOrigins ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
 Returns stubs for all active Origins. More...
 
 findProcesses ($query)
 Finds all processes associated with an entity. More...
 
 findProducts ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1, $stubResponses=true)
 Get all active products. More...
 
 findSettings ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
 Return all publicly-visible settings. More...
 
 findSources ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
 Returns stubs for all active Sources. More...
 
 findTags ()
 Get all active tags. More...
 
 findTasks ($query)
 Returns an array containing tasks for the given query. More...
 
 findTeams ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
 Returns stubs for all active Teams. More...
 
 findTerritories ($orderBy= 'name', $orderDirection= 'ASC', $limit=50, $page=1)
 Get all territories. More...
 
 findTimeline ($query, $orderBy= 'time', $orderDirection= 'ASC', $limit=50, $page=1, $stubResponses=true)
 Find timeline events (Activities, Emails and Notes) for an Entity. More...
 
 findUsers ($orderBy= 'last_name', $orderDirection= 'ASC', $limit=50, $page=1)
 Returns stubs for all active Users. More...
 
 getAccount ($accountId, $rev=null)
 Get the specified Account. More...
 
 getActivity ($activityId, $rev=null)
 Get the specified Activity. More...
 
 getAnalyticsReport ($reportType, $period, $filter=null, $options=null)
 Returns graph data and overview information for various sales analytics reports. More...
 
 getContact ($contactId, $rev=null)
 Get the specified Contact. More...
 
 getEmail ($emailId, $rev=null)
 Get the specified Email. More...
 
 getLead ($leadId, $rev=null)
 Get the specified Lead by ID. More...
 
 getNote ($noteId, $rev=null)
 Get the specified Note. More...
 
 getProduct ($productId, $rev=null)
 Get all information for a Product (including full price list). More...
 
 getTask ($taskId, $rev=null)
 Get the specified Task. More...
 
 getTeam ($teamId, $rev=null)
 Get the specified Team. More...
 
 getUpdateTimes ()
 Gets the last-updated times of each of the provisioning bins. More...
 
 getUser ($userId=null, $rev=null)
 Get all info about a User. More...
 
 newAccount ($account)
 Create a new Account. More...
 
 newActivity ($activity)
 Create a new Activity. More...
 
 newBackup ()
 Initiate downloadable backup. More...
 
 newContact ($contact)
 Create a new Contact. More...
 
 newEmail ($emailString)
 Saves the given e-mail message. More...
 
 newLead ($lead)
 Create a new Lead. More...
 
 newNote ($entity, $note)
 Adds the note to the given entity. More...
 
 newProduct ($product)
 Create a new Product. More...
 
 newSource ($name)
 Given a source name, fetches an existing source or creates a new one if it does not exist. More...
 
 newTag ($tag)
 Create a new Tag. More...
 
 newTask ($task)
 Create a new Task. More...
 
 newTeam ($team)
 Create a new Team. More...
 
 newUser ($user)
 Create a new User. More...
 
 searchAccounts ($string, $limit=10)
 Return a list of Account stubs matching a given search string. More...
 
 searchActivityParticipants ($string, $limit=10)
 Return a list of stubs matching a given search string for all entities that could be participants in an Activity. More...
 
 searchByEmail ($emailAddressString)
 Works just like searchUniversal(), but only searches by email address. More...
 
 searchCompetitors ($string, $limit=10)
 Return a list of Competitor stubs matching a given search string. More...
 
 searchContacts ($string, $limit=10)
 Return a list of Contact stubs matching a given search string. More...
 
 searchContactsAndUsers ($string, $limit=10)
 Return a list of Contact and User stubs matching a given search string. More...
 
 searchLeads ($string, $limit=40)
 Return a list of Lead stubs matching a given search string. More...
 
 searchMentionableEntities ($string, $entityType, $entityId, $knownLocalEntities, $limit=10)
 Returns an array of mentionable entities matching the $string, but excluding any that the client already knows about, as indicated by $knownLocalResults. More...
 
 searchProducts ($string, $limit=10)
 Return a list of Product stubs matching a given search string. More...
 
 searchSources ($string, $limit=10)
 Return a list of Source stubs matching a given search string. More...
 
 searchUniversal ($string)
 Return a list of Contact, Lead, and Account stubs matching a given search string. More...
 
 searchUsersAndTeams ($string, $limit=10)
 Return a list of User and Team stubs matching a given search string. More...
 

Member Function Documentation

add (   $num1,
  $num2 
)

For testing.

Try it out!

Parameters
int$num1
int$num2
Returns
int
deleteAccount (   $accountId,
  $rev 
)

Delete an account.

Try it out!

Parameters
int$accountIdaccount ID to delete
string$rev
Returns
boolean
deleteActivity (   $activityId,
  $rev 
)

Delete an activity.

Try it out!

Parameters
int$activityIdactivity ID to delete
string$rev
Returns
boolean
deleteContact (   $contactId,
  $rev 
)

Delete a contact.

Try it out!

Parameters
int$contactIdcontact ID to delete
string$rev
Returns
boolean
deleteLead (   $leadId,
  $rev 
)

Delete a lead.

Try it out!

Parameters
int$leadIdlead ID to delete
string$rev
Returns
boolean
deleteNote (   $noteId,
  $rev 
)

Deletes the given note.

Try it out!

Parameters
int$noteIdThe note ID to delete.
string$revThe note's revision.
Returns
boolean
deleteProduct (   $productId,
  $rev 
)

Delete a product.

Try it out!

Parameters
int$productIdproduct ID to delete
string$rev
Returns
boolean
deleteTask (   $taskId,
  $rev 
)

Delete a task.

Try it out!

Parameters
int$taskIdtask ID to delete
string$rev
Returns
boolean
deleteTeam (   $teamId,
  $rev 
)

Delete a team.

Try it out!

Parameters
int$teamIdteam ID to delete
string$rev
Returns
boolean
deleteUser (   $userId,
  $rev 
)

Delete a user.

Try it out!

Parameters
int$userIduser ID to delete
string$rev
Returns
boolean
editAccount (   $accountId,
  $rev,
  $account 
)

Edit an account.

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",
"accountTypeId": "1",
"phone": {
"cell": "717-555-0467",
"office": "877-000-9237"
},
"owner": {
"entityType": "Users",
"id": 1
},
"note": "Needs to be contacted!",
"tags": ["some tag name", "some other tag"],
// Include keys and values to be updated
}

Try it out!

See Also
newAccount() for input specification
Parameters
int$accountIdaccount ID to edit
string$rev
array$accountUpdated account information
Returns
Account The updated account
editActivity (   $activityId,
  $rev,
  $activity 
)

Edit an activity.

These fields can be edited with this method:

  • name (string)
  • description (string)
  • leads (array of objects, see example below)
  • status (int)
  • location (see example below)
  • startTime (Zend_Date::ATOM)
  • endTime (Zend_Date::ATOM)
  • activityTypeId
  • isAllDay (boolean)
  • isTimed (boolean, corresponds to "Any time" checkbox on web)
  • isFlagged (boolean, corresponds to "Important" flag on web)
  • participants (array of objects, see example below)
  • logNote (object containing key 'note')
  • followupTo (id of an activity to which this is a follow-up)

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. The log note can contain any number of mentions, as described at Note::_render.

Possible values for the status field:

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

Try it out!

See Also
newActivity() for input specification
Parameters
int$activityIdactivity ID to edit
string$rev
array$activityupdated activity information
Returns
Activity The updated activity
editContact (   $contactId,
  $rev,
  $contact 
)

Edit a contact.

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": {
"work": "717-555-0480",
"home": "+216 717-555-6633",
"cell": "877-555-5001"
},
"owner": {
"entityType": "Users",
"id": 1
},
"note": "cool guy",
"description": "Works late call anytime",
"tags": ["some tag name", "some other tag"],
}

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.

Try it out!

See Also
newContact() for input specifications
Parameters
int$contactIdthe contact ID to update
string$rev
array$contactthe updated contact information
Returns
Contact The updated contact
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,
} , ...
],
"accounts": [
{
"id": 6,
"rev": 7,
} , ...
},
"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

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

Try it out!

See Also
newLead() for input formatting specification
findLead_Outcomes() to find possible outcomes
Parameters
int$leadIdlead ID to update
string$rev
array$leadnew lead information
Returns
Lead The updated lead
editNote (   $noteId,
  $rev,
  $note 
)

Edits the given note (note that notes can only be edited for 24 hours by the note author)

Try it out!

Parameters
int$noteIdThe note ID to delete.
string$revThe note's revision.
mixed$noteA simple string, or (for future compatibility), the note array containing the entityType "Notes" and "note" key containing the note's text. The string may contain any number of mentions. See Note::_render for more information.
Returns
array The note's entity
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).

Try it out!

Parameters
int$productIdproduct ID to update
string$rev
array$productnew product information
Returns
Product The updated product
See Also
newProduct() for input formatting specification
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"
}
}

Try it out!

Parameters
int$stepIdstep ID to update
string$rev
array$stepupdates step information
Returns
Step The updated step
editTask (   $taskId,
  $rev,
  $task 
)

Edit a task.

The title field is required.

Try it out!

Parameters
int$taskIdtask ID to update
string$rev
array$tasknew task information
Returns
Task The updated task
See Also
newTask() for input formatting specification
editTeam (   $teamId,
  $rev,
  $team 
)

Edit a team.

Try it out!

Parameters
int$teamIdteam ID to update
string$rev
array$teamnew team information
Returns
Team The updated team
See Also
newTeam() for input formatting specification
editUser (   $userId,
  $rev,
  $user 
)

Edit a user.

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
}

Try it out!

See Also
newUser() for input specifications
Parameters
int$userIdthe user ID to update
string$rev
array$userthe updated user information
Returns
User The updated user
findAccounts (   $query = null,
  $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1,
  $stubResponses = true 
)

Find accounts matching a specified query.

Currently implemented query keys:

Example query:

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

Try it out!

Parameters
array$queryquery keys and values
string$orderBy
string$orderDirection
int$limit(max 100)
int$page
bool$stubResponseswhether to return stub responses instead of full responses (default true)
Returns
array of Account objects
findAccountTypes (   $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

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

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of Account_Type objects
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
  • accountId -> An optional array of account 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
  • isFlagged -> An optional boolean for filtering by the "Important" flag
  • startTime -> An optional date or time to compare against the start time, prefixed by a comparison operator (either "<", ">", "=", ">=", or "<=").
  • endTime -> An optional date or time to compare against the end tiem, prefixed by a comparison operator (either "<", ">", "=", ">=", or "<=").

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 queries:

// Find all scheduled activities associated with lead 42
"query": {
"leadId": 42,
"status": 0
}
// Find all scheduled activities that scheduled after 2007-01-01 00:00:00UTC and before or on 2008-10-10 10:20:30 UTC
"query": {
"startTime": "> 2007-01-01",
"endTime": "<= 2008-10-10 10:20:30",
}

Try it out!

Parameters
array$queryquery keys and values
string$orderBy
string$orderDirection
int$limit(max 100)
int$page
bool$stubResponseswhether to return stub responses instead of full responses (default true)
Returns
array of Activity objects
findActivityTypes (   $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

Get all active activity types.

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of Activity_Type objects
findBackups ( )

List available and running backups.

Try it out!

Returns
array of Backup objects
findCompetitors (   $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

Returns stubs for all active Competitors.

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of Competitor objects
findContacts (   $query = null,
  $orderBy = 'id',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1,
  $stubResponses = true 
)

Find contacts associated with a specified account or lead.

Query parameters:

Order by choices:

  • id
  • creatorUserId
  • creatorOriginId
  • legacyId
  • rev
  • createdTime
  • modifiedTime
  • givenName (i.e. first name)
  • familyName (i.e. last name)
  • displayName (i.e. full name)

Example query:

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

Try it out!

Parameters
array$queryquery keys and values
string$orderBy
string$orderDirection
int$limit(max 100)
int$page
bool$stubResponseswhether to return stub responses instead of full responses (default true)
Returns
array of Contact objects
findCustomFields ( )

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

Try it out!

Returns
array
{
"Leads": [ EntityAttribute, ... ],
"Contacts": [ EntityAttribute, ... ],
"Accounts": [ EntityAttribute, ... ]
}
findDelays (   $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

Returns stubs for all active Delays (seen in Step responses in availableDelayIds)

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of Delay objects
findIndustries (   $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

Returns stubs for all active Industries (to be applied to an account).

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of Industry objects
findLead_Outcomes (   $orderBy = 'description',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

Get all possible outcomes for a closed lead.

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of Lead_Outcome objects
findLeads (   $query,
  $orderBy = 'id',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1,
  $stubResponses = true 
)

Find leads matching a specified query.

Example query:

{
"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, ... ], // Team, User: { "entityType": "Teams", "id": 12 }
"origin": [ originId, originId ],
"source": [ sourceId, sourceId ],
"number": 1000, // The lead number visible to end users on the website, in the form "Lead-1000"
"tag": [ "tag #1", "tag #2" ]
}

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 '<', '>', '=', '<=', '>='

Try it out!

Parameters
array$queryquery keys and values.
string$orderBy
string$orderDirection
int$limit(max 100 for non-stub responses)
int$page
bool$stubResponseswhether to return stub responses instead of full responses (default true)
Returns
array of Lead objects
findMarkets (   $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

Returns stubs for all active Markets.

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of Market objects
findMilestones (   $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

Get all active milestones.

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of Milestone objects
findOrigins (   $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

Returns stubs for all active Origins.

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of Origin objects
findProcesses (   $query)

Finds all processes associated with an entity.

Example:

"query": {
"entity": {
"entityType": "Leads",
"id": 1000
}
}

Try it out!

Parameters
array$queryThe query for the find operation. Requires an 'entity' field with 'entityType' and 'id' properties, and no other options are currently supported.
Returns
array The processes that match the query.
findProducts (   $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1,
  $stubResponses = true 
)

Get all active products.

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
bool$stubResponseswhether to return Product stubs instead of full Product objects. Defaults to true.
Returns
array of Product objects
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.

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array Example:
"result": {
"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",
"work_week_start": "7"
}
findSources (   $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

Returns stubs for all active Sources.

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of Source objects
findTags ( )

Get all active tags.

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

Try it out!

Returns
array Example:
"result": {
"Leads": ["tag1", "tag2"],
"Contacts": [],
"Accounts": ["tag1"]
}
findTasks (   $query)

Returns an array containing tasks for the given query.

"query": {
"entity": Lead, // Related entity: { "entityType": "Leads", "id": 1002 }
"assignee": Team|User, // Team, User: { "entityType": "Teams", "id": 12 }
"creator": User // User: { "entityType": "Users", "id": 15 }
}

At least one parameter required. These parameters are ANDed in the query.

Try it out!

Parameters
array$queryquery keys and values.
Returns
array of tasks
findTeams (   $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

Returns stubs for all active Teams.

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of Team objects
findTerritories (   $orderBy = 'name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

Get all territories.

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of Territory objects
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
}

Try it out!

Parameters
array$queryquery keys and values
string$orderBy
string$orderDirection
int$limit
int$page
bool$stubResponseswhether to return stub responses instead of full responses (default true)
See Also
Lead, Activity, Email, and Note for output details
Returns
array of the above entities. Example:
"result": [ Activity, Email, Note, ... ]
findUsers (   $orderBy = 'last_name',
  $orderDirection = 'ASC',
  $limit = 50,
  $page = 1 
)

Returns stubs for all active Users.

Try it out!

Parameters
string$orderBy
string$orderDirection
int$limit
int$page
Returns
array of User objects
getAccount (   $accountId,
  $rev = null 
)

Get the specified Account.

Try it out!

Parameters
int$accountIdaccount ID to get
string$rev
Returns
Account
getActivity (   $activityId,
  $rev = null 
)

Get the specified Activity.

Try it out!

Parameters
int$activityIdactivity 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. User impersonation must be enabled for reports to be generated.

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; otherwise, defaults to UTC
"useEmails": (bool), // only valid for Effort reports.
"includeCanceled": (bool) // only valid for Success reports.
}

Try it out!

Parameters
string$reportType
string$period
array$filter(optional)
array$options(optional)
Returns
array Example:
{
"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"
}
getContact (   $contactId,
  $rev = null 
)

Get the specified Contact.

Try it out!

Parameters
int$contactIdcontact ID to get
string$rev
Returns
Contact
getEmail (   $emailId,
  $rev = null 
)

Get the specified Email.

Try it out!

Parameters
int$emailIdemail ID to get
string$rev
Returns
Email
getLead (   $leadId,
  $rev = null 
)

Get the specified Lead by ID.

Note that a lead's ID is not always the same as the number shown when viewing the lead on the Nutshell website. Use the findLeads() method with the "number" query parameter to retrieve the lead corresponding to a number on the website.

Try it out!

Parameters
int$leadIdlead ID to get
string$rev
Returns
Lead
getNote (   $noteId,
  $rev = null 
)

Get the specified Note.

Try it out!

Parameters
int$noteIdnote ID to get
string$rev
Returns
Note
getProduct (   $productId,
  $rev = null 
)

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

Try it out!

Parameters
int$productIdID of product to get
string$rev
Returns
Product
getTask (   $taskId,
  $rev = null 
)

Get the specified Task.

Try it out!

Parameters
int$taskIdtask ID to get
string$rev
Returns
Task
getTeam (   $teamId,
  $rev = null 
)

Get the specified Team.

Try it out!

Parameters
int$teamIdID 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.

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.

Try it out!

Returns
array of UpdateTimes. Example snippet:
{
"Industries": "2009-02-13T14:53:27+01:00",
"Products": "2009-02-13T14:53:27+01:00",
...
}
getUser (   $userId = null,
  $rev = null 
)

Get all info about a User.

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

Try it out!

Parameters
int$userIdID of user to get
string$rev
Returns
User
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",
"owner": {
"entityType": "Users",
"id": 1
},
"industryId": "3",
"accountTypeId": "1",
"territoryId": "10",
"url": [ "http://www.andyfowler.com/", "facebook.com/andy" ],
"phone": [ "717-555-0480", "717-555-0055", "877-555-9988" ],
"leads": [
{
"relationship": "First account",
"id": 12
}, ...
],
"contacts": [
{
"relationship": "First contact",
"id": 12,
}, ...
],
"owner": {
"entityType": "Users",
"id": 1
},
"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",
}
}

The "owner" field of account is optional and may be used to specify the ownership of the new entity. Both the entityType and id fields are required; either Users or Teams can be given ownership. If absent, the default owner is the creator.

"owner": {
"entityType": "Users",
"id": 1
}

Try it out!

Parameters
array$accountnew account
Returns
Account The new account
newActivity (   $activity)

Create a new Activity.

The following fields are optional:

  • leads (array of objects, see example below)
  • isAllDay (boolean)
  • isTimed (boolean, corresponds to "Any time" checkbox on web)
  • isFlagged (boolean, corresponds to "Important" flag on web)
  • location (see example below)
  • participants (see example below)
  • status (int)
  • logNote (array containing key 'note')
  • followupTo (id of an activity to which this is a follow-up)

Possible values for the status field:

0 = not logged
1 = logged

Example activity:

"activity": {
"name": "string value",
"description": "string value",
"activityTypeId": 1, // int value
"leads": [
{
"entityType": "Leads",
"id": 1000
}
],
"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,
"isTimed": true,
"isFlagged": false,
"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"
}
]
}

Try it out!

Parameters
array$activitynew activity
Returns
Activity The new activity
newBackup ( )

Initiate downloadable backup.

Only one backup may be running at a time.

Returns
Backup
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",
"owner": {
"entityType": "Users",
"id": 1
},
"description": "Beagle owner",
"phone": [ "717-555-0480", "+216 707-555-2903", "877-555-5555" ],
"email": ["andy@gmail.com", "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"
}

The "owner" field of contact is optional and may be used to specify the ownership of the new entity. Both the entityType and id fields are required; either Users or Teams can be given ownership. If absent, the default owner is the creator.

"owner": {
"entityType": "Users",
"id": 1
}

Try it out!

Parameters
array$contact
Returns
Contact The new contact
newEmail (   $emailString)

Saves the given e-mail message.

Try it out!

Parameters
string$emailStringE-mail in RFC 822 format
Returns
Email The new email
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"},
"tags": ["some tag name", "some other tag"],
"accounts": [
{
"id": 111
} , ...
],
"contacts": [
{
"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"
},
},
"note": [
"New lead note #1",
"New lead note #2"
]
}

Try it out!

Parameters
array$leadnew lead information
Returns
Lead The new lead
newNote (   $entity,
  $note 
)

Adds the note to the given entity.

Try it out!

Parameters
array$entityThe entity array containing the entityType and id of the entity that is receiving the note. It will also accept the entity itself. Example:
"entity": {
"entityType": "Leads",
"id": 42
}
mixed$noteA simple string, or (for future compatibility), the note array containing the entityType "Notes" and "note" key containing the note's text. The string may contain any number of mentions. See Note::_render for more information.
Returns
Note The new note
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).

Try it out!

Parameters
array$productProduct example:
"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
Product The new product
newSource (   $name)

Given a source name, fetches an existing source or creates a new one if it does not exist.

Try it out!

Parameters
string$nameThe name of the source to be added.
Returns
Source The new source
newTag (   $tag)

Create a new Tag.

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

"Accounts"
"Leads"
"Contacts"

Try it out!

Parameters
array$tagExample:
"tag": {
"name": "Some new tag",
"entityType": "Accounts"
}
Returns
Tag The new tag
newTask (   $task)

Create a new Task.

The title field is required.

Try it out!

Parameters
array$taskTask example:
"task": {
"title": "Send product sheet",
"description": "Notes for this task",
"dueTime": "2013-01-11T15:23:19-05:00",
"assignee": {
"entityType": "Users",
"id": 12
}
Returns
Task The new task
newTeam (   $team)

Create a new Team.

The name field is required.

Try it out!

Parameters
array$teamExample:
"team": {
"name": "East Coast",
"division": "Sales"
}
Returns
Team The new team
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.

Try it out!

Parameters
array$user
Returns
User The new user
searchAccounts (   $string,
  $limit = 10 
)

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

Try it out!

Parameters
string$stringQuery
int$limit
Returns
array of Account objects
searchActivityParticipants (   $string,
  $limit = 10 
)

Return a list of stubs matching a given search string for all entities that could be participants in an Activity.

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

Try it out!

Parameters
string$stringQuery
int$limit(optional) max number of results; defaults to 10
Returns
array
"result": [ User, Contact, Account... ]
searchByEmail (   $emailAddressString)

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

Will return up to 5 account or contact stubs with the specified email address. Results are organized by entity type.

Try it out!

Parameters
string$emailAddressStringQuery
Returns
array
"result": {
"contacts": [ Contact, ... ],
"accounts": [ Account, ... ]
}
searchCompetitors (   $string,
  $limit = 10 
)

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

Try it out!

Parameters
string$stringQuery
int$limit
Returns
array of Competitor objects
searchContacts (   $string,
  $limit = 10 
)

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

Try it out!

Parameters
string$stringQuery
int$limit
Returns
array of Contact objects
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.

Try it out!

Parameters
string$stringQuery
int$limit
Returns
array
"result": [ User, Contact, ... ]
searchLeads (   $string,
  $limit = 40 
)

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

Try it out!

Parameters
string$stringQuery
int$limit
Returns
array of Lead objects
searchMentionableEntities (   $string,
  $entityType,
  $entityId,
  $knownLocalEntities,
  $limit = 10 
)

Returns an array of mentionable entities matching the $string, but excluding any that the client already knows about, as indicated by $knownLocalResults.

Parameters
string$stringThe query string to search for
string$entityTypeThe type of the contextual entity
int$entityIdThe id of the contextual entity
array$knownLocalEntitiesAn array of objects containing at least the entityType-id pair that represents any locally cached results that should not be returned.
Returns
array of entities with all entries of $knownLocalEntities filtered out
searchProducts (   $string,
  $limit = 10 
)

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

Try it out!

Parameters
string$stringQuery
int$limit
Returns
array of Product objects
searchSources (   $string,
  $limit = 10 
)

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

Try it out!

Parameters
string$stringQuery
int$limit
Returns
array of Source objects
searchUniversal (   $string)

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

Results are organized by entity type.

Try it out!

Parameters
string$stringQuery
Returns
array
"result": {
"contacts": [ Contact, ... ],
"leads": [ Lead, ... ],
"accounts": [ Account, ... ]
}
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.

Try it out!

Parameters
string$stringQuery
int$limit
Returns
array
"result": [ User, Team, ... ]