Writing to the API

Adding a new record

Use the POST HTTP method to create new records.

In the following example we’re using curl to create a new organisation record. The API uses JSON for the request but it’s good practice to make sure that you include Content-type and Accept request headers of application/json as the API in the future may support more content types.

curl -i -X POST -H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "party": {
    "type": "organisation",
    "name": "Acme INC"
  }
}' https://api.capsulecrm.com/api/v2/parties

When creating a record the response header will contain an HTTP status of 201 Created and the body will contain the record stored in Capsule. Additionally, a Location response header will contain the URL you can use to retrieve the record over the API. To include the response headers in Curl add the -i command line option.

Response

{
    "party": {
        "id": 100,
        "type": "organisation",
        "about": null,
        "name": "Acme INC",
        "createdAt": "2015-11-30T16:20:05Z",
        "updatedAt": "2015-11-30T16:20:05Z",
        "lastContactedAt": null,
        "pictureURL": "https://capsulecrm.com/theme/default/images/org_avatar_70.png",
        "addresses": [],
        "phoneNumbers": [],
        "websites": [],
        "emailAddresses": []
    }
}

Updating an existing record

Use the PUT HTTP method to update existing records.

In the following we’re using curl to update an existing organisation record. To simplify updates on the API, only the details you’re updating need to be included in the JSON document you submit to the API. For example, when creating an organisation record, name attribute is required, however when making an update name is optional, if you’re only updating contact details. Any details that are not included in the request body remain unchanged on the record.

curl -i -X PUT -H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "party": {
    "type": "organisation",
    "name": "Acme"
  }
}' https://api.capsulecrm.com/api/v2/parties/100

Response

{
    "party": {
        "id": 100,
        "type": "organisation",
        "about": null,
        "name": "Acme",
        "createdAt": "2015-11-30T16:20:05Z",
        "updatedAt": "2015-11-30T16:20:05Z",
        "lastContactedAt": null,
        "pictureURL": "https://capsulecrm.com/theme/default/images/org_avatar_70.png",
        "addresses": [],
        "phoneNumbers": [],
        "websites": [],
        "emailAddresses": []
    }
}

The response from the API request will include the entire record including details that were not including in the body of your request.

Deleting a record

Use the DELETE HTTP method to remove a record from your account.

curl -i -X DELETE -H "Authorization: Bearer {token}" https://api.capsulecrm.com/api/v2/parties/100

Response