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) and milestone (the
opportunity milestone).
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.
{
"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 ...}
]
}
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) and milestone (the
opportunity milestone).
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.
{
"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 ...}
]
}
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) and milestone (the
opportunity milestone).
Read more about embed.
|
Response
Returns HTTP status code 200. The body of the response will be an Opportunity object.
{
"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) and milestone (the
opportunity milestone).
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.
{
"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. Note that 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.
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
} ]
}
}
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) and milestone (the
opportunity milestone).
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.
{
"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"
}
}
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) and milestone (the
opportunity milestone).
Read more about embed.
|
Response
Returns HTTP status code 200. All good
{
"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.
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.
{
"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) and milestone (the
opportunity milestone).
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.
{
"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 ...}
]
}
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) and organisation (extended organisation details for people).
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.
{
"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,
"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": [],
"emailAddresses": [
{
"id": 12134,
"type": "Work",
"address": "scott@homestyleshop.co"
}
],
"pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png"
}
]
}
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.
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.
List associated cases
The collection of cases 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) and opportunity (the associated opportunity).
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.
{
"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"
},
"createdAt": "2015-12-07T16:54:27Z",
"updatedAt": "2015-12-07T16:54:27Z",
"description": "Scope and design web site shopping cart",
"name": "Consulting",
"closedOn": null,
"lastContactedAt": null
},
{... another kase object ...},
{... another kase object ...},
{... another kase object ...}
]
}
