Deprecation warning - version 1 of the Capsule API will not be available after January 31, 2018. Developers should use version 2 when developing their applications. Developers who have already built applications please check our migration guide on how to move your applications to the latest version.

Show a Party

Show a specified person or organisation:

GET /api/party/:party-id

Response

HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<person>
  <id>100</id>
  <firstName>Eric</firstName>
  <lastName>Schmidt</lastName>
  <createdOn>2011-09-14T15:22:01Z</createdOn>
  <updatedOn>2011-12-14T10:45:46Z</updatedOn>
</person>{
  "person": {
    "id": "100",
    "firstName": "Eric",
    "lastName": "Schmidt",
    "createdOn": "2011-09-14T15:22:01Z",
    "updatedOn": "2011-12-14T10:45:46Z"
  }
}

Show as JSONShow as XML

List Parties

The collection of parties on the Capsule account:

GET /api/party

The list of parties can be filtered by using one of the following options:

  • ?q= The search term will be matched against name, telephone number and exact match on searchable custom fields.
  • ?email= Search by email address
  • ?lastmodified= Added or updated since the date specified (UTC timezone). The date must be specified in the following format YYYYMMDDTHHMMSS. eg. Midnight June 31, 2009 GMT would be 20090631T000000
  • ?tag= Tagged with the selected tag

The results can also be paginated using the following options:

  • &start= first record to be returned. The results start with an index of 0.
  • &limit= the maximum number of matching records to be returned

Response

HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<parties>
  <person>
    <id>100</id>
    <firstName>Eric</firstName>
    <lastName>Schmidt</lastName>
    <createdOn>2011-09-14T15:22:01Z</createdOn>
    <updatedOn>2011-12-14T10:45:46Z</updatedOn>
  </person>
  <person>
    <id>101</id>
    <firstName>Larry </firstName>
    <lastName>Page</lastName>
    <createdOn>2011-09-14T15:22:01Z</createdOn>
    <updatedOn>2011-11-15T10:50:48Z</updatedOn>
  </person>
  <organisation>
    <id>50</id>
    <name>Google Inc</name>
    <createdOn>2011-09-14T15:22:01Z</createdOn>
    <updatedOn>2011-12-14T10:45:46Z</updatedOn>
  </organisation>
</parties>{
  "parties": {
    "person": [
      {
        "id": "100",
        "firstName": "Eric",
        "lastName": "Schmidt",
        "createdOn": "2011-09-14T15:22:01Z",
        "updatedOn": "2011-12-14T10:45:46Z"
      },
      {
        "id": "101",
        "firstName": "Larry ",
        "lastName": "Page",
        "createdOn": "2011-09-14T15:22:01Z",
        "updatedOn": "2011-11-15T10:50:48Z"
      }
    ],
    "organisation": {
      "id": "50",
      "name": "Google Inc",
      "createdOn": "2011-09-14T15:22:01Z",
      "updatedOn": "2011-12-14T10:45:46Z"
    }
  }
}

Show as JSONShow as XML

List People at an Organisation

List the collection of people associated with a specific organisation:

GET /api/party/:id/people

Response

HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<parties>
  <person>
    <id>100</id>
    <firstName>Eric</firstName>
    <lastName>Schmidt</lastName>
  </person>
  <person>
    <id>101</id>
    <firstName>Larry </firstName>
    <lastName>Page</lastName>
  </person>
</parties>{
  "parties": {
    "person": [
      {
        "id": "100",
        "firstName": "Eric",
        "lastName": "Schmidt"
      },
      {
        "id": "101",
        "firstName": "Larry ",
        "lastName": "Page"
      }
    ]
  }
}

Show as JSONShow as XML

Add a Person

POST /api/person

Request

  • title optional personal title; options include Mr, Master, Mrs, Miss, Ms and Dr.
  • firstName and lastName at least one of these is required
  • jobTitle optional the job title for the person
  • about background information about the person
  • organisationName and organisationId optional, links the person to an organisation either searching for the organisation by name (if one is not found a new record is created automatically) or using the organisation party id.

Adding contact details - in the contacts element email, phone, web and physical addresses can be added.

address

  • type optional, can be one of the following options Home, Office, Postal
  • street, city, state, zip and country at least one of these is required to create an address
  • country from the list options available using GET /api/countries

email

  • type optional, can be one of the following options Work, Home
  • emailAddress required, valid email address

phone

  • type optional, can be one of the following options Home, Work, Mobile, Fax, Direct
  • phoneNumber required

website

  • type optional, can be one of the following options Work, Home
  • webService required, can be one of the following options URL, SKYPE, TWITTER, FACEBOOK, LINKED_IN, XING, FEED, GOOGLE_PLUS, FLICKR, GITHUB, YOUTUBE
  • webAddress required, a web URL
    • for SKYPE and TWITTER this should be the username (i.e. capsulecrm)
    • for FACEBOOK, LINKED_IN and XING user the public profile URL for the contact
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<person>
  <contacts>
    <address>
      <type>Office</type>
      <street>1600 Amphitheatre Parkway</street>
      <city>Mountain View</city>
      <state>CA</state>
      <zip>94043</zip>
      <country>United States</country>
    </address>
    <email>
      <type>Home</type>
      <emailAddress>e.schmidt@google.com</emailAddress>
    </email>
    <phone>
      <type>Mobile</type>
      <phoneNumber>+1 888 555555</phoneNumber>
    </phone>
    <website>
      <type>work</type>
      <webService>URL</webService>
      <webAddress>www.google.com</webAddress>
    </website>
  </contacts>
  <title>Mr</title>
  <firstName>Eric</firstName>
  <lastName>Schmidt</lastName>
  <jobTitle>Chairman</jobTitle>
  <organisationName>Google Inc</organisationName>
  <about>A comment here</about>
</person>{
  "person": {
    "contacts": {
      "address": {
        "type": "Office",
        "street": "1600 Amphitheatre Parkway",
        "city": "Mountain View",
        "state": "CA",
        "zip": "94043",
        "country": "United States"
      },
      "email": {
        "type": "Home",
        "emailAddress": "e.schmidt@google.com"
      },
      "phone": {
        "type": "Mobile",
        "phoneNumber": "+1 888 555555"
      },
      "website": {
        "type": "work",
        "webService": "URL",
        "webAddress": "www.google.com"
      }
    },
    "title": "Mr",
    "firstName": "Eric",
    "lastName": "Schmidt",
    "jobTitle": "Chairman",
    "organisationName": "Google Inc",
    "about": "A comment here"
  }
}

Show as JSONShow as XML

Response

HTTP/1.1 201 Created
Location: https://sample.capsulecrm.com/api/party/100

Add Organisation

POST /api/organisation

Request

  • name required, company name
  • about optional, background information about the person
  • contact details are in the same format as adding a person
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<organisation>
  <contacts>
    <address>
      <type>Office</type>
      <street>1600 Amphitheatre Parkway</street>
      <city>Mountain View</city>
      <state>CA</state>
      <zip>94043</zip>
      <country>United States</country>
    </address>
  </contacts>
  <name>Google Inc</name>
  <about>A comment here</about>
</organisation>{
  "organisation": {
    "contacts": {
      "address": {
        "type": "Office",
        "street": "1600 Amphitheatre Parkway",
        "city": "Mountain View",
        "state": "CA",
        "zip": "94043",
        "country": "United States"
      }
    },
    "name": "Google Inc",
    "about": "A comment here"
  }
}

Show as JSONShow as XML

Response

HTTP/1.1 201 Created
Location: https://sample.capsulecrm.com/api/party/50

Update a Person

Update a specific person:

PUT /api/person/:party-id

Request

Only the details that require updating need to be included in the XML or JSON request. To delete an existing email, phone number, address or web address from a Person include a delete="true" attribute on the element of the contact detail to be deleted i.e. <email delete="true"><id>123</id></email> or, if using JSON, "email": { "id": "123", "@delete": true }.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<person>
  <firstName>James</firstName>
</person>{
  "person": {
    "firstName": "James"
  }
}

Show as JSONShow as XML

Response

HTTP/1.1 200 OK

Update an Organisation

PUT /api/organisation/:party-id

Request

Only the details that require updating need to be included in the XML or JSON request. To delete an existing email, phone number, address or web address from an Organisation include a deleted="true" attribute on the element of the contact detail to be deleted i.e. <email delete="true"><id>123</id></email> or, if using JSON, "email": { "id": "123", "@delete": true }.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<organisation>
  <name>New Co.</name>
</organisation>{
  "organisation": {
    "name": "New Co."
  }
}

Show as JSONShow as XML

Response

HTTP/1.1 200 OK

Delete Contact from a Party

Remove an email, phone number, address or web address from a person or organisation:

DELETE /api/party/:party-id/contact/:contact-id

Response

HTTP/1.1 200 OK

Delete a Party

Delete a specific party:

DELETE /api/party/:party-id

Response

HTTP/1.1 200 OK