Mastering the SuiteCRM V8 API with Postman: A Step-by-Step Guide

The SuiteCRM V8 API introduces a modern and secure way to interact with SuiteCRM using RESTful principles. In this tutorial, we’ll walk through setting up the V8 API, obtaining access tokens with Postman, and performing core operations like retrieving, adding, and updating leads.

How the V8 API Works

At its core, the SuiteCRM V8 API follows these steps:

1. Create an API Key: Generate an OAuth2 client in SuiteCRM to define your app’s credentials.
2. Authenticate and Retrieve Tokens: Use the client_id, client_secret, username, and password to obtain an access_token and a refresh_token.
3. Use the Access Token: Include the access_token in your API requests to authenticate and interact with SuiteCRM.
4. Refresh Tokens: When the access_token expires, use the refresh_token to get a new one without logging in again.

This article will guide you through:

• Setting up the API and generating tokens.
• Using Postman to perform essential operations, including retrieving, creating, and updating records in SuiteCRM.
  • Get a list of leads.
  • Retrieve a specific lead by ID.
  • Retrieve a specific lead by phone number.
  • Add a new lead.
  • Update an existing lead.

By the end of this guide, you’ll be equipped to leverage SuiteCRM’s V8 API to streamline your workflows and integrate with other systems.

Setting Up the SuiteCRM V8 API

Before you start… IMPORTANT….. if this is your first time using the V8 API, you must create the encryption keys in the setup guide:

https://docs.suitecrm.com/developer/api/developer-setup-guide/json-api/#_generate_private_and_public_key_for_oauth2

Before you can use the V8 API, you need to configure your SuiteCRM instance:

Step 1: Enable the API

1. Log into SuiteCRM as an admin.
2. Navigate to Admin > OAuth2 Clients & Tokens.
3. Click Create OAuth2 Client and fill out the form:
   • Client Name: YourAppName
   • Client Type: password
   • Client ID: A unique identifier (e.g., yourapp-id).
   • Client Secret: A secure string (e.g., yourapp-secret).
4. Save the OAuth2 Client.

Step 2: Verify API Availability

1. Ensure the /Api endpoint is accessible. For example:

https://yourdomain.com/Api/access_token

You should get a vaild URL but method not allowed.

Note: For SuiteCRM 8 you may have to construct the URL like

…/legacy/Api/access_token

ALL URL’s in this blog are for V7 SutieCRM, so if you are using V8.x SuiteCRM you must use /legacy/ in your URL unless you have setup an .htaccess redirect that fixes that problem.

OR ensure that you have a proper .htaccess rule that forwards the legacy to public.

2. Test the endpoint in your browser. If you encounter issues, verify your .htaccess configuration to ensure proper URL rewriting.

Getting the Access Token

To interact with the API, you first need an access token. Here’s how to retrieve it with Postman:

Step 1: Create a New Request

1. Open Postman and create a new request.
2. Set the method to POST and the URL to:

https://yourdomain.com/Api/access_token

Step 2: Configure the Request

1. In the Headers tab, set:

Content-Type: application/json

2. Set x-www-form-urlencoded and in the Body tab, select raw and enter:

{
  "grant_type": "client_credentials",
  "client_id": "yourapp-id",
  "client_secret": "yourapp-secret"  
}

Step 3: Send the Request

1. Click Send.
2. If successful, you’ll receive a response containing the access_token and refresh_token.

Using the Access Token

With the access token in hand, you can now perform API operations. For each request, include the token in the Authorization header like so:

Authorization: Bearer {access_token}

Performing API Operations

Example #1: Getting a List of Leads

Retrieve a paginated list of leads.

Request Details:

• Method: GET
• URL

https://yourdomain.com/Api/V8/module/Leads

Again note, for SuiteCRM 8.x you must put /legacy/ in the URL

• Headers:

Authorization: Bearer {access_token}

Response: The API returns a list of leads in JSON format:

{
  "data": [
    {
      "id": "lead-id-1",
      "type": "Leads",
      "attributes": {
        "first_name": "John",
        "last_name": "Doe",
        "email1": "john.doe@example.com"
      }
    }
  ]
}

Example #2: Get a Specific Lead

Retrieve details for a single lead by ID.

Request Details:

• Method: GET
• URL:

https://yourdomain.com/Api/V8/module/Leads/{lead-id}

• Headers

Authorization: Bearer {access_token}

Response:

{
  "data": {
    "id": "lead-id",
    "type": "Leads",
    "attributes": {
      "first_name": "John",
      "last_name": "Doe",
      "email1": "john.doe@example.com"
    }
  }
}

Example #3: Add a New Lead

Create a new lead in SuiteCRM.

Request Details:

• Method: POST
• URL:

https://yourdomain.com/Api/V8/module

• Headers:

Authorization: Bearer {access_token}

• Body (raw):

{
  "data": {
    "type": "Leads",
    "attributes": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email1": "jane.doe@example.com",
      "phone_work": "123-456-7890",
      "description": "New lead created via API."
    }
  }
}

Response: The API returns the ID of the new lead:

{
  "data": {
    "id": "new-lead-id",
    "type": "Leads"
  }
}

Example #4 Update an Existing Lead

Update details for an existing lead.

Request Details:

• Method: PATCH
• URL:

https://yourdomain.com/Api/V8/module

• Headers

Authorization: Bearer {access_token}

• Body

{
  "data": {
    "type": "Leads",
    "id": "lead-id",
    "attributes": {
      "phone_work": "987-654-3210",
      "description": "Updated lead details via API."
    }
  }
}

Response: The API confirms the update:

{
  "data": {
    "id": "lead-id",
    "type": "Leads",
    "attributes": {
      "phone_work": "987-654-3210",
      "description": "Updated lead details via API."
    }
  }
}

Example #5: Retrieving a Specific Lead by Phone Number

To look up a lead by phone number, we’ll use the filter parameter in our API request.

API Request

• Method: GET
• URL:

https://your-suitecrm-instance/Api/V8/module/Leads?filter[phone_work][eq]=123-123-1234

• Headers

Authorization: Bearer {{access_token}}
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Expected Response:

{
  "data": [
    {
      "type": "Leads",
      "id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
      "attributes": {
        "first_name": "John",
        "last_name": "Doe",
        "phone_work": "123-123-1234",
        "email1": "johndoe@example.com",
        "status": "New"
      }
    }
  ]
}

If a match is found, you’ll get a JSON response containing the lead’s details. Otherwise, you’ll receive an empty data array.

This method allows you to efficiently find a lead by phone number, which is particularly useful when integrating with telephony systems or call tracking tools.

Reference Table of Endpoints

Conclusion

The SuiteCRM V8 API offers a robust way to interact with your CRM, enabling powerful integrations and customizations for SutieCRM Developement. In this guide, you’ve learned how to:

• Configure the V8 API for your SuiteCRM instance.
• Use Postman to authenticate and perform API requests.
• Manage leads through the API with real-world examples.

If you’re looking for help integrating SuiteCRM into your workflows or building custom solutions, contact me for expert SuiteCRM development and consulting.

Stay tuned for the next part of this series, where we’ll explore the SuiteCRM GraphQL API for even more possibilities!

What’s your experience with SuiteCRM’s APIs? Share your thoughts in the comments below.