Salesforce

Salesforce

Access the Salesforce REST API with managed OAuth authentication. Query records using SOQL, manage sObjects, and perform CRUD operations on your Salesforce data.

Quick Start

CLI:

maton salesforce query 'SELECT Id,Name FROM Contact LIMIT 10'

maton api '/salesforce/services/data/v63.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+10'

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/salesforce/services/data/v63.0/query?q=SELECT+Id,Name,Email+FROM+Contact+LIMIT+10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://api.maton.ai/salesforce/{endpoint-path}

The gateway proxies requests to {instance}.salesforce.com (automatically replaced with your connection config) and injects your access token. Only the endpoints documented in the API Reference section below are supported — always use specific endpoint paths from that section rather than constructing arbitrary paths.

Installation

NPM:

npm install -g @maton/cli

Homebrew:

brew install maton-ai/cli/maton

Authentication

CLI:

maton login                          # Opens browser for API key
maton login --interactive            # Skip browser, paste API key directly
maton whoami                         # Show current auth state

Manual:

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key
4. Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Connection Management

Manage your Salesforce OAuth connections at https://api.maton.ai.

List Connections

CLI:

maton connection list salesforce --status ACTIVE

maton api -X GET /connections -f app=salesforce -f status=ACTIVE

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=salesforce&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

CLI:

maton connection create salesforce

maton api /connections -f app=salesforce

Python:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'salesforce'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

CLI:

maton connection view {connection_id}

maton api /connections/{connection_id}

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "salesforce",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

CLI:

maton connection delete {connection_id}

maton api -X DELETE /connections/{connection_id}

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Salesforce connections, specify which one to use:

CLI:

maton salesforce query 'SELECT Id,Name FROM Contact LIMIT 10' --connection {connection_id}

maton api /salesforce/services/data/v63.0/sobjects --connection {connection_id}

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/salesforce/services/data/v63.0/sobjects')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If you have multiple connections, always specify the connection to ensure requests go to the intended account.

Security & Permissions

• IMPORTANT: Treat MATON_API_KEY as a secret — do not log it, include it in chats or prompts visible to others, or expose it in shared files or outputs. The key authenticates with Maton, and the Salesforce connection is independently scoped via OAuth. Use the narrowest Salesforce permissions available, rotate the key if exposed at maton.ai/settings, and revoke unused connections promptly.
• Access is scoped to the Salesforce resources permitted by the connected account's OAuth scopes. Only install if you need Salesforce CRM administration. Prefer sandbox orgs for destructive or batch testing.
• Default to read-only operations. Always start with SOQL queries or GET requests to confirm record IDs and field values before proposing any changes.
• All write operations require explicit user approval with specific details. Before executing any POST, PATCH, DELETE, or composite/batch call:
  1. Retrieve and display the target resource (sObject type, record ID, record name) so the user can verify.
  2. Clearly describe the intended effect (e.g., "This will delete Opportunity 'Acme Deal' (ID: 006xx) — this cannot be undone").
  3. Wait for explicit user confirmation before proceeding.
• Batch and composite operations require extra caution. These can modify multiple records in a single call. List every affected record and confirm before execution.

API Reference

SOQL Query

GET /salesforce/services/data/v63.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+10

Example:

maton salesforce query 'SELECT Id,Name FROM Contact LIMIT 10'

Complex query:

GET /salesforce/services/data/v63.0/query?q=SELECT+Id,Name,Email+FROM+Contact+WHERE+Email+LIKE+'%25example.com'+ORDER+BY+CreatedDate+DESC

Example:

maton salesforce query "SELECT Id,Name,Email FROM Contact WHERE Email LIKE '%example.com' ORDER BY CreatedDate DESC"

Get Object

GET /salesforce/services/data/v63.0/sobjects/Contact/0035g00000XYZ

Example:

maton salesforce record view 0035g00000XYZ --type Contact

Create Object

POST /salesforce/services/data/v63.0/sobjects/Contact
Content-Type: application/json

{
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "[email protected]"
}

Example:

maton salesforce record create --type Contact --data '{"FirstName":"John","LastName":"Doe","Email":"[email protected]"}'

Update Object

PATCH /salesforce/services/data/v63.0/sobjects/Contact/0035g00000XYZ
Content-Type: application/json

{
  "Phone": "+1234567890"
}

Example:

maton salesforce record update 0035g00000XYZ --type Contact --data '{"Phone":"+1234567890"}'

Delete Object

DELETE /salesforce/services/data/v63.0/sobjects/Contact/0035g00000XYZ

Example:

maton salesforce record delete 0035g00000XYZ --type Contact

Describe Object (get schema)

GET /salesforce/services/data/v63.0/sobjects/Contact/describe

Example:

maton salesforce object describe Contact

List Objects

GET /salesforce/services/data/v63.0/sobjects

Example:

maton salesforce object list

Search (SOSL)

GET /salesforce/services/data/v63.0/search?q=FIND+{John}+IN+ALL+FIELDS+RETURNING+Contact(Id,Name)

Example:

maton salesforce search 'FIND {John} IN ALL FIELDS RETURNING Contact(Id,Name)'

Get API Limits

GET /salesforce/services/data/v63.0/limits

Example:

maton salesforce limit view

Get Current User

Example:

maton salesforce whoami

Composite Request (batch multiple operations)

POST /salesforce/services/data/v63.0/composite
Content-Type: application/json

{
  "compositeRequest": [
    {
      "method": "GET",
      "url": "/services/data/v63.0/sobjects/Contact/003XXXXXXX",
      "referenceId": "contact1"
    },
    {
      "method": "GET",
      "url": "/services/data/v63.0/sobjects/Account/001XXXXXXX",
      "referenceId": "account1"
    }
  ]
}

Example:

echo '{"compositeRequest":[{"method":"GET","url":"/services/data/v63.0/sobjects/Contact/003XXXXXXX","referenceId":"contact1"},{"method":"GET","url":"/services/data/v63.0/sobjects/Account/001XXXXXXX","referenceId":"account1"}]}' \
  | maton salesforce composite call -F -

Composite Batch Request

POST /salesforce/services/data/v63.0/composite/batch
Content-Type: application/json

{
  "batchRequests": [
    {"method": "GET", "url": "v63.0/sobjects/Contact/003XXXXXXX"},
    {"method": "GET", "url": "v63.0/sobjects/Account/001XXXXXXX"}
  ]
}

Example:

echo '{"batchRequests":[{"method":"GET","url":"v63.0/sobjects/Contact/003XXXXXXX"},{"method":"GET","url":"v63.0/sobjects/Account/001XXXXXXX"}]}' \
  | maton salesforce composite batch -F -

sObject Collections Create (batch create)

POST /salesforce/services/data/v63.0/composite/sobjects
Content-Type: application/json

{
  "allOrNone": true,
  "records": [
    {"attributes": {"type": "Contact"}, "FirstName": "John", "LastName": "Doe"},
    {"attributes": {"type": "Contact"}, "FirstName": "Jane", "LastName": "Smith"}
  ]
}

Example:

maton salesforce record create --all-or-none --data '[{"attributes":{"type":"Contact"},"FirstName":"John","LastName":"Doe"},{"attributes":{"type":"Contact"},"FirstName":"Jane","LastName":"Smith"}]'

sObject Collections Delete (batch delete)

DELETE /salesforce/services/data/v63.0/composite/sobjects?ids=003XXXXX,003YYYYY&allOrNone=true

Example:

maton salesforce record delete 003XXXXX 003YYYYY --all-or-none

Get Updated Records

GET /salesforce/services/data/v63.0/sobjects/Contact/updated/?start=2026-04-30T00:00:00Z&end=2026-05-05T00:00:00Z

Example:

maton salesforce record list --type Contact --start 2026-04-30T00:00:00Z --end 2026-05-05T00:00:00Z

Get Deleted Records

GET /salesforce/services/data/v63.0/sobjects/Contact/deleted/?start=2026-04-30T00:00:00Z&end=2026-05-05T00:00:00Z

Example:

maton salesforce record list --type Contact --start 2026-04-30T00:00:00Z --end 2026-05-05T00:00:00Z --changes deleted

List API Versions

GET /salesforce/services/data/

Example:

maton salesforce version list

Common Objects

• Account - Companies/Organizations
• Contact - People associated with accounts
• Lead - Potential customers
• Opportunity - Sales deals
• Case - Support cases
• Task - To-do items
• Event - Calendar events

Pagination

Salesforce uses cursor-based pagination. The CLI automatically paginates with '--paginate'.

Example:

maton salesforce query 'SELECT Id,Name FROM Contact' --paginate

Code Examples

CLI

# Query contacts
maton salesforce query 'SELECT Id,Name FROM Contact LIMIT 10'

# View a specific record
maton salesforce record view 0035g00000XYZ --type Contact

# Create a new contact
maton salesforce record create --type Contact --data '{"FirstName":"John","LastName":"Doe"}'

# Describe an object schema
maton salesforce object describe Contact

# Check authenticated user
maton salesforce whoami

# Check API limits
maton salesforce limit view

JavaScript

const response = await fetch(
  'https://api.maton.ai/salesforce/services/data/v63.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+5',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://api.maton.ai/salesforce/services/data/v63.0/query',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'q': 'SELECT Id,Name FROM Contact LIMIT 5'}
)

Notes

• Use URL encoding for SOQL queries (spaces become +)
• Record IDs are 15 or 18 character alphanumeric strings
• API version (v63.0) can be adjusted; latest is v65.0
• Update and Delete operations return HTTP 204 (no content) on success
• Dates for updated/deleted queries use ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
• Use allOrNone: true in batch operations for atomic transactions
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsing
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.

Error Handling

Troubleshooting: API Key Issues

CLI:

1. Check your auth state:

maton whoami

1. Verify the API key is valid by listing connections:

maton connection list

Manual:

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

1. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with salesforce. For example:

• Correct: https://api.maton.ai/salesforce/services/data/v63.0/query
• Incorrect: https://api.maton.ai/services/data/v63.0/query

Resources

• REST API Developer Guide
• List sObjects
• Describe sObject
• Get Record
• Create Record
• Update Record
• Delete Record
• Query Records (SOQL)
• Composite Request
• sObject Collections
• SOQL Reference
• SOSL Reference
• Maton CLI Manual
• Maton Community
• Maton Support