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

Number of entities to return per page. Value must be between 1 and 100 Default: 50

embed Array of String

Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Accepted values are tags, fields and organisation

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": null,
      "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": [],
      "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 specified 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 specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Accepted values are tags, fields and organisation

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": null,
    "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": [],
    "emailAddresses": [
      {
        "id": 12134,
        "type": "Work",
        "address": "scott@homestyleshop.co"
      }
    ],
    "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png"
  }
}

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 specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Accepted values are tags, fields and organisation

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": null,
      "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": [],
      "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 add a custom field you’ll need to specify a value and a definition id. Use the List Party Fields Definitions operation to get a list of fields defined on your Capsule account.

  "fields": [
    {
       "value": "Website",
       "definition": { "id": 1 }
    },
    {
      "definition": { "id": 2 } ,
      "value": "2015-09-02"
    }
  ]

POST
https://api.capsulecrm.com/api/v2/parties
          {
  "party": {
    "type": "person",
    "about": null,
    "title": null,
    "firstName": "Scott",
    "lastName": "Spacey",
    "jobTitle": "Creative Director",
    "organisation": null,
    "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": [],
    "tags": [ {"name": "Web Design"}, {"id": 1641} ],
    "fields": [
      {
         "value": "Website",
         "definition": { "id": 1 }
      },
      {
        "definition": { "id": 2 } ,
        "value": "2015-09-02"
      }
    ]
  }
}

        

Query Parameters

Name Type Description
embed Array of String

Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Accepted values are tags, fields and organisation

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": null,
    "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": [],
    "emailAddresses": [
      {
        "id": 12134,
        "type": "Work",
        "address": "scott@homestyleshop.co"
      }
    ],
    "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png"
  }
}

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.

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

  • updating an existing entity include the id and any attributes that are being updated
  • deleting an existing entity include the id and the following JSON attribute "_delete": true
  • adding a new entity create entity without an id

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 specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Accepted values are tags, fields and organisation

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,
    "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

Number of entities to return per page. Value must be between 1 and 100 Default: 50

embed Array of String

Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Accepted values are tags, fields and organisation

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": null,
      "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": [],
      "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 collections of parties that have been deleted from capsule since the date specified in the since parameter.

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 afer this date. Must in be ISO8601 format

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 Deleted 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
{
  "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"
    }
  ]
}

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 (like filtering by Tag) we don’t currently have these endpoints documented however they are on the way - if you would like early access please contact us at support@capsulecrm.com.

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

Number of entities to return per page. Value must be between 1 and 100 Default: 50

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/search?q=Spacey&page=4>; rel="next"
{
  "parties": [
    {
      "id": 11587,
      "type": "person",
      "about": null,
      "title": null,
      "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": [],
      "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