> ## Documentation Index
> Fetch the complete documentation index at: https://docs.morphic.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Tips for building robust integrations with the Morphic API.

## Use bulk operations

For operations on multiple records, prefer bulk endpoints over individual calls:

```bash theme={null}
# 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:

```python theme={null}
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:

```bash theme={null}
# 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](/rate-limiting))

## Use semantic search

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

```bash theme={null}
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