Party

Parties represent the People and Organisations on your Capsule account. For a full description of the model see the Party model definition.

List parties

The collection of Parties on the Capsule account.

GET

https://api.capsulecrm.com/api/v2/parties

Query Parameters

Name	Type	Description
since	Date	If set then includes only entities that have been changed after this date. Must in be ISO8601 format.
page	Integer	The page of results to return. Default: `1`
perPage	Integer	The number of entities to return per page. Value must be between `1` and `100`. Default: `50`
embed	Array of String	Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are `tags` (tags), `fields` (custom fields and fields in DataTags), `organisation` (extended organisation details for people), and `missingImportantFields` (indicates if a party has any Important custom fields that are missing a value). Read more about `embed`.

Response

Returns HTTP status code 200. The body of the response will contain an object with a single property parties which is an array of Party objects. In the case of an invalid request, an error message will be returned, as described in the errors section.

HTTP/1.1 200
          
Link: <https://api.capsulecrm.com/api/v2/parties?page=4>; rel="next"

{
  "parties": [
    {
      "id": 11587,
      "type": "person",
      "about": null,
      "title": "Mr",
      "firstName": "Scott",
      "lastName": "Spacey",
      "jobTitle": "Creative Director",
      "createdAt": "2015-09-15T10:43:23Z",
      "updatedAt": "2015-09-15T10:43:23Z",
      "organisation": null,
      "lastContactedAt": null,
      "owner": null,
      "team": null,
      "addresses": [
        {
          "id": 12135,
          "type": null,
          "city": "Chicago",
          "country": "United States",
          "street": "847 North Rush Street",
          "state": "IL",
          "zip": "65629"
        }
      ],
      "phoneNumbers": [
        {
          "id": 12133,
          "type": null,
          "number": "773-338-7786"
        }
      ],
      "websites": [
        {
          "id": 106,
          "type": "Home",
          "address": "https://capsulecrm.com",
          "service": "URL",
          "url": "https://capsulecrm.com"
        },
        {
          "id": 109,
          "type": "Work",
          "address": "capsulecrm",
          "service": "TWITTER",
          "url": "https://twitter.com/capsulecrm"
        }
      ],
      "emailAddresses": [
        {
          "id": 12134,
          "type": "Work",
          "address": "scott@homestyleshop.co"
        }
      ],
      "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png"
    }
  ]
}

Headers:

Name	Type	Description
Link	String	Links to the next and previous pages, encoded as defined in RFC 5988.

Show party

Show a specific person or organisation.

GET

https://api.capsulecrm.com/api/v2/parties/{partyId}

Query Parameters

Name	Type	Description
embed	Array of String	Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are `tags` (tags), `fields` (custom fields and fields in DataTags), `organisation` (extended organisation details for people), and `missingImportantFields` (indicates if a party has any Important custom fields that are missing a value). Read more about `embed`.

Response

Returns HTTP status code 200. The body of the response will contain an object with a single property party which will contain a Party object.

HTTP/1.1 200

{
  "party": {
    "id": 11587,
    "type": "person",
    "about": null,
    "title": "Mr",
    "firstName": "Scott",
    "lastName": "Spacey",
    "jobTitle": "Creative Director",
    "createdAt": "2015-09-15T10:43:23Z",
    "updatedAt": "2015-09-15T10:43:23Z",
    "organisation": null,
    "lastContactedAt": null,
    "addresses": [
      {
        "id": 12135,
        "type": null,
        "city": "Chicago",
        "country": "United States",
        "street": "847 North Rush Street",
        "state": "IL",
        "zip": "65629"
      }
    ],
    "phoneNumbers": [
      {
        "id": 12133,
        "type": null,
        "number": "773-338-7786"
      }
    ],
    "websites": [
      {
        "id": 106,
        "type": "Home",
        "address": "https://capsulecrm.com",
        "service": "URL",
        "url": "https://capsulecrm.com"
      },
      {
        "id": 109,
        "type": "Work",
        "address": "capsulecrm",
        "service": "TWITTER",
        "url": "https://twitter.com/capsulecrm"
      }
    ],
    "emailAddresses": [
      {
        "id": 12134,
        "type": "Work",
        "address": "scott@homestyleshop.co"
      }
    ],
    "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png",
    "owner": {
      "id": 1,
      "username": "owner",
      "name": "Rupert Ada"
    },
    "team": null
  }
}

Show multiple parties

Allows to load a list of parties by providing their unique ids. partyIds must be a comma separated list of integers and can contain at most 10 values.

GET

https://api.capsulecrm.com/api/v2/parties/{partyIds}

Query Parameters

Name	Type	Description
embed	Array of String	Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are `tags` (tags), `fields` (custom fields and fields in DataTags), `organisation` (extended organisation details for people), and `missingImportantFields` (indicates if a party has any Important custom fields that are missing a value). Read more about `embed`.

Response

Returns HTTP status code 200. The body of the response will contain an object with a single property parties which is an array of Party objects. The endpoint will return 404 NOT FOUND if any one of the provided ids does not match and existing party. In the case of an invalid request, an error message will be returned, as described in the errors section.

HTTP/1.1 200

{
  "parties": [
    {
      "id": 11587,
      "type": "person",
      "about": null,
      "title": "Mr",
      "firstName": "Scott",
      "lastName": "Spacey",
      "jobTitle": "Creative Director",
      "createdAt": "2015-09-15T10:43:23Z",
      "updatedAt": "2015-09-15T10:43:23Z",
      "organisation": null,
      "lastContactedAt": null,
      "owner": null,
      "team": null,
      "addresses": [
        {
          "id": 12135,
          "type": null,
          "city": "Chicago",
          "country": "United States",
          "street": "847 North Rush Street",
          "state": "IL",
          "zip": "65629"
        }
      ],
      "phoneNumbers": [
        {
          "id": 12133,
          "type": null,
          "number": "773-338-7786"
        }
      ],
      "websites": [
        {
          "id": 106,
          "type": "Home",
          "address": "https://capsulecrm.com",
          "service": "URL",
          "url": "https://capsulecrm.com"
        },
        {
          "id": 109,
          "type": "Work",
          "address": "capsulecrm",
          "service": "TWITTER",
          "url": "https://twitter.com/capsulecrm"
        }
      ],
      "emailAddresses": [
        {
          "id": 12134,
          "type": "Work",
          "address": "scott@homestyleshop.co"
        }
      ],
      "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png"
    }
  ]
}

Create party

Creates a new party. The body must contain an object with a single property party which must be a Party object.

When adding tags you can specify either the tags id or name. Use the List Party Tags operation to get the list of tags already defined on your Capsule account.
To link a new person to an organisation you need to specify the id or name of the organisation to link to. If name is used and an organisation with that name doesn't already exist it will be created at the same time as the person.

"organisation": {
    "id": 1234
  }

"organisation": {
    "name": "HomeStyle"
  }

The owner and team properties are optional, with either owner and/or team being provided to assign the party to a user and/or team.
- If the owner property is not provided, the owner will be set to the user of the api access token being used. To explicitly set no owner set the owner property to null.
- If the owner property is provided but no team property is provided, the owner's default team will be used. To explicitly set no team set the team property to null.
To add a custom field you'll need to specify a definition id or name and a value. Use the List Field Definitions operation to get a list of the Party fields defined on your Capsule account.
- If you are identifying the custom field by name and the field belongs to a DataTag, you also need to specify the tag's id or name. For custom fields that don't belong to a DataTag you should explicitly state "tag": null.

POST

https://api.capsulecrm.com/api/v2/parties

          {
  "party": {
    "type": "person",
    "about": null,
    "title": "Mr",
    "firstName": "Scott",
    "lastName": "Spacey",
    "jobTitle": "Creative Director",
    "organisation": null,
    "owner": {
      "id": 1
    },
    "emailAddresses": [
      {
        "type": "Work",
        "address": "scott@homestyleshop.co"
      }
    ],
    "addresses": [
      {
        "type": null,
        "city": "Chicago",
        "country": "United States",
        "street": "847 North Rush Street",
        "state": "IL",
        "zip": "65629"
      }
    ],
    "phoneNumbers": [
      {
        "type": null,
        "number": "773-338-7786"
      }
    ],
    "websites": [
      {
        "type": "Home",
        "address": "https://capsulecrm.com",
        "service": "URL"
      },
      {
        "type": "Work",
        "address": "capsulecrm",
        "service": "TWITTER"
      }
    ],
    "tags": [ {"name": "Web Design"}, {"id": 1641} ],
    "fields": [
      {
         "definition": {
            "id": 1
         },
         "value": "Website"
      },
      {
        "definition": 2,
        "value": "2015-09-02"
      },
      {
        "definition": {
          "name": "Date of Birth",
          "tag": null
        },
        "value": "1979-02-03"
      },
      {
        "definition": {
          "name": "Sector",
          "tag": 14
        },
        "value": "Technology"
      }
    ]
  }
}

Query Parameters

Name	Type	Description
embed	Array of String	Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are `tags` (tags), `fields` (custom fields and fields in DataTags), `organisation` (extended organisation details for people), and `missingImportantFields` (indicates if a party has any Important custom fields that are missing a value). Read more about `embed`.

Response

Returns HTTP status code 201. The body of the response will contain the party as it was stored in Capsule.

HTTP/1.1 201
          
Location: https://api.capsulecrm.com/api/v2/parties/11587

{
  "party": {
    "id": 11587,
    "type": "person",
    "about": null,
    "title": "Mr",
    "firstName": "Scott",
    "lastName": "Spacey",
    "jobTitle": "Creative Director",
    "createdAt": "2015-09-15T10:43:23Z",
    "updatedAt": "2015-09-15T10:43:23Z",
    "organisation": null,
    "lastContactedAt": null,
    "addresses": [
      {
        "id": 12135,
        "type": null,
        "city": "Chicago",
        "country": "United States",
        "street": "847 North Rush Street",
        "state": "IL",
        "zip": "65629"
      }
    ],
    "phoneNumbers": [
      {
        "id": 12133,
        "type": null,
        "number": "773-338-7786"
      }
    ],
    "websites": [
      {
        "id": 106,
        "type": "Home",
        "address": "https://capsulecrm.com",
        "service": "URL",
        "url": "https://capsulecrm.com"
      },
      {
        "id": 109,
        "type": "Work",
        "address": "capsulecrm",
        "service": "TWITTER",
        "url": "https://twitter.com/capsulecrm"
      }
    ],
    "emailAddresses": [
      {
        "id": 12134,
        "type": "Work",
        "address": "scott@homestyleshop.co"
      }
    ],
    "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png",
    "owner": {
      "id": 1,
      "username": "owner",
      "name": "Rupert Ada"
    },
    "team": null
  }
}

Headers:

Name	Type	Description
Location	String	The URL that identifies the new party.

Update party

Update an existing party. The body must contain an object with a single property party which must be a Party object. Fields that are not included in the request will remain unchanged.

The owner and team are optional, with either owner and/or team being provided to assign the party to a user and/or team.

If the owner property is provided but no team property is provided, the owner's default team will be used, you can override this by setting the team property to null.

To apply changes to entities in the addresses, phoneNumbers, websites, emailAddresses, tags or fields collections you can do the following:

To add a new entity: create an entity without an id.
To update an existing entity: include the id and any attributes that are being updated.
To delete an existing entity: include the id and the following JSON attribute "_delete": true .

PUT

https://api.capsulecrm.com/api/v2/parties/{partyId}

          {
  "party": {
    "about": "Started as creative director in 2012",
    "phoneNumbers": [
      {
        "id": 12136,
        "_delete": true
      }
    ],
    "emailAddresses": [
      {
        "id": 12137,
        "type": "Home"
      },
      {
        "type": "Work",
        "address": "sales@homestyleshop.co"
      }
    ]
  }
}

Query Parameters

Name	Type	Description
embed	Array of String	Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are `tags` (tags), `fields` (custom fields and fields in DataTags), `organisation` (extended organisation details for people), and `missingImportantFields` (indicates if a party has any Important custom fields that are missing a value). Read more about `embed`.

Response

Returns HTTP status code 200. All good

HTTP/1.1 200

{
  "party": {
    "id": 11588,
    "type": "person",
    "about": "Started as creative director in 2012",
    "title": null,
    "firstName": "Scott",
    "lastName": "Spacey",
    "jobTitle": "Creative Director",
    "createdAt": "2015-09-15T12:18:08Z",
    "updatedAt": "2015-09-15T12:29:30Z",
    "organisation": null,
    "lastContactedAt": null,
    "owner": null,
    "team": null,
    "addresses": [
      {
        "id": 12138,
        "type": null,
        "city": "Chicago",
        "country": "United States",
        "street": "847 North Rush Street",
        "state": "IL",
        "zip": "65629"
      }
    ],
    "phoneNumbers": [],
    "websites": [],
    "emailAddresses": [
      {
        "id": 12137,
        "type": "Home",
        "address": "scott@homestyleshop.co"
      },
      {
        "id": 12139,
        "type": "Work",
        "address": "sales@homestyleshop.co"
      }
    ],
    "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png"
  }
}

Delete party

Fully delete the specific party from Capsule.

DELETE

https://api.capsulecrm.com/api/v2/parties/{partyId}

Response

Returns HTTP status code 204. Returns status code 204 with an empty body if the party was successfully deleted. In some cases Capsule might schedule the deletion for later and return HTTP status 202 Accepted as defined in Long Running Operation section.

HTTP/1.1 204

List employees

The collection of employees linked to this organisation.

GET

https://api.capsulecrm.com/api/v2/parties/{partyId}/people

Query Parameters

Name	Type	Description
page	Integer	The page of results to return. Default: `1`
perPage	Integer	The number of entities to return per page. Value must be between `1` and `100`. Default: `50`
embed	Array of String	Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are `tags` (tags), `fields` (custom fields and fields in DataTags), `organisation` (extended organisation details for people), and `missingImportantFields` (indicates if a party has any Important custom fields that are missing a value). Read more about `embed`.

Response

Returns HTTP status code 200. The body of the response will contain an object with a single property parties which is an array of Party objects.

HTTP/1.1 200
          
Link: <https://api.capsulecrm.com/api/v2/parties/1/people?page=2>; rel="next"

{
  "parties": [
    {
      "id": 11587,
      "type": "person",
      "about": null,
      "title": "Mr",
      "firstName": "Scott",
      "lastName": "Spacey",
      "jobTitle": "Creative Director",
      "createdAt": "2015-09-15T10:43:23Z",
      "updatedAt": "2015-09-15T10:43:23Z",
      "organisation": null,
      "lastContactedAt": null,
      "owner": null,
      "team": null,
      "addresses": [
        {
          "id": 12135,
          "type": null,
          "city": "Chicago",
          "country": "United States",
          "street": "847 North Rush Street",
          "state": "IL",
          "zip": "65629"
        }
      ],
      "phoneNumbers": [
        {
          "id": 12133,
          "type": null,
          "number": "773-338-7786"
        }
      ],
      "websites": [
        {
          "id": 106,
          "type": "Home",
          "address": "https://capsulecrm.com",
          "service": "URL",
          "url": "https://capsulecrm.com"
        },
        {
          "id": 109,
          "type": "Work",
          "address": "capsulecrm",
          "service": "TWITTER",
          "url": "https://twitter.com/capsulecrm"
        }
      ],
      "emailAddresses": [
        {
          "id": 12134,
          "type": "Work",
          "address": "scott@homestyleshop.co"
        }
      ],
      "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png"
    }
  ]
}

Headers:

Name	Type	Description
Link	String	Links to the next and previous pages, encoded as defined in RFC 5988.

List deleted parties

A collection of parties that have been deleted from Capsule since the date specified in the since parameter. Also contains parties that have been made restricted for the user calling the API endpoint.

GET

https://api.capsulecrm.com/api/v2/parties/deleted

Query Parameters

Name	Type	Description
since	Date	The since date is required to return only entities that have been deleted after this date. Must in be ISO8601 format.

Response

Returns HTTP status code 200. The body of the response will contain an object with a property parties which is an array of Deleted Party objects.

The body of the response object will also contain the property restrictedParties which is an array of Restricted Party objects. This is only present if any parties were made restricted.

In the case of an invalid request, an error message will be returned, as described in the errors section.

HTTP/1.1 200

{
  "parties": [
    {
      "id": 448354,
      "deletedAt": "2015-07-14T11:26:19Z"
    },
    {
      "id": 448371,
      "deletedAt": "2015-08-03T10:23:20Z"
    },
    {
      "id": 448426,
      "deletedAt": "2015-08-03T11:10:25Z"
    }
  ],
  "restrictedParties": [
      {
          "id": 448427,
          "type": "person",
          "firstName": null,
          "lastName": "Private",
          "pictureURL": "https://facehub.capsule.run/default/person?text=P&size=100",
          "isRestricted": true
      },
      {
          "id": 448428,
          "type": "organisation",
          "name": "Private",
          "pictureURL": "https://facehub.capsule.run/default/person?text=P&size=100",
          "isRestricted": true
      }
  ]
}

Search parties

Search for parties on the Capsule account. This will return the same results as the global search inside Capsule.

If you're looking for a more structured search endpoint you can use Filters to search by a specific field or tag.

GET

https://api.capsulecrm.com/api/v2/parties/search

Query Parameters

Name	Type	Description
q	String	The value to search for e.g. a name, a postcode or a phone number.
page	Integer	The page of results to return. Default: `1`
perPage	Integer	The number of entities to return per page. Value must be between `1` and `100`. Default: `50`
embed	Array of String	Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are `tags` (tags), `fields` (custom fields and fields in DataTags), `organisation` (extended organisation details for people), and `missingImportantFields` (indicates if a party has any Important custom fields that are missing a value). Read more about `embed`.

Response

HTTP/1.1 200
          
Link: <https://api.capsulecrm.com/api/v2/parties/search?q=Spacey&page=4>; rel="next"

{
  "parties": [
    {
      "id": 11587,
      "type": "person",
      "about": null,
      "title": "Mr",
      "firstName": "Scott",
      "lastName": "Spacey",
      "jobTitle": "Creative Director",
      "createdAt": "2015-09-15T10:43:23Z",
      "updatedAt": "2015-09-15T10:43:23Z",
      "organisation": null,
      "lastContactedAt": null,
      "owner": null,
      "team": null,
      "addresses": [
        {
          "id": 12135,
          "type": null,
          "city": "Chicago",
          "country": "United States",
          "street": "847 North Rush Street",
          "state": "IL",
          "zip": "65629"
        }
      ],
      "phoneNumbers": [
        {
          "id": 12133,
          "type": null,
          "number": "773-338-7786"
        }
      ],
      "websites": [
        {
          "id": 106,
          "type": "Home",
          "address": "https://capsulecrm.com",
          "service": "URL",
          "url": "https://capsulecrm.com"
        },
        {
          "id": 109,
          "type": "Work",
          "address": "capsulecrm",
          "service": "TWITTER",
          "url": "https://twitter.com/capsulecrm"
        }
      ],
      "emailAddresses": [
        {
          "id": 12134,
          "type": "Work",
          "address": "scott@homestyleshop.co"
        }
      ],
      "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png"
    }
  ]
}

Headers:

Name	Type	Description
Link	String	Links to the next and previous pages, encoded as defined in RFC 5988.