What we do
Tools
Industries
Department
How we workLet's talk →
Home/SugarCRM/The SugarCRM API From the First Token Request
SugarCRM

SugarCRM API Integrations Break at Login, Token Refresh and Paging. Start There.

The script that logs in to Sugar works on day one. A week later someone signs into Sugar as the same user and the script's session dies, because both are on the default platform. Sugar's REST API reaches standard records, Studio custom modules and their relationships, and most of its traps sit in the login request.

The first SugarCRM API request

Get a token: POST to /rest/v{version}/oauth2/token with grant_type password, client_id sugar, the username and password, and your own platform name.

Use it: send the access token in the OAuth-Token header on each call, such as a POST to /rest/v{version}/Accounts/filter.

Renew it: access tokens last 3,600 seconds and refresh tokens 1,209,600 (14 days). Swap the refresh token with grant_type refresh_token, and store that instead of the password.

List the endpoints: /rest/v{version}/help on your own instance documents every versioned endpoint it serves.

Sugar's v10+ REST API beside the legacy v4_1 web services

Build new work here

REST API, v10 and later

  • Two-legged OAuth2 with access and refresh tokens.
  • Versioned paths under /rest/v{version}/, up to v11.24 in the Sugar 14 docs.
  • Studio custom modules, fields and relationships reachable like standard ones.
  • A filter endpoint with $and, $or, $starts and $contains expressions.
Older installs

Legacy API, v1 to v4_1

  • Listed separately in Sugar's developer guide as the Legacy API.
  • Used by integrations written years ago, often on self-hosted Sugar, in SOAP or REST form.
  • Session-based login rather than OAuth2 tokens.
  • Example code online is often written against it, which confuses new builds.

Write anything new against the v10+ API. Before a Sugar upgrade, list which of your integrations still call the legacy one.

Sugar API integrations that pass testing, then fail in production

Left on the default platform

How you'll know: A real user, or the integration, gets logged out without warning.

Fix: The platform parameter defaults to base, which clashes with people using Sugar. Create a custom platform through Configure API Platforms in Admin, or a Platform extension, and send that name.

No refresh flow

How you'll know: Calls start failing about an hour after the job starts.

Fix: Access tokens expire after 3,600 seconds. Request a new one with the refresh token before it lapses, and log in again only when the refresh token has expired too.

Only 20 records come back

How you'll know: A sync of 4,000 accounts copies 20 and reports success.

Fix: The filter endpoint returns 20 by default. Set max_num, then keep calling with the next_offset it returns until it comes back as -1.

Matched on labels, not field names

How you'll know: Values land in the wrong field after someone renames a label in Studio.

Fix: Map by the field's internal name. Studio custom fields carry a _c suffix, and the label a user sees can change at any time.

SugarCRM API questions from the first build

Does SugarCRM have a REST API?

Yes. Current Sugar versions expose a REST API at /rest/v{version}/ that covers standard modules and anything built in Studio, with two-legged OAuth2 for authentication.

Is there an older SOAP API for SugarCRM?

Yes. Sugar's developer guide lists the v1 to v4_1 web services separately as the Legacy API, and older, especially self-hosted, integrations were often written against them in SOAP form. Check which one an existing integration calls before you change anything around it.

Can the Sugar API access custom modules built in Studio?

Yes. Custom modules, fields and relationships from Studio are reachable the same way as standard ones. Custom fields carry a _c suffix in their internal names, which is what the API expects.

Do I need a developer to build on the SugarCRM API?

For anything past a test request, yes. The requests are simple; the work is in a custom platform, token refresh, paging and field mapping, and in handling whatever request limits your instance applies. n-frames writes those integrations.

How long does a SugarCRM access token last?

3,600 seconds, or one hour. The refresh token lasts 1,209,600 seconds, which is 14 days, so a job that runs daily can keep renewing without storing a password.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.