A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The SugarCRM API is how an app or AI agent works with a CRM instance: listing accounts, reading a contact, creating a lead, updating an opportunity, or filing a case. Access starts by exchanging a user's login for a token, and that user's role and access lists decide which modules and records the token can read or change. SugarCRM does not split access into per-method permissions, so an agent inherits exactly what its login can see and do.
How an app or AI agent connects to SugarCRM determines what it can reach. A call signs in for an access token, then sends that token on every request, and a separate route lets SugarCRM push changes out to other systems.
The REST API is served from each instance at https://
The /bulk endpoint runs a sequence of REST requests in one call. A client POSTs a requests array, each entry naming a url, method, and optional data and headers, and the requests run in order with their results returned together. A failure inside one sub-request does not stop the batch, which cuts the round trips an agent makes for a multi-step task.
SugarCRM has no hosted webhook product on the core REST API. An administrator configures outbound notifications inside the instance with logic hooks or the Sugar Connect framework, so a change like a new or updated record can call another system. This is set up per instance rather than registered through the REST API.
The primary login. A call POSTs to /oauth2/token with grant_type=password, a client_id (commonly 'sugar'), a client_secret, the user's username and password, and a platform value such as base. It returns a bearer access_token, an expires_in, and a refresh_token. The token represents one Sugar user, and that user's role and ACLs decide its access. There is no hosted consent screen.
When an access token expires, a call POSTs to /oauth2/token with grant_type=refresh_token plus the refresh_token, client_id, client_secret, and platform, and receives a new access token without re-sending the password. The refresh token has its own lifetime, returned as refresh_expires_in.
The SugarCRM API is organized around modules, the record types a CRM holds, like Accounts, Contacts, Leads, Opportunities, and Cases. Each module shares the same set of methods to list, read, create, update, delete, and relate records, and a write changes real customer data.
Generic create, read, update, and delete on any module, like Accounts, Contacts, Leads, Opportunities, and Cases.
List and filter records in a module by an expression, with paging and field selection.
List, create, relate, and unlink records across module relationships.
Global, cross-module search over fields flagged for unified search.
Discover the instance's modules, fields, views, and dropdown options.
Read the profile and preferences of the authenticated user.
Run many requests in one call, and check that the API is reachable.
Sign in for a token, refresh it, and log out.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Records (by module)Generic create, read, update, and delete on any module, like Accounts, Contacts, Leads, Opportunities, and Cases.4 | ||||||
| GET | / | Retrieve a single record from a module by its id. | read | — | Current | |
No OAuth scope. Requires the user to have view access to the record via role and ACLs. Acts onrecord Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | / | Create a record in a module, optionally relating it to existing records. | write | — | Current | |
No OAuth scope. Requires edit/create access on the module via role and ACLs. Acts onrecord Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | / | Update an existing record in a module. | write | — | Current | |
No OAuth scope. Requires edit access on the record. A concurrent change can return 409 edit_conflict. Acts onrecord Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | / | Delete a record from a module. | write | — | Current | |
No OAuth scope. Requires delete access on the module via role and ACLs. Acts onrecord Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Filter & listList and filter records in a module by an expression, with paging and field selection.4 | ||||||
| GET | / | List filtered records from a module, with paging, ordering, and field selection. | read | — | Current | |
No OAuth scope. Returns only what the user's role and ACLs allow on that module. Pages with max_num and offset; next_offset is -1 when done. Acts onrecord Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | / | Retrieve a list of records from a module filtered by an expression, with and/or conditions. | read | — | Current | |
No OAuth scope. POST is recommended over the GET form because long filter URLs can break. A saved filter id can be passed instead of, or joined with, an inline filter. Acts onrecord Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | / | Retrieve a filtered list of records from a module via query parameters. | read | — | Current | |
No OAuth scope. Same as the POST form, but limited by maximum URL length on large filters. Acts onrecord Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | / | Return the number of records in a module that match the given filter. | read | — | Current | |
No OAuth scope. Counts only records the user is permitted to see. Acts onrecord Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Related records (links)List, create, relate, and unlink records across module relationships.5 | ||||||
| GET | / | List records related to a particular record through a named relationship. | read | — | Current | |
No OAuth scope. Returns related records the user is allowed to see, like an account's contacts. Acts onrelated_record Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | / | Create a new related record and link it to the given record in one call. | write | — | Current | |
No OAuth scope. Requires edit access on both the module and the related module. Acts onrelated_record Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | / | Relate two existing records from different modules through a relationship. | write | — | Current | |
No OAuth scope. Links two records that already exist, like attaching an existing contact to an account. Acts onrelationship Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | / | Unlink the relationship between two related records. | write | — | Current | |
No OAuth scope. Removes the link between two records; it does not delete either record. Acts onrelationship Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | / | Mark a record as a favorite for the current user. | write | — | Current | |
No OAuth scope. Affects the current user's favorites, not the record's shared data. Acts onfavorite Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SearchGlobal, cross-module search over fields flagged for unified search.1 | ||||||
| GET | /search | Search across modules for records matching a text query, over fields flagged for unified search. | read | — | Current | |
No OAuth scope. The q parameter matches fields with unified_search enabled; max_num and offset page the results. Returns only records the user can see. Acts onsearch_result Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Metadata & enumsDiscover the instance's modules, fields, views, and dropdown options.3 | ||||||
| GET | /metadata | Return the instance's full metadata: modules, fields, relationships, views, and layouts. | read | — | Current | |
No OAuth scope. The response can be several megabytes; a type_filter narrows it, and the _hash lets a client send X-Metadata-Hash to skip unchanged metadata. Acts onmetadata Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /metadata/ | Return a specific metadata segment for a module that is not in the default metadata context. | read | — | Current | |
No OAuth scope, but this endpoint is administrator-only. It is used for modules not visible in the standard metadata response. Acts onmetadata Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | / | Retrieve the dropdown (enum) options available for a field on a module. | read | — | Current | |
No OAuth scope. Returns the key-and-label option list for the field, like the account_type values on Accounts. Acts onenum Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Current userRead the profile and preferences of the authenticated user.1 | ||||||
| GET | /me | Get the current user: the profile and preferences of the login the token belongs to. | read | — | Current | |
No OAuth scope. Useful to confirm which Sugar user a token authenticates as, and therefore its effective access. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Bulk & serviceRun many requests in one call, and check that the API is reachable.2 | ||||||
| POST | /bulk | Run a sequence of REST requests in one call, executed in order with their results returned together. | write | — | Current | |
No OAuth scope. Each sub-request carries the same access as the token. A failure inside one sub-request does not stop the batch. Acts onbulk_request Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /ping | Check that the Sugar REST API is reachable and responding. | read | — | Current | |
No OAuth scope. A lightweight reachability check. Acts onservice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AuthenticationSign in for a token, refresh it, and log out.2 | ||||||
| POST | /oauth2/token | Sign in to the Sugar REST API and retrieve an OAuth 2.0 access token (password or refresh_token grant). | write | — | Current | |
No OAuth scope. Returns a bearer access_token, expires_in, and a refresh_token. The token represents one Sugar user. Acts ontoken Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /oauth2/logout | Log out of the Sugar REST API and invalidate the current session token. | write | — | Current | |
No OAuth scope. Ends the session tied to the access token. Acts ontoken Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SugarCRM does not expose a hosted webhook product on the REST API. An administrator wires up outbound notifications inside the instance using logic hooks or the Sugar Connect framework, so a change like a new lead can reach another system.
| Event | What it signals | Triggered by |
|---|
SugarCRM runs on each customer's own instance, so how fast and how much an app can call is governed by that instance's server and platform settings rather than a single published rate ceiling.
SugarCRM is deployed per customer, on SugarCloud or self-hosted, so there is no single published account-wide request-rate ceiling like a multi-tenant SaaS. Throughput is bounded by the instance's web server, PHP, and database capacity, and by platform-level settings an administrator controls. A heavy call, like the full Metadata API response, can be several megabytes, so the X-Metadata-Hash header lets a client skip re-fetching unchanged metadata. The /bulk endpoint reduces round trips by running a sequence of requests in one call.
A list or filter call pages with max_num to set the page size and offset to skip records. The response returns a next_offset field, which is the offset to pass for the next page, or -1 when no more records remain. A fields parameter narrows which fields come back to reduce payload size, and an order_by parameter sorts the results.
The full Metadata API response is typically a few megabytes and grows with customization. A request exceeding the instance's configured limit returns HTTP 413 request_too_large. The /bulk endpoint accepts a requests array, and a failure inside one sub-request does not stop the batch or fail the overall call.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 301 | incorrect_version | The requested REST API version is wrong or unavailable on this instance. | Call a supported version in the path (/rest/v11/) or the Accept header, and check the instance's supported versions. |
| 401 | need_login / invalid_grant | No valid session, or the OAuth credentials were rejected. need_login means the token is missing or expired; invalid_grant means the login or refresh token was bad. | Authenticate at /oauth2/token, or refresh the access token. Verify the client_id, client_secret, username, and password. |
| 403 | not_authorized | The authenticated user's role or ACLs do not permit this action on this module or record. | Grant the needed access on the user's Sugar role, or authenticate as a user that has it. This is the main permission boundary. |
| 404 | not_found / no_method | The record or module does not exist or is not visible to this user (not_found), or the path does not map to a known endpoint (no_method). | Check the module name and record id, confirm the user can see the record, and verify the endpoint path and method. |
| 409 | edit_conflict | The record changed since it was read, so the update would overwrite newer data. | Re-read the record, re-apply the change, and retry, or send the expected modified date so the server can detect the conflict. |
| 412 | metadata_out_of_date | The client's cached metadata hash no longer matches the instance, often after a customization or upgrade. | Re-fetch the Metadata API and send the new X-Metadata-Hash on subsequent requests. |
| 413 | request_too_large | The request exceeded the instance's configured size limit. | Send fewer records, narrow the fields, or split the work, for example across smaller /bulk batches. |
| 422 | missing_parameter / invalid_parameter | A required parameter was absent (missing_parameter) or a supplied value was not valid (invalid_parameter). | Read the error_message, fix the parameters, and resend. The request is not retryable unchanged. |
| 500 | fatal_error | An unexpected error on the SugarCRM instance, returned as {"error": "fatal_error", "error_message": "..."}. | Retry with backoff, and check the instance logs or contact the instance administrator if it persists. |
| 503 | maintenance / service_unavailable | The instance is in maintenance or temporarily unavailable, for example during an upgrade. | Wait and retry with backoff once the instance is back online. |
SugarCRM versions its REST API with a major and minor number. The major number changes only for a breaking change, the minor number rises as endpoints are added, and an older version stays supported for at least a year after it is deprecated.
v11 is the current major version of the Sugar REST API. The major number changes only for a breaking change; the minor number (v11_1, v11_4, v11_8, on toward v11_24) rises as endpoints are added without breaking existing clients. A version is selected in the request path (/rest/v11/) or the HTTP Accept header, and a deprecated version stays supported for at least a year.
Sugar 9.0.0 introduced the v11_4 minor version, adding REST endpoints including a leancount on a related-records link, without breaking earlier v11 clients.
The Sugar 10.0 release (Q2 2020) shipped on the v11.8 REST API minor version, continuing additive changes within the v11 major line.
v10 is the prior major version, still reachable on instances that support it. v11 was added alongside v10 in Fall '17 so existing v10 dashboard clients kept working while new dashboard APIs landed in v11.
Pin the version in the request path or the Accept header, and move up deliberately.
SugarCRM REST API release notes ↗Bollard AI sits between a team's AI agents and SugarCRM. Grant each agent exactly the access it needs, read or write, module by module, and every call is checked and logged.