Opportunity

Opportunities are used to track potential sales with customers such as bids, deals or proposals. For a full description of the model, see the Opportunity model definition.

List opportunities

The collection of Opportunities on the Capsule account.

GET

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

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), `party` (assigned party), `milestone` (the opportunity milestone), and `missingImportantFields` (indicates if an opportunity 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 opportunity which is an array of Opportunity 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/opportunities?page=4>; rel="next"

{
  "opportunities": [
    {
      "id": 12,
      "updatedAt": "2015-10-29T12:55:12Z",
      "description": "Scope and design web site shopping cart",
      "owner": {
        "id": 6,
        "username": "scottspacey",
        "name": "Scott Spacey"
      },
      "party": {
        "id": 581,
        "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png",
        "type": "organisation",
        "name": "Capsule"
      },
      "lostReason": null,
      "milestone": {
        "id": 14,
        "name": "Bid"
      },
      "value": {
        "amount": 500,
        "currency": "GBP"
      },
      "expectedCloseOn": "2015-10-31",
      "probability": 50,
      "durationBasis": "FIXED",
      "duration": null,
      "closedOn": null,
      "createdAt": "2015-10-29T12:55:12Z",
      "name": "Consulting"
    },
    {...  another opportunity object ...},
    {...  another opportunity object ...},
    {...  another opportunity object ...}
  ]
}

Headers:

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

List opportunities by party

The collection of all opportunities associated with the given party.

GET

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

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), `party` (assigned party), `milestone` (the opportunity milestone), and `missingImportantFields` (indicates if an opportunity 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 opportunities which is an array of Opportunity 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/581/opportunities?page=4>; rel="next"

{
  "opportunities": [
    {
      "id": 12,
      "updatedAt": "2015-10-29T12:55:12Z",
      "description": "Scope and design web site shopping cart",
      "owner": {
        "id": 6,
        "username": "scottspacey",
        "name": "Scott Spacey"
      },
      "party": {
        "id": 581,
        "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png",
        "type": "organisation",
        "name": "Capsule"
      },
      "lostReason": null,
      "milestone": {
        "id": 14,
        "name": "Bid"
      },
      "value": {
        "amount": 500,
        "currency": "GBP"
      },
      "expectedCloseOn": "2015-10-31",
      "probability": 50,
      "durationBasis": "FIXED",
      "duration": null,
      "closedOn": null,
      "createdAt": "2015-10-29T12:55:12Z",
      "name": "Consulting"
    },
    {...  another opportunity object ...},
    {...  another opportunity object ...},
    {...  another opportunity object ...}
  ]
}

Headers:

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

Show opportunity

Returns a specific opportunity.

GET

https://api.capsulecrm.com/api/v2/opportunities/{opportunityId}

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), `party` (assigned party), `milestone` (the opportunity milestone), and `missingImportantFields` (indicates if an opportunity 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 be an Opportunity object.

HTTP/1.1 200

{
  "opportunity": {
    "id": 83948362,
    "updatedAt": "2015-10-29T12:55:12Z",
    "description": "Scope and design web site shopping cart",
    "owner": {
      "id": 6,
      "username": "scottspacey",
      "name": "Scott Spacey"
    },
    "party": {
      "id": 581,
      "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png",
      "type": "organisation",
      "name": "Capsule"
    },
    "lostReason": null,
    "milestone": {
      "id": 14,
      "name": "Bid"
    },
    "value": {
      "amount": 500,
      "currency": "GBP"
    },
    "expectedCloseOn": "2015-10-31",
    "probability": 50,
    "durationBasis": "FIXED",
    "duration": null,
    "closedOn": null,
    "createdAt": "2015-10-29T12:55:12Z",
    "name": "Consulting"
  }
}

Show multiple opportunities

Return a list of opportunities, specified by the opportunityIds provided. The opportunityIds must be a comma separated list of integers and can contain at most 10 values.

GET

https://api.capsulecrm.com/api/v2/opportunities/{opportunityIds}

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), `party` (assigned party), `milestone` (the opportunity milestone), and `missingImportantFields` (indicates if an opportunity 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 be an array of Opportunity objects. Will return status code 404 if at least one of the provided ids does not match an existing opportunity. In the case of an invalid request, an error message will be returned, as described in the errors section.

HTTP/1.1 200

{
  "opportunities": [
    {
      "id": 12,
      "updatedAt": "2015-10-29T12:55:12Z",
      "description": "Scope and design web site shopping cart",
      "owner": {
        "id": 6,
        "username": "scottspacey",
        "name": "Scott Spacey"
      },
      "party": {
        "id": 581,
        "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png",
        "type": "organisation",
        "name": "Capsule"
      },
      "lostReason": null,
      "milestone": {
        "id": 14,
        "name": "Bid"
      },
      "value": {
        "amount": 500,
        "currency": "GBP"
      },
      "expectedCloseOn": "2015-10-31",
      "probability": 50,
      "durationBasis": "FIXED",
      "duration": null,
      "closedOn": null,
      "createdAt": "2015-10-29T12:55:12Z",
      "name": "Consulting"
    },
    {...  another opportunity object ...},
    {...  another opportunity object ...},
    {...  another opportunity object ...}
  ]
}

Create opportunity

Creates a new opportunity. The body must contain an object with a single property opportunity which must be an Opportunity object.

One or more tracks can be applied to the opportunity by including the relevant track ids in a tracks array. This is a convenient shortcut to apply tracks to new opportunities only, and tracks is not a field of Opportunity objects. Tracks can be specified using a definition object or the ID shorthand, or a mixture of both, as shown below.
When adding tags you can specify either the tags id or name. Use the List Opportunity 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 definition id or name and a value. Use the List Opportunity Fields Definitions operation to get a list of fields defined on your Capsule account.

POST

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

          {
  "opportunity" : {
    "description" : "Scope and design web site shopping cart",
    "party" : {
      "id" : 581
    },
    "milestone" : {
      "id" : 14
    },
    "value" : {
      "amount" : 500,
      "currency" : "GBP"
    },
    "expectedCloseOn" : "2015-10-31",
    "probability" : 50,
    "durationBasis" : "FIXED",
    "name" : "Consulting",
    "tracks" : [ {
      "definition" : {
        "id" : 1
      }
    }, {
      "definition" : 2
    } ],
    "fields" : [ {
      "definition" : {
        "name" : "Client size"
      },
      "value" : "Medium"
    }, {
      "definition" : {
        "id" : 2
      },
      "value" : "2015-09-02"
    }, {
      "definition" : 3,
      "value" : "Yellow"
    } ],
    "tags" : [ {
      "id" : 123
    }, {
      "name" : "Web design"
    } ]
  }
}

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), `party` (assigned party), `milestone` (the opportunity milestone), and `missingImportantFields` (indicates if an opportunity 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 opportunity as it was stored in Capsule.

HTTP/1.1 201
          
Location: https://api.capsulecrm.com/api/v2/opportunities/83948362

{
  "opportunity": {
    "id": 83948362,
    "updatedAt": "2015-10-29T12:55:12Z",
    "description": "Scope and design web site shopping cart",
    "owner": {
      "id": 6,
      "username": "scottspacey",
      "name": "Scott Spacey"
    },
    "party": {
      "id": 581,
      "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png",
      "type": "organisation",
      "name": "Capsule"
    },
    "lostReason": null,
    "milestone": {
      "id": 14,
      "name": "Bid"
    },
    "value": {
      "amount": 500,
      "currency": "GBP"
    },
    "expectedCloseOn": "2015-10-31",
    "probability": 50,
    "durationBasis": "FIXED",
    "duration": null,
    "closedOn": null,
    "createdAt": "2015-10-29T12:55:12Z",
    "name": "Consulting"
  }
}

Headers:

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

Update opportunity

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

An owner and/or team are required on an opportunity.

To apply changes to entities in the tags or fields collections you can do the following:

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 .
To add a new entity: create an entity without an id.

PUT

https://api.capsulecrm.com/api/v2/opportunities/{opportunityId}

          {
  "opportunity": {
    "name": "new opportunity name",
    "tags": [
      {
        "id": 4,
        "_delete": true
      }
    ],
    "fields": [
      {
        "id": 1,
        "value": "sale"
      }
    ]
  }
}

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), `party` (assigned party), `milestone` (the opportunity milestone), and `missingImportantFields` (indicates if an opportunity 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

{
  "opportunity": {
    "id": 83948362,
    "updatedAt": "2015-10-29T12:55:12Z",
    "description": "Scope and design web site shopping cart",
    "owner": {
      "id": 6,
      "username": "scottspacey",
      "name": "Scott Spacey"
    },
    "party": {
      "id": 581,
      "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png",
      "type": "organisation",
      "name": "Capsule"
    },
    "tags": [],
    "lostReason": null,
    "milestone": {
      "id": 14,
      "name": "Bid"
    },
    "value": {
      "amount": 500,
      "currency": "GBP"
    },
    "expectedCloseOn": "2015-10-31",
    "probability": 50,
    "durationBasis": "FIXED",
    "duration": null,
    "closedOn": null,
    "createdAt": "2015-10-29T12:55:12Z",
    "name": "new opportunity name",
    "fields": [
        {
          "id": 1,
          "definition": {
          "id": 17,
          "name": "type"
        },
        "value": "sale",
        "tagId": null
      }
    ]
  }
}

Delete opportunity

Fully delete a specific opportunity from Capsule.

DELETE

https://api.capsulecrm.com/api/v2/opportunities/{opportunityId}

Response

Returns HTTP status code 204. Returns status code 204 with an empty body if the opportunity was successfully deleted.

HTTP/1.1 204

List deleted opportunities

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

GET

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

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.

Response

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

The body of the response object will also contain a property restrictedOpportunities which is an array of Restricted Opportunity objects. This is only present if any opportunities 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

{
  "opportunities" : [ {
    "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 opportunities

Search for opportunities 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/opportunities/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), `party` (assigned party), `milestone` (the opportunity milestone), and `missingImportantFields` (indicates if an opportunity 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/opportunities/search?q=design&page=4>; rel="next"

{
  "opportunities": [
    {
      "id": 12,
      "updatedAt": "2015-10-29T12:55:12Z",
      "description": "Scope and design web site shopping cart",
      "owner": {
        "id": 6,
        "username": "scottspacey",
        "name": "Scott Spacey"
      },
      "party": {
        "id": 581,
        "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png",
        "type": "organisation",
        "name": "Capsule"
      },
      "lostReason": null,
      "milestone": {
        "id": 14,
        "name": "Bid"
      },
      "value": {
        "amount": 500,
        "currency": "GBP"
      },
      "expectedCloseOn": "2015-10-31",
      "probability": 50,
      "durationBasis": "FIXED",
      "duration": null,
      "closedOn": null,
      "createdAt": "2015-10-29T12:55:12Z",
      "name": "Consulting"
    },
    {...  another opportunity object ...},
    {...  another opportunity object ...},
    {...  another opportunity object ...}
  ]
}

Headers:

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

List additional parties

The collection of additional parties related to this opportunity.

GET

https://api.capsulecrm.com/api/v2/opportunities/{opportunityId}/parties

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/opportunities/1/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.

Add additional party

Add a person or organisation as an additional contact to the opportunity.

POST

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

Response

Returns HTTP status code 204. Returns status code 204 with an empty body if the related contact was successfully added.

HTTP/1.1 204

Remove additional party

Remove that person or organisation as an additional contact of the opportunity.

DELETE

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

Response

Returns HTTP status code 204. Returns status code 204 with an empty body if the related contact was successfully deleted.

HTTP/1.1 204

List associated projects

The collection of projects related to this opportunity.

GET

https://api.capsulecrm.com/api/v2/opportunities/{opportunityId}/kases

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), `party` (assigned party), `opportunity` (the associated opportunity), and `missingImportantFields` (indicates if a project 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 kases which is an array of Kase objects.

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

{
  "kases": [
    {
      "id": 12,
      "party": {
        "id": 892,
        "type": "organisation",
        "name": "Zestia",
        "pictureURL": "https://capsulecrm.com/theme/default/images/org_avatar_70.png"
      },
      "owner": {
        "id": 61,
        "username": "ted",
        "name": "Ted Danson"
      },
      "status": "OPEN",
      "opportunity": {
        "id": 83948362,
        "name": "Scope and design web site shopping cart"
      },
      "stage": {
        "name": "Project Brief",
        "id": 149
      },
      "createdAt": "2015-12-07T16:54:27Z",
      "updatedAt": "2015-12-07T16:54:27Z",
      "expectedCloseOn": "2015-12-09",
      "description": "Scope and design web site shopping cart",
      "name": "Consulting",
      "closedOn": null,
      "lastContactedAt": null
    },
    {... another project object ...},
    {... another project object ...},
    {... another project object ...}
  ]
}

Headers:

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