Skip to main content

​
Use bulk operations

For operations on multiple records, prefer bulk endpoints over individual calls: 
# Instead of deleting one by one
curl -X POST "https://api.socrateslabs.io/api/contacts/bulk-delete" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["id1", "id2", "id3"]}'

​
Paginate efficiently

When fetching all records, use the maximum page_size of 100 to reduce the number of API calls: 
params = {"page": 1, "page_size": 100}
Check total_pages in the response to know when to stop.

​
Handle soft deletes

Most delete operations are soft deletes. Deleted records won’t appear in list results but the data is retained for recovery. Keep this in mind when building sync integrations.

​
Use filters on list endpoints

Most list endpoints support filtering to reduce response size: 
# Filter contacts by company
curl "https://api.socrateslabs.io/api/contacts?company_id=uuid" \
  -H "X-API-Key: sk_your_api_key_here"

​
Implement error handling

Always handle common error cases:
  • 401: Refresh or check your API key
  • 404: The resource may have been deleted
  • 422: Validate your request body before sending
  • 429: Implement exponential backoff (see Rate Limiting)
For finding records by meaning rather than exact text, use the Cortex Search endpoints: 
curl -X POST "https://api.socrateslabs.io/api/cortex/search" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "enterprise customers in California"}'

​
Content types

  • All request bodies must be application/json unless uploading files
  • File uploads use multipart/form-data
  • All responses are application/json unless downloading files