Making Your First API Call

This guide will walk you through the essential steps to authenticate and successfully make a first API call.

---

Prerequisites

Before you begin, ensure you have:

• Application Created: Registered in the Trimble Cloud Console
• Product Subscription: Your application must be subscribed to at least one API Product
• Credentials: Your Application Client ID and Client Secret
• Scopes: Know your API Scopes

---

Step 1: Get an Access Token

Trimble uses OAuth 2.0 for security. You must exchange your credentials for a temporary Access Token.

1.1 Prepare Your Credentials

Take your Client ID and Client Secret and combine them in the format:

client_id:client_secret

---

1.2 Encode to Base64

Encode the combined string into Base64.

Example:

my_client_id:my_client_secret
→ bXlfY2xpZW50X2lkOm15X2NsaWVudF9zZWNyZXQ=

---

1.3 Send the Request

Send a POST request to the identity endpoint. Include your encoded string in the Authorization header using the Basic prefix.

Endpoint

• Prod: POST https://id.trimble.com/oauth/token
• Stage: POST https://stage.id.trimblecloud.com/oauth/token

Headers

Authorization: Basic [YOUR_BASE64_ENCODED_STRING]
Content-Type: application/x-www-form-urlencoded

Request Body

grant_type=client_credentials&scope=YOUR_API_SCOPES

---

How to Get the API Scope from Trimble Cloud Console

1. Log into Console
2. Navigate to your subscribed Product
3. Select the API Version in the Product
4. Locate Scopes in the bottom section

💡 Success Tip: The response will include an access_token, typically valid for 3600 seconds (1 hour).

---

Step 2: Choose Your API Endpoint

Before making a call, identify the correct URL and resource.

2.1 Navigate to Your Subscribed Product

• Go to your application’s Subscriptions
• Click on the specific API Product

---

2.2 APIs and Versioning

• Products may contain multiple API versions (e.g., v1, v2)
• Ensure you select the correct version

Example:

https://cloud.api.trimble.com/field-service/v1/jobs

---

2.3 Explore the OpenAPI Specification (OAS)

• Access via the Specification tab

• Includes:

  • Available endpoints (GET, POST, etc.)
  • Required parameters
  • Response schemas

• Can be downloaded as JSON/YAML for tools like Postman

---

Endpoint Structure

Most Trimble APIs follow:

https://cloud.api.trimble.com/product-name/v1/resource

Example (List Users):

GET https://cloud.api.trimble.com/admin/v1/users

---

Step 3: Execute the Call

Use Postman, cURL, or your preferred language. Include the access token in the Authorization header.

Example cURL Request

curl --request GET 'https://cloud.api.trimble.com/admin/v1/users' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json'

---

Step 4: Understand the Response

A successful response returns:

• HTTP Status: 200 OK
• Payload: JSON

Example Response

{
  "status": "success",
  "data": [
    {
      "id": "12345",
      "name": "Sample User"
    }
  ],
  "uniqueId": "987654321"
}

---

Common Error Codes

Status Code	Meaning
401 Unauthorized	Access Token is expired or incorrect
403 Forbidden	Not subscribed to API Product or invalid audience
404 Not Found	Incorrect endpoint URL

---