developers API Documentation

Person Attributes

Name Type Example Writable? Description
id integer 1234 no The unique id of the person
full_name string Bob Smoth yes The full_name of the person (will split on space to set first and last name)
first_name string Bob yes The first name of the person
last_name string Smith yes The last name of the person
summary string yes Text summary description of the person
phone string 123-123-1234 yes
home_phone string 123-123-1234 yes
mobile string 123-123-1234 yes
position string yes
website string yes
email string bob@bob.com yes
email2 string bob@bob.com yes
home_email string bob@bob.com yes
company_id string 1234 yes The company_id of the person
company_name string Bob Inc. yes The company name of the person (if changed, will find or create a company by that name)
user_id integer 1234 yes The user_id of the person
user object {id: 2134, full_name: 'Bob Smith'} no A convenience object to get the full name of the person owner
type string Contact or Lead yes Specify the person type.
lead_status_id integer 1234 yes Specify the lead status id
lead_status object {id: 1234, name: 'Hot'} no A convenience object to get the name of the status.
lead_source_id integer 1234 yes Specify the lead source id
lead_source object {id: 1234, name: 'Hot'} no A convenience object to get the name of the source.
image_thumb_url string https://s3.amazonaws.com/avatar.png yes A link to the person's avatar. Avatar is scaled to maximum of 50x50 pixels.
image_mobile_url string https://s3.amazonaws.com/avatar.png no A link to the person's mobile avatar. Mobile avatar is scaled to maximum of 100x100 pixels.
predefined_contacts_tag_ids array [23,24,25] yes An array of tag ids this person is tagged with
predefined_contacts_tags object [{id: 123, name: 'Hot lead'}, {id: 124, name: 'Golfer'}] no A convenience object to get the tag names
custom_fields object {custom_label_90: [45, 46, 47], custom_label_5: "text val"} yes Custom fields for the person. See custom fields section for more info.
work_address_1 string yes
work_address_2 string yes
work_city string yes
work_state string yes
work_country string yes
work_postal_code string yes
home_address_1 string yes
home_address_2 string yes
home_city string yes
home_state string yes
home_country string yes
home_postal_code string yes
facebook_url string yes
linked_in_url string yes
twitter string yes
instant_message string yes
created_at datetime 2012/02/07 15:26:10 -0500 yes Timestamp for when person was created
updated_at datetime 2012/02/07 15:26:10 -0500 yes Timestamp for when person was last updated
possible_notify_user_ids array [1,2,3,4,5] no The list of user_ids that can be added to notify_user_ids on associated notes.
unsubscribed boolean false yes Whether or not the person is unsubscribed.
bounced boolean false yes Whether or not the person has bounced email.
last_emailed_at datetime 2012/02/07 15:26:10 -0500 yes Timestamp for when person was last emailed

Person Associations

Retrieve notes associated to a person

GET /api/v3/people/1234/notes.json

Retrieve deals associated to a person

GET /api/v3/people/1234/deals.json

Retrieve calendar entries associated to a person

GET /api/v3/people/1234/calendar_entries.json

Receive a list of all People

The simplest way to get people is to simply call people with no parameters.

This will bring back the first 30 visible people to a user, with respect to visibility rules.

Request format

GET /people.json

Request Parameters

Param Type Description
page integer The offset of people
per_page integer The number of people per page
search_id integer Search people by previously saved filter with given search_id. Note: when you provide a search_id, all parameters except page and per_page will be ignored.
sort string The sort order of people.
conditions[person_id] integer The person with given person_id. Note: you can specify a comma-separated list of ids to retrieve more people at once, e.g. conditions[person_id]=1,2,3
conditions[person_name] string The people with name like person_name
conditions[person_owner] integer The people owned by the person_owner (user_id)
conditions[person_city] string The people with city like person_city
conditions[person_state] string The people with state like person_state
conditions[person_zip] string The people with zip code like person_zip
conditions[person_position] string The people with position like person_position
conditions[person_company_name] string The people with company name like person_company_name
conditions[lead_source] integer The people with lead source, (lead_source_id)
conditions[person_status] integer The people with the status person_status, (status_id)
conditions[person_email] string The people with email like person_email
conditions[person_full_name] string The people with full name like person_full_name
conditions[person_phone] string The people with phone number like person_phone
conditions[person_converted] datetime range The people that were converted during the supplied date range.
conditions[person_created] datetime range The people that were created during the supplied date range.
conditions[person_modified] datetime range The people that were modified during the supplied date range.
conditions[person_simple_search] string The people with first name, last name, email, or company name like person_simple_search.
conditions[person_type] string Accepts "Lead" or "Contact", to find people of that specific type.

Examples

curl "https://api.pipelinedeals.com/api/v3/people.json?api_key=abc1234&per_page=1"
HTTP Code
200
Body
{
  "pagination": {
    "page": 1,
    "total": 11,
    "per_page": 2
  },
  "entries": [
    {
      "fax": null,
      "id": 3,
      "facebook_url": null,
      "lead_source": {
        "id": 2,
        "name": "Cold Call"
      },
      "viewed_at": null,
      "work_city": "new york",
      "lead_status": {
        "id": 5,
        "name": "Follow-up"
      },
      "last_name": "Ajtai",
      "user": {
        "id": 1,
        "full_name": "admin nick"
      },
      "first_name": "Veronika",
      "updated_at": "2012/06/08 13:58:02 -0400",
      "work_country": null,
      "created_at": "2012/01/23 13:10:27 -0500",
      "email": "ffie2@w22md22b.org",
      "position": null,
      "company_name": "kwanzaa",
      "home_country": null,
      "home_state": null,
      "image_thumb_url": "/webpack/images/thumb/missing.png",
      "image_mobile_url": "/webpack/images/mobile/missing.png",
      "home_city": null,
      "home_phone": null,
      "work_state": "sc",
      "email2": null,
      "twitter": null,
      "custom_fields": {
        "custom_label_90": 49,
        "custom_label_83": [
          28,
          29,
          30
        ],
        "custom_label_89": "2012/05/21"
      },
      "work_postal_code": null,
      "instant_message": null,
      "linked_in_url": null,
      "predefined_contacts_tags": [

      ],
      "work_address_1": null,
      "work_address_2": null,
      "home_email": null,
      "home_address_1": null,
      "home_address_2": null,
      "type": "Contact",
      "company_id": 8,
      "user_id": 1,
      "predefined_contacts_tag_ids": [

      ],
      "mobile": null,
      "full_name": "Veronika Ajtai",
      "phone": null,
      "website": null,
      "home_postal_code": null
    },
    {
      "fax": null,
      "id": 4,
      "facebook_url": null,
      "lead_source": {
        "id": 2,
        "name": "Cold Call"
      },
      "viewed_at": null,
      "work_city": "22",
      "lead_status": {
        "id": 3,
        "name": "Warm"
      },
      "last_name": "Yarmosh",
      "user": {
        "id": 6,
        "full_name": "basic2 basic2"
      },
      "first_name": "Ken",
      "updated_at": "2012/06/05 10:40:31 -0400",
      "work_country": null,
      "created_at": "2012/01/23 13:10:27 -0500",
      "email": "ken@technosight.com",
      "position": null,
      "company_name": "yarmosh inc",
      "home_country": null,
      "home_state": null,
      "image_thumb_url": "/webpack/images/thumb/missing.png",
      "image_mobile_url": "/webpack/images/mobile/missing.png",
      "home_city": null,
      "home_phone": null,
      "work_state": "ny",
      "email2": null,
      "twitter": null,
      "custom_fields": {
        "custom_label_90": 48,
        "custom_label_82": 66,
        "custom_label_83": [
          28,
          29
        ],
        "custom_label_89": "2012/05/18"
      },
      "work_postal_code": "654323",
      "instant_message": null,
      "linked_in_url": "aaassss",
      "predefined_contacts_tags": [

      ],
      "work_address_1": null,
      "work_address_2": null,
      "home_email": null,
      "home_address_1": null,
      "home_address_2": null,
      "type": "Lead",
      "company_id": 15,
      "user_id": 6,
      "predefined_contacts_tag_ids": [

      ],
      "mobile": null,
      "full_name": "Ken Yarmosh",
      "phone": "1215-801-7554",
      "website": null,
      "home_postal_code": null
    }
  ]
}

Create a person

Request format

POST /people.json

Applying a todo template

To apply a people-based todo template, pass the people todo_template_id when creating the person.

To set the owner of any tasks created by applying the given todo template, you may also pass a todo_template_user_id parameter.

curl -X POST -d "person[last_name]=smith&todo_template_id=1234&todo_template_user_id=42" \
"https://api.pipelinedeals.com/api/v3/people.json?api_key=abc1234"

Examples

curl -X POST -d "person[last_name]=Bert" \
  "https://api.pipelinedeals.com/api/v3/people.json?api_key=abc1234"
HTTP Code
200
Body
{
  "phone": null,
  "company_id": 8,
  "home_city": null,
  "home_phone": null,
  "instant_message": null,
  "created_at": "2012/01/23 13:10:27 -0500",
  "full_name": "Veronika Ajtai",
  "work_postal_code": null,
  "predefined_contacts_tag_ids": [

  ],
  "facebook_url": null,
  "id": 3,
  "lead_source": {
    "id": 2,
    "name": "Cold Call"
  },
  "viewed_at": null,
  "twitter": null,
  "last_name": "Ajtai",
  "first_name": "Veronika",
  "website": null,
  "work_country": null,
  "predefined_contacts_tags": [

  ],
  "email": "ffie2@w22md22b.org",
  "work_city": "new york",
  "lead_status": {
    "id": 5,
    "name": "Follow-up"
  },
  "linked_in_url": null,
  "position": null,
  "home_country": null,
  "email2": null,
  "home_state": null,
  "company_name": "kwanzaa",
  "work_state": "sc",
  "custom_fields": {
    "custom_label_90": 49,
    "custom_label_83": [
      28,
      29,
      30
    ],
    "custom_label_89": "2012/05/21"
  },
  "home_postal_code": null,
  "fax": null,
  "home_email": null,
  "home_address_1": null,
  "home_address_2": null,
  "updated_at": "2012/06/08 13:58:02 -0400",
  "user_id": 1,
  "mobile": null,
  "work_address_1": null,
  "work_address_2": null,
  "type": "Contact",
  "image_thumb_url": "/webpack/images/thumb/missing.png",
  "image_mobile_url": "/webpack/images/mobile/missing.png",
  "user": {
    "full_name": "admin nick",
    "id": 1
  }
}

Failure Response

HTTP Code
422
Body
[
    {
        "field": "last_name", 
        "humanized_field": "Last name", 
        "msg": "can't be blank"
    }
]

Flags when creating a person

Below are a list of flags that can be used to manipulate how the system works when performing requests. They are added as parameters to the request.

check_for_duplicates

Default: false

Behavior: If true, the system will return an error if you attempt to create a duplicate contact.

A duplicate is any contact that that has the same last_name and email as an existing contact that is visible to the api user making the call.

Example of turning check_for_duplicates on

  curl -X POST -d "person[last_name]=Bert" \
  "https://api.pipelinedeals.com/api/v3/people.json?api_key=fXKPfR09VAV82DcTR4BR&check_for_duplicates=true"
  

deliver_assignment_email

Default: true

Behavior: If true, the system will send an email notification to the owner of the new person (if the owner is different than the user of the API request).

Set deliver_assignment_email=false to disable this notification.


Retrieve a person

Request format

GET /people/:id.json

Examples

curl "https://api.pipelinedeals.com/api/v3/people/8.json?api_key=abc1234"
HTTP Code
200
Body
{
  "phone": null,
  "company_id": 8,
  "home_city": null,
  "home_phone": null,
  "instant_message": null,
  "created_at": "2012/01/23 13:10:27 -0500",
  "full_name": "Veronika Ajtai",
  "work_postal_code": null,
  "predefined_contacts_tag_ids": [

  ],
  "facebook_url": null,
  "id": 3,
  "lead_source": {
    "id": 2,
    "name": "Cold Call"
  },
  "viewed_at": null,
  "twitter": null,
  "last_name": "Ajtai",
  "first_name": "Veronika",
  "website": null,
  "work_country": null,
  "predefined_contacts_tags": [

  ],
  "email": "ffie2@w22md22b.org",
  "work_city": "new york",
  "lead_status": {
    "id": 5,
    "name": "Follow-up"
  },
  "linked_in_url": null,
  "position": null,
  "home_country": null,
  "email2": null,
  "home_state": null,
  "company_name": "kwanzaa",
  "work_state": "sc",
  "custom_fields": {
    "custom_label_90": 49,
    "custom_label_83": [
      28,
      29,
      30
    ],
    "custom_label_89": "2012/05/21"
  },
  "home_postal_code": null,
  "fax": null,
  "home_email": null,
  "home_address_1": null,
  "home_address_2": null,
  "updated_at": "2012/06/08 13:58:02 -0400",
  "user_id": 1,
  "mobile": null,
  "work_address_1": null,
  "work_address_2": null,
  "type": "Contact",
  "image_thumb_url": "/webpack/images/thumb/missing.png",
  "image_mobile_url": "/webpack/images/mobile/missing.png",
  "user": {
    "full_name": "admin nick",
    "id": 1
  }
}

Failure Response

HTTP Code
404
Body
empty

Update a person

Request format

PUT /people/:id.json

Applying a todo template

To apply a people-based todo template, pass the people todo_template_id when updating the person.

To set the owner of any tasks created by applying the given todo template, you may also pass a todo_template_user_id parameter.

curl -X PUT -d "person[last_name]=smith&todo_template_id=1234&todo_template_user_id=42" \
"https://api.pipelinedeals.com/api/v3/people.json?api_key=abc1234"

Examples

curl -X PUT -d "person[lead_status_id]=13" \
  "https://api.pipelinedeals.com/api/v3/people/9.json?api_key=abc1234"
HTTP Code
200
Body
{
  "phone": null,
  "company_id": 8,
  "home_city": null,
  "home_phone": null,
  "instant_message": null,
  "created_at": "2012/01/23 13:10:27 -0500",
  "full_name": "Veronika Ajtai",
  "work_postal_code": null,
  "predefined_contacts_tag_ids": [

  ],
  "facebook_url": null,
  "id": 3,
  "lead_source": {
    "id": 2,
    "name": "Cold Call"
  },
  "viewed_at": null,
  "twitter": null,
  "last_name": "Ajtai",
  "first_name": "Veronika",
  "website": null,
  "work_country": null,
  "predefined_contacts_tags": [

  ],
  "email": "ffie2@w22md22b.org",
  "work_city": "new york",
  "lead_status": {
    "id": 5,
    "name": "Follow-up"
  },
  "linked_in_url": null,
  "position": null,
  "home_country": null,
  "email2": null,
  "home_state": null,
  "company_name": "kwanzaa",
  "work_state": "sc",
  "custom_fields": {
    "custom_label_90": 49,
    "custom_label_83": [
      28,
      29,
      30
    ],
    "custom_label_89": "2012/05/21"
  },
  "home_postal_code": null,
  "fax": null,
  "home_email": null,
  "home_address_1": null,
  "home_address_2": null,
  "updated_at": "2012/06/08 13:58:02 -0400",
  "user_id": 1,
  "mobile": null,
  "work_address_1": null,
  "work_address_2": null,
  "type": "Contact",
  "image_thumb_url": "/webpack/images/thumb/missing.png",
  "image_mobile_url": "/webpack/images/mobile/missing.png",
  "user": {
    "full_name": "admin nick",
    "id": 1
  }
}

Failure Response

HTTP Code
422
Body
[
    {
        "field": "last_name", 
        "humanized_field": "Last name", 
        "msg": "can't be blank"
    }, 
    {
        "field": "name", 
        "humanized_field": "Name", 
        "msg": "can't be blank"
    }
]

Update a person's tags

To update a person's tags supply an array with the set of tag ids you would like to be applied. Unknown tag ids will be ignored.

Examples

curl -X PUT -d "person[tag_ids][]=13&person[tag_ids][]=28" \
  "https://api.pipelinedeals.com/api/v3/people/9.json?api_key=abc1234"

Update a person's deals

To update a person's deals supply an array with the set of deal ids you would like to be applied. Unknown deal ids will be ignored.

Examples

curl -X PUT -d "person[deal_ids][]=23" \
  "https://api.pipelinedeals.com/api/v3/people/9.json?api_key=abc1234"

Flags when updating a person

Below are a list of flags that can be used to manipulate how the system works when performing requests. They are added as parameters to the request.

deliver_reassignment_email

Default: true

Behavior: If true, and you are changing a person's user_id, the system will send a lead assignment email to the new user.

Example of turning deliver_reassignment_email off

  curl -X PUT -d "person[user_id]=1234" \
  "https://api.pipelinedeals.com/api/v3/people/123.json?api_key=fXKPfR09VAV82DcTR4BR&deliver_reassignment_email=false"
  

Delete a person

Request format

DELETE /people/:id.json

Examples

curl -X DELETE "https://api.pipelinedeals.com/api/v3/people/10.json?api_key=abc1234"
HTTP Code
200
Body
empty

Failure Response

HTTP Code
404
Body
empty