Custom Field

Custom fields allow you to record information about your contacts, projects or sales opportunities. These endpoints allow to manage the custom fields' definitions in the Capsule account. For a full description of the model see the Fields definition model description.

To add, remove or update custom field values use the update party, update opportunity or update project endpoints.

List custom fields

The collection of all custom fields on this Capsule account. The entity parameter inside the URL must be parties, opportunities or kases and defines which custom fields to return.

GET
https://api.capsulecrm.com/api/v2/{entity}/fields/definitions

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

Response

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

HTTP/1.1 200
Link: <https://api.capsulecrm.com/api/v2/parties/fields/definitions?page=2>; rel="next" 
{
  "definitions" : [ {
    "id" : 45,
    "type" : "text",
    "displayOrder" : 1,
    "name" : "Refering Site"
  }, {
    "id" : 51,
    "type" : "number",
    "displayOrder" : 1,
    "name" : "Lead Score",
    "tag" : {
      "id" : 1499,
      "name" : "Lead",
      "dataTag" : true
    }
  }, {
    "id" : 46,
    "type" : "date",
    "description" : "Birthday Field",
    "displayOrder" : 2,
    "name" : "Date of Birth",
    "captureRule" : "person"
  }, {
    "id" : 47,
    "type" : "list",
    "displayOrder" : 3,
    "name" : "Industry Sector",
    "captureRule" : "organisation",
    "options" : [ "Technology", "Insurance", "Financial services", "Retail & consumer" ]
  }, {
    "id" : 48,
    "type" : "boolean",
    "displayOrder" : 4,
    "name" : "Local"
  } ]
}

Headers:

Name Type Description
Link String

Links to the next and previous pages, encoded as defined in RFC 5988.

Show custom field

Show a specific custom field.

GET
https://api.capsulecrm.com/api/v2/{entity}/fields/definitions/{fieldId}

Response

Returns HTTP status code 200. The body of the response will contain an object with a single property definition which is a Field Definition object.

HTTP/1.1 200 
{
  "definition" : {
    "id" : 52,
    "type" : "list",
    "displayOrder" : 1,
    "name" : "Type",
    "tag" : {
      "id" : 1501,
      "name" : "Integration Partner",
      "dataTag" : true
    },
    "options" : [ "Accounting", "Helpdesk", "Mailing" ]
  }
}

Create custom field

Creates a new party, opportunity or project custom field specified by the entity parameter inside the URL, which must be parties, opportunities or kases.

Custom fields can be created on data tags - i.e. tags with dataTag set to true. Simply specify the id or name of the tag in the request body as shown below.

The body must contain an object with a single property definition which must be a Field Definition object.

POST
https://api.capsulecrm.com/api/v2/{entity}/fields/definitions
          {
  "definition" : {
    "type" : "List",
    "name" : "Type",
    "options" : [ "Accounting", "Helpdesk", "Mailing" ],
    "tag" : {
      "name" : "Integration Partner"
    }
  }
}

Response

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

HTTP/1.1 201
Location: https://api.capsulecrm.com/api/v2/parties/fields/definitions/100 
{
  "definition" : {
    "type" : "List",
    "name" : "Type",
    "options" : [ "Accounting", "Helpdesk", "Mailing" ],
    "tag" : {
      "name" : "Integration Partner"
    }
  }
}

Headers:

Name Type Description
Location String

The URL that identifies the new field.

Update custom field

Update the details of a party, opportunity or project field definition. The body must contain an object with a single property definition which must be a Field Definition object.

PUT
https://api.capsulecrm.com/api/v2/{entity}/fields/definitions/{fieldId}
          {
  "definition" : {
    "name" : "Integration Type",
    "tag" : {
      "name" : "Integration Partner"
    }
  }
}

Response

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

HTTP/1.1 200 
{
  "definition" : {
    "id" : 52,
    "type" : "list",
    "displayOrder" : 1,
    "name" : "Integration Type",
    "tag" : {
      "id" : 1501,
      "name" : "Integration Partner",
      "dataTag" : true
    },
    "options" : [ "Accounting", "Helpdesk", "Mailing" ]
  }
}

Delete custom field

Removes a custom field from this Capsule account. Note that this will remove the field value from any parties, opportunities and projects it was assigned to.

DELETE
https://api.capsulecrm.com/api/v2/{entity}/fields/definitions/{fieldId}

Response

Returns HTTP status code 204. However, Capsule might schedule the deletion for later and return HTTP status 202 Accepted as defined in Long Running Operation section.

HTTP/1.1 204