Best Practices

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.morphic.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.morphic.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)

Use semantic search

For finding records by meaning rather than exact text, use the Cortex Search endpoints:

curl -X POST "https://api.morphic.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

Getting Started

Core Concepts

Changelog

Use bulk operations

Paginate efficiently

Handle soft deletes

Use filters on list endpoints

Implement error handling

Use semantic search

Content types

​Use bulk operations

​Paginate efficiently

​Handle soft deletes

​Use filters on list endpoints

​Implement error handling

​Use semantic search

​Content types

Use bulk operations

Paginate efficiently

Handle soft deletes

Use filters on list endpoints

Implement error handling

Use semantic search

Content types