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 ATOM/rfc3339 format. Info on ATOM/rfc3339 here: http://en.wikipedia.org/wiki/Atom_(standard)#Date_formats http://tools.ietf.org/html/rfc3339

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

	findAudiences ( $orderBy='name', $orderDirection='ASC', $limit=50, $page=1)
	Returns stubs for all active Audiences. 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...

	findNotes ( $query=null, $orderBy='createdTime', $orderDirection='DESC', $limit=50, $page=1, $stubResponses=false)
	Get all active notes. 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...

	findStagesets ( $orderBy='name', $orderDirection='ASC', $limit=50, $page=1)
	Get all active stagesets (this is the Nutshell API term for Pipelines) More...

	findTags ()
	Get all active tags. More...

	findTasks ( $query, $orderBy='due_time', $orderDirection='ASC', $limit=50, $page=1, $stubResponses=false)
	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 ( $query=null, $orderBy='last_name', $orderDirection='ASC', $limit=50, $page=1)
	Find users matching a specified query. 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...

	instanceData ()
	Return data related to authenticated Nutshell instance. 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, $createContacts=true)
	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()

add	(	$num1,
		$num2
	)

For testing.

Try it out!

Parameters

int	$num1
int	$num2

Returns: int

◆ deleteAccount()

deleteAccount	(	$accountId,
		$rev
	)

Delete an account.

Try it out!

Parameters

int	$accountId	account ID to delete
string	$rev

Returns: boolean

◆ deleteActivity()

deleteActivity	(	$activityId,
		$rev
	)

Delete an activity.

Try it out!

Parameters

int	$activityId	activity ID to delete
string	$rev

Returns: boolean

◆ deleteContact()

deleteContact	(	$contactId,
		$rev
	)

Delete a contact.

Try it out!

Parameters

int	$contactId	contact ID to delete
string	$rev

Returns: boolean

◆ deleteLead()

deleteLead	(	$leadId,
		$rev
	)

Delete a lead.

Try it out!

Parameters

int	$leadId	lead ID to delete
string	$rev

Returns: boolean

◆ deleteNote()

deleteNote	(	$noteId,
		$rev
	)

Deletes the given note.

Try it out!

Parameters

int	$noteId	The note ID to delete.
string	$rev	The note's revision.

Returns: boolean

◆ deleteProduct()

deleteProduct	(	$productId,
		$rev
	)

Delete a product.

Try it out!

Parameters

int	$productId	product ID to delete
string	$rev

Returns: boolean

◆ deleteTask()

deleteTask	(	$taskId,
		$rev
	)

Delete a task.

Try it out!

Parameters

int	$taskId	task ID to delete
string	$rev

Returns: boolean

◆ deleteTeam()

deleteTeam	(	$teamId,
		$rev
	)

Delete a team.

Try it out!

Parameters

int	$teamId	team ID to delete
string	$rev

Returns: boolean

◆ deleteUser()

deleteUser	(	$userId,
		$rev
	)

Delete a user.

Try it out!

Parameters

int	$userId	user ID to delete
string	$rev

Returns: boolean

◆ editAccount()

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
}

You can upload files to the account by adding sparse objects to the "file" property. See https://developers.nutshell.com/#files for more information on uploading and downloading files

Try it out!

See also: newAccount() for input specification

Parameters

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

Returns: Account The updated account

◆ editActivity()

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 (ATOM/rfc3339)
endTime (ATOM/rfc3339)
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	$activityId	activity ID to edit
string	$rev
array	$activity	updated activity information

Returns: Activity The updated activity

◆ editContact()

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.

You can upload files to the contact by adding sparse objects to the "file" property. See https://developers.nutshell.com/#files for more information on uploading and downloading files

Try it out!

See also: newContact() for input specifications

Parameters

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

Returns: Contact The updated contact

◆ editLead()

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:

= STATUS_POTENTIAL
= STATUS_STOLE  // they stole from us
= 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"
    }
    "priority": "0"
 
}

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. ATOM/rfc3339 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:

= Won
= Lost
= Cancelled

To reopen a lead, set the status to 0

To change the stage a lead is in, pass in the ID of the milestone to move the lead to. (NOTE: milestone is the Nutshell API term for a stage) All milestones can be retrieved with the findMilestones() method.

"lead": {
   "milestoneId": 1
}

To change the pipeline a lead is in, pass in the ID of the stageset to move the lead to. (NOTE: stageset is the Nutshell API term for a pipeline) All pipelines can be retrieved with the findStagesets() method.

"lead": {
   "stagesetId": 1
}

To specify the lead as hot, set the priority to 1

You can upload files to the lead by adding sparse objects to the "file" property. See https://developers.nutshell.com/#files 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	$leadId	lead ID to update
string	$rev
array	$lead	new lead information

Returns: Lead The updated lead

◆ editNote()

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	$noteId	The note ID to delete.
string	$rev	The note's revision.
mixed	$note	A 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()

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	$productId	product ID to update
string	$rev
array	$product	new product information

Returns: Product The updated product

See also: newProduct() for input formatting specification

◆ editStep()

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:

= STATUS_NEW
= STATUS_DELAYED  // DEPRECATED
= STATUS_COMPLETED
= 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	$stepId	step ID to update
string	$rev
array	$step	updates step information

Returns: Step The updated step

◆ editTask()

editTask	(	$taskId,
		$rev,
		$task
	)

Edit a task.

The title field is required.

Try it out!

Parameters

int	$taskId	task ID to update
string	$rev
array	$task	new task information

Returns: Task The updated task

See also: newTask() for input formatting specification

◆ editTeam()

editTeam	(	$teamId,
		$rev,
		$team
	)

Edit a team.

Try it out!

Parameters

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

Returns: Team The updated team

See also: newTeam() for input formatting specification

◆ editUser()

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	$userId	the user ID to update
string	$rev
array	$user	the updated user information

Returns: User The updated user

◆ findAccounts()

findAccounts	(	$query = `null`,
		$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()
territory -> An array of territory ids. See findTerritories()
origin -> An array of origin ids. See findOrigins()
hasOpenLeads -> boolean. If true, only return accounts associated with open leads.
tag -> An array of tag names. See findTags()

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	$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 of Account objects

◆ findAccountTypes()

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()

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:

= STATUS_SCHEDULED
= STATUS_LOGGED
= 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	$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 of Activity objects

◆ findActivityTypes()

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

◆ findAudiences()

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

Returns stubs for all active Audiences.

Try it out!

Parameters

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

Returns: array of Audience objects

◆ findBackups()

findBackups ( )

List available and running backups.

Try it out!

Returns: array of Backup objects

◆ findCompetitors()

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()

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
territory -> An array of territory ids. See findTerritories()
tag -> An array of tag names. See findTags()

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	$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 of Contact objects

◆ findCustomFields()

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()

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()

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()

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()

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,
  "milestoneId": 1,
  "outcomeId": 1, // find leads associated with a custom outcomeId
  "milestoneIds": [1, 2], // find leads in any of the provided milestone IDs
  "stagesetId": 2, // (stagesets are referred to as "pipelines" in Nutshell)
  "stagesetIds": [ 2, 3 ], // find leads in *any* of the provided stageset IDs
  "dueTime": "> 2010-09-15",  // or "< 2009-02-02"
  "assignee": [ Team, User, ... ],  // Team, User: { "entityType": "Teams", "id": 12 }
  "origin": [ originId, originId ],
  "channel": [ channelName, channelName ], // unknown, organic-search, paid-search, organic-search, paid-social, email, direct-traffic, referral-traffic, traditional
  "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" ],
  "priority": 1 // i.e. only `hot` leads
}

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' and 'modifiedTime' comparison are '<', '>', '=', '<=', '>='

Try it out!

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 of Lead objects

◆ findMarkets()

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()

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

◆ findNotes()

findNotes	(	$query = `null`,
		$orderBy = `'createdTime'`,
		$orderDirection = `'DESC'`,
		$limit = `50`,
		$page = `1`,
		$stubResponses = `false`
	)

Get all active notes.

Currently implemented query keys:

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 time, prefixed by a comparison operator (either "<", ">", "=", ">=", or "<=").

Example queries:

// Find all notes created 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	$query	query keys and values
string	$orderBy	default to createdTime
string	$orderDirection	default to descending
int	$limit
int	$page
bool	$stubResponses	whether to return Note stubs instead of full Note objects. Defaults to false.

Returns: array|Zend_Db_Table_Select Note objects

◆ findOrigins()

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()

findProcesses ( $query )

Finds all processes associated with an entity.

Example:

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

Try it out!

Parameters

array $query The 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()

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	$stubResponses	whether to return Product stubs instead of full Product objects. Defaults to true.

Returns: array of Product objects

◆ findSettings()

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()

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

◆ findStagesets()

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

Get all active stagesets (this is the Nutshell API term for Pipelines)

Try it out!

Parameters

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

Returns: array of Stageset objects

◆ findTags()

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()

findTasks	(	$query,
		$orderBy = `'due_time'`,
		$orderDirection = `'ASC'`,
		$limit = `50`,
		$page = `1`,
		$stubResponses = `false`
	)

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 }
  "onlyIncomplete": false|true // false, true
}

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

Try it out!

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 false)

Returns: array|Zend_Db_Table_Select Tasks

◆ findTeams()

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()

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()

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	$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)

See also: Lead, Activity, Email, and Note for output details

Returns: array of the above entities. Example:
"result": [ Activity, Email, Note, ... ]

◆ findUsers()

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

Find users matching a specified query.

All active users returned if query is null.

Currently implemented query keys:

email -> Email address to query

Try it out!

Parameters

array	$query	query keys and values
string	$orderBy
string	$orderDirection
int	$limit
int	$page

Returns: array of User objects

◆ getAccount()

getAccount	(	$accountId,
		$rev = `null`
	)

Get the specified Account.

Try it out!

Parameters

int	$accountId	account ID to get
string	$rev

Returns: Account

◆ getActivity()

getActivity	(	$activityId,
		$rev = `null`
	)

Get the specified Activity.

Try it out!

Parameters

int	$activityId	activity ID to get
string	$rev

Returns: Activity

◆ getAnalyticsReport()

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 (Value of won leads)
WinRate (Statistics about won leads vs. closed 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
Activity_Types (only relevent to Effort reports)

"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()

getContact	(	$contactId,
		$rev = `null`
	)

Get the specified Contact.

Try it out!

Parameters

int	$contactId	contact ID to get
string	$rev

Returns: Contact

◆ getEmail()

getEmail	(	$emailId,
		$rev = `null`
	)

Get the specified Email.

Try it out!

Parameters

int	$emailId	email ID to get
string	$rev

Returns: Email

◆ getLead()

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	$leadId	lead ID to get
string	$rev

Returns: Lead

◆ getNote()

getNote	(	$noteId,
		$rev = `null`
	)

Get the specified Note.

Try it out!

Parameters

int	$noteId	note ID to get
string	$rev

Returns: Note

◆ getProduct()

getProduct	(	$productId,
		$rev = `null`
	)

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

Try it out!

Parameters

int	$productId	ID of product to get
string	$rev

Returns: Product

◆ getTask()

getTask	(	$taskId,
		$rev = `null`
	)

Get the specified Task.

Try it out!

Parameters

int	$taskId	task ID to get
string	$rev

Returns: Task

◆ getTeam()

getTeam	(	$teamId,
		$rev = `null`
	)

Get the specified Team.

Try it out!

Parameters

int	$teamId	ID of team to get
string	$rev

Returns: Team

◆ getUpdateTimes()

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 ATOM/rfc3339 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()

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	$userId	ID of user to get
string	$rev

Returns: User

◆ instanceData()

instanceData ( )

Return data related to authenticated Nutshell instance.

Utilized by integration partners.

Returns: {

"id": "78557"

}

◆ newAccount()

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 $account new account

Returns: Account The new account

◆ newActivity()

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", // ATOM/rfc3339 format
    "endTime": "2009-02-13T14:53:27+01:00",   // ATOM/rfc3339 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"
        },
        {
           "entityType": "Email",
           "email": "example@gmail.com"
        },
        {
           "entityType": "Email",
           "email": "newemaill@gmail.com",
           "name": "Carly (New Contact via Email) Hughes"
        },
        {
           "entityType": "Phone",
           "phone": "7342229999",
           "name": "Jim (New Contact via Phone) Halpert"
        },
    ]
}

Try it out!

Parameters

array $activity new activity

Returns: Activity The new activity

◆ newBackup()

newBackup ( )

Initiate downloadable backup.

Only one backup may be running at a time.

Returns: Backup

◆ newContact()

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"
    "audiences": [
        {
            "id": 111,
        }, ...
    ],
}

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()

newEmail	(	$emailString,
		$createContacts = `true`
	)

Saves the given e-mail message.

Automatically creates contacts or pending users, unless createContacts is false.

Try it out!

Parameters

string	$emailString	E-mail in RFC 822 format
bool	$createContacts	If false, don't create contacts or pending users.

Returns: Email The new email

◆ newLead()

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.

Leads with a priority of 1 will be considered hot leads; default is 0, i.e. not hot

Possible values for the competitor->status field:

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

Sample new lead:

"lead": {
    "primaryAccount": {"id": "1234"},
    "createdTime": "2022-09-13T15:23:19-05:00", // you can set the "open" time of the lead with this field
    "dueTime": "2023-11-13T15:23:19-05:00",
    "market": {"id": "1"},
    "tags": ["some tag name", "some other tag"],
    "description": "A great new lead",
    "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"
    ],
    "priority": 0 // this will NOT be a `hot` lead
}

To specify the stage a lead will be in, pass in the ID of a milestone. (NOTE: milestone is the Nutshell API term for a stage) All milestones can be retrieved with the findMilestones() method.

"milestoneId": 1

To specify the pipeline a lead will be in, pass in the ID a the stageset. (NOTE: stageset is the Nutshell API term for a pipeline) All pipelines can be retrieved with the findStagesets() method.

"stagesetId": 1

Try it out!

Parameters

array $lead new lead information

Returns: Lead The new lead

◆ newNote()

newNote	(	$entity,
		$note
	)

Adds the note to the given entity.

Try it out!

Parameters

array	$entity	The 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	$note	A 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()

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

$product

Product 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()

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 $name The name of the source to be added.

Returns: Source The new source

◆ newTag()

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

$tag

Example:

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

Returns: Tag The new tag

◆ newTask()

newTask ( $task )

Create a new Task.

The title field is required. Use the entity attribute to attach the task to a specific company or person.

Try it out!

Parameters

array

$task

Task example:

"task": {
    "title": "Send product sheet",
    "description": "Notes for this task",
    "dueTime": "2013-01-11T15:23:19-05:00",
    "assignee": {
        "entityType": "Users",
        "id": 12
    },
   "entity": {
       "entityType": "Accounts",
       "id": 1
   }
}

Returns: Task The new task

◆ newTeam()

newTeam ( $team )

Create a new Team.

The name field is required.

Try it out!

Parameters

array

$team

Example:

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

Returns: Team The new team

◆ newUser()

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()

searchAccounts	(	$string,
		$limit = `10`
	)

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

Try it out!

Parameters

string	$string	Query
int	$limit

Returns: array of Account objects

◆ searchActivityParticipants()

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	$string	Query
int	$limit	(optional) max number of results; defaults to 10

Returns: array
"result": [ User, Contact, Account... ]

◆ searchByEmail()

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 $emailAddressString Query

Returns: array
"result": {

"contacts": [ Contact, ... ],

"accounts": [ Account, ... ]

}

◆ searchCompetitors()

searchCompetitors	(	$string,
		$limit = `10`
	)

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

Try it out!

Parameters

string	$string	Query
int	$limit

Returns: array of Competitor objects

◆ searchContacts()

searchContacts	(	$string,
		$limit = `10`
	)

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

Try it out!

Parameters

string	$string	Query
int	$limit

Returns: array of Contact objects

◆ searchContactsAndUsers()

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	$string	Query
int	$limit

Returns: array
"result": [ User, Contact, ... ]

◆ searchLeads()

searchLeads	(	$string,
		$limit = `40`
	)

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

Try it out!

Parameters

string	$string	Query
int	$limit

Returns: array of Lead objects

◆ searchMentionableEntities()

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	$string	The query string to search for
string	$entityType	The type of the contextual entity
int	$entityId	The id of the contextual entity
array	$knownLocalEntities	An array of objects containing at least the entityType-id pair that represents any locally cached results that should not be returned. DISCLAIMER: Currently not respected.
int	$limit

Returns: array of entities with all entries of $knownLocalEntities filtered out

◆ searchProducts()

searchProducts	(	$string,
		$limit = `10`
	)

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

Try it out!

Parameters

string	$string	Query
int	$limit

Returns: array of Product objects

◆ searchSources()

searchSources	(	$string,
		$limit = `10`
	)

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

Try it out!

Parameters

string	$string	Query
int	$limit

Returns: array of Source objects

◆ searchUniversal()

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 $string Query

Returns: array
"result": {

"contacts": [ Contact, ... ],

"leads": [ Lead, ... ],

"accounts": [ Account, ... ]

}

◆ searchUsersAndTeams()

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	$string	Query
int	$limit

Returns: array
"result": [ User, Team, ... ]

Description

Public Member Functions

Member Function Documentation

◆ add()

◆ deleteAccount()

◆ deleteActivity()

◆ deleteContact()

◆ deleteLead()

◆ deleteNote()

◆ deleteProduct()

◆ deleteTask()

◆ deleteTeam()

◆ deleteUser()

◆ editAccount()

◆ editActivity()

◆ editContact()

◆ editLead()

◆ editNote()

◆ editProduct()

◆ editStep()

◆ editTask()

◆ editTeam()

◆ editUser()

◆ findAccounts()

◆ findAccountTypes()

◆ findActivities()

◆ findActivityTypes()

◆ findAudiences()

◆ findBackups()

◆ findCompetitors()

◆ findContacts()

◆ findCustomFields()

◆ findDelays()

◆ findIndustries()

◆ findLead_Outcomes()

◆ findLeads()

◆ findMarkets()

◆ findMilestones()

◆ findNotes()

◆ findOrigins()

◆ findProcesses()

◆ findProducts()

◆ findSettings()

◆ findSources()

◆ findStagesets()

◆ findTags()

◆ findTasks()

◆ findTeams()

◆ findTerritories()

◆ findTimeline()

◆ findUsers()

◆ getAccount()

◆ getActivity()

◆ getAnalyticsReport()

◆ getContact()

◆ getEmail()

◆ getLead()

◆ getNote()

◆ getProduct()

◆ getTask()

◆ getTeam()

◆ getUpdateTimes()

◆ getUser()

◆ instanceData()

◆ newAccount()

◆ newActivity()

◆ newBackup()

◆ newContact()

◆ newEmail()

◆ newLead()

◆ newNote()

◆ newProduct()

◆ newSource()

◆ newTag()

◆ newTask()

◆ newTeam()

◆ newUser()

◆ searchAccounts()

◆ searchActivityParticipants()

◆ searchByEmail()