Capsule CRM API Essential Guide

What type of API does Capsule CRM provide?

Based on the search results provided, Capsule CRM appears to have a REST API. The key points are:

1. The Capsule API is RESTful:

   • The API closely follows RESTful principles, with every resource having its own URL.
   • Resources can be manipulated using standard REST commands: GET (view), POST (create), PUT (update) and DELETE.

2. The API uses XML or JSON over HTTPS:

   • This allows developers to use existing tools and languages to interact with the API.

3. Capsule provides a RESTful API for integrating third-party or custom applications:

   • They refer developers to the "Capsule API getting started guide" for more information.

4. Authentication for the API uses OAuth 2:

   • This is preferred over API keys as it provides better security and control.

Does the Capsule CRM API have webhooks?

Yes, the official Capsule CRM API does have webhooks, which they refer to as "REST hooks".

The Capsule API allows you to subscribe to various events, including party/created, party/updated, party/deleted, project/created, project/updated, project/deleted, project/moved, opportunity/created, opportunity/updated, opportunity/deleted, opportunity/moved, user/created, user/updated, and user/deleted.

REST hooks are designed to avoid the need for polling and allow real-time notifications when events occur in Capsule. You can subscribe to a maximum of 20 REST hooks per account, and to use them, you need to register a client application and set up OAuth authentication.

When an event occurs, Capsule sends a POST request to the specified target URL with a JSON payload containing event details. REST hooks can be managed (subscribed, listed, and unsubscribed) through specific API endpoints, and only users with an Administrator role can subscribe or unsubscribe them. REST hooks are only visible to users authenticated via the registered application that subscribed them.

It's recommended to use REST hooks instead of polling to reduce overhead and get real-time updates, unsubscribe from unused hooks to maintain a clean setup, ensure your application can handle additional elements that may be added to responses in future API updates, and test your integrations thoroughly, especially when changes to the API are announced.

Rate Limits and other limitations

Here are the key points about the API Rate Limits for the Capsule CRM API:

Rate Limit Details

• The rate limit is 4,000 requests per hour per user for requests using Bearer Token Authentication [2].

• All successful API requests include three headers with rate limit information:

  • X-RateLimit-Limit: The maximum number of requests allowed per hour
  • X-RateLimit-Remaining: The number of requests remaining in the current rate limit window
  • X-RateLimit-Reset: The time when the current rate limit window resets (in UTC epoch seconds) [2]

Avoiding Rate Limit Issues

• It's recommended to add a one second delay between API requests to avoid hitting the rate limit [2].

• Caching API responses can help avoid rate limits. The API provides ways to retrieve only updated data since a certain date [2].

• Using the "since" query parameter on list endpoints allows retrieving only entities added or updated after a specified date [2].

• Endpoints are available to retrieve deleted entities, allowing you to keep a local cache up-to-date [2].

Rate Limit Errors

• If you exceed the rate limit, you'll receive a 429 Too Many Requests error response [2].

• The error response includes the rate limit headers showing 0 remaining requests and when the limit will reset [2].

• After receiving a rate limit error, wait until the time specified in X-RateLimit-Reset before making more requests [2].

Best Practices

• Design your application to handle the rate limits and use caching strategies where possible.

• Monitor your API usage and implement appropriate throttling mechanisms.

• If you consistently hit rate limits despite following best practices, contact Capsule CRM support for assistance [2].

By following these guidelines and being aware of the rate limits, you can ensure your integration with the Capsule CRM API remains stable and efficient.

Latest API Version

The most recent version of the Capsule CRM API is v2. Here are the key points about the Capsule CRM API:

API Version

• The current version of the Capsule CRM API is v2 [3][4].

Authentication

• API v2 uses OAuth 2 for authentication [4].
• Each request must be authenticated with a user's Bearer token [4].
• The API requests are made via HTTPS using the api.capsulecrm.com subdomain [4].

Key URLs

• API base URL: https://api.capsulecrm.com/api/v2/ [3][4]
• Authorization URL: https://api.capsulecrm.com/oauth/authorise [4]
• Token exchange URL: https://api.capsulecrm.com/oauth/token [4]
• Token revocation URL: https://api.capsulecrm.com/oauth/token/revoke [4]

Authentication Methods

1. OAuth 2 flow: Recommended for applications shared with other people [4].
2. Personal Access Tokens: For one-off integrations or internal use [4][5].

API Features

• The API supports REST hooks, which are Capsule's solution to webhooks [1].
• It allows integrations to link opportunities to cases [1].
• The API supports listing people at organizations and getting the Capsule account site address [1].

Best Practices

• Use OAuth 2 for shared applications [4].
• Generate different access tokens for each individual purpose [5].
• Restrict the scope of tokens to only what is required for the given purpose [5].
• Revoke tokens when they are no longer needed [4].

Recent Changes

• Cases have been renamed to Projects across Capsule, but the API endpoints still use the kases naming scheme [1].
• Documentation has been updated to include support for the Board and Stage endpoints [1].

It's important to note that Capsule regularly updates their API, so it's a good practice to check their developer documentation for the most up-to-date information.

How to get a Capsule CRM developer account and API Keys?

To get a developer account for Capsule CRM and create an API integration, you need to follow these steps:

1. Sign up for a Capsule CRM account if you don't already have one.
2. Generate a Personal Access Token in your Capsule account.
3. Register your application to get OAuth 2 credentials (client ID and secret).
4. Use the API documentation to implement the integration.

Key points to consider:

• Capsule provides a RESTful API that allows you to integrate third-party or custom applications.
• You can authenticate using either Personal Access Tokens or OAuth 2 flow.
• Personal Access Tokens are suitable for one-off integrations or internal use, while OAuth 2 is recommended for applications shared with other users.

Steps to create an API integration:

1. Generate a Personal Access Token:

   • Log in to your Capsule account
   • Go to My Preferences > API Authentication Tokens
   • Click "Generate new API token"

2. Register your application for OAuth 2 (if needed):

   • You'll need to register your application to get a client ID and secret
   • Choose "installed" as the application type for mobile or desktop apps

3. Implement authentication:

   • Use the Personal Access Token in the Authorization header for API requests
   • Or implement the OAuth 2 flow for user authorization

4. Use the API documentation:

   • Refer to the Capsule API documentation to make API calls and integrate with your application

Best practices:

• Generate different access tokens for each individual purpose
• Restrict the scope of tokens to only what is required
• Keep the client secret server-side and don't share it or include it in distributed code
• Use OAuth 2 for applications shared with other users, as it's more secure and user-friendly

What can you do with the Capsule CRM API?

Based on the information provided in the search results, here's a list of data models you can interact with using the Capsule CRM API, along with what is possible for each model:

User Model

• Retrieve user information, including:

  • User ID
  • Locale
  • Currency preference
  • Email preference
  • Click-to-call preference
  • Preferred email address
  • Associated party record
  • Username
  • Timezone
  • Name
  • Task reminder settings [2]

• List users on the account [3]

Project Model (formerly Cases)

• Create new projects
• Search for projects
• List projects
• Retrieve details of a specific project
• Interact with project-related data, such as:
  • Associated party
  • Project status
  • Description
  • Name
  • Stage
  • Expected close date
  • Custom fields
  • Tracks [4]

Entry Model

• List entries (notes, emails, and completed tasks) for parties, projects, and opportunities
• Create new entries
• Retrieve entry details, including:
  • Entry type (note, email, task)
  • Creator information
  • Activity type
  • Creation and update timestamps
  • Content
  • Associated party
  • Attachments (for notes and emails)
  • Participants (for emails) [5]

Party Model

• While not explicitly detailed in the provided search results, the Party model is referenced in relation to users and projects. It likely includes operations such as:
  • Retrieving party details
  • Creating new parties
  • Updating party information
  • Listing parties [9]

Additional Considerations

• The API supports pagination for requests that return multiple items [1]
• You can embed additional data in responses using the embed query parameter for certain endpoints [1]
• The API uses JSON for data exchange [1]
• Authentication is required using bearer tokens [1]
• Some endpoints support custom fields, which can be retrieved using the List Field Definitions operation [4]

It's important to note that while these are the main data models mentioned in the provided search results, the Capsule CRM API may include additional models and operations not covered in this summary. For a comprehensive understanding of all available data models and operations, it's recommended to consult the full API documentation.