# Welcome to iClosed.io

The iClosed.io API gives you programmatic access to contacts, calls, deals, transactions, events, and custom fields — everything you need to build sales automation, sync with your CRM, or extend the iClosed platform. The API is REST-based, returns JSON, and authenticates via a Bearer API key.

> **OpenAPI spec:** Download the full spec at [`https://api-docs-iclosed.redocly.app/_bundle/openapi/v1/openapi.yaml`](https://api-docs-iclosed.redocly.app/_bundle/openapi/v1/openapi.yaml)


## Base URLs

| Environment | Base URL |
|  --- | --- |
| Production | `https://public.api.iclosed.io` |
| Development | `https://public-dev.api.iclosed.io` |


> **Development environment:** Uses a separate data store — data created here never appears in production. API keys created in the dev app work only against the dev base URL.


## Quick Start

Make your first API call in three steps.

**1. Set your API key**


```bash
export ICLOSED_API_KEY=iclosed_YOUR_API_KEY
```

**2. Fetch your calls**


```bash
curl "https://public.api.iclosed.io/v1/eventCalls?eventType=UPCOMING&limit=5" \
  -H "Authorization: Bearer $ICLOSED_API_KEY"
```

**3. Create a contact**


```bash
curl -X POST https://public.api.iclosed.io/v1/contacts \
  -H "Authorization: Bearer $ICLOSED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName": "Jane", "lastName": "Doe", "email": "jane@example.com"}'
```

## Authentication

All requests require a valid API key in the `Authorization` header:


```
Authorization: Bearer iclosed_<your-api-key>
```

Both `Bearer` (with a space) and the `iclosed_` prefix are required. See [Authentication](/docs/authentication) for full details.

## Rate Limiting

Default: **20 requests per second per endpoint** per account. Exceeding this returns `429 Too Many Requests` with a JSON body:


```json
{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests, please try again later.",
  "retryAfter": 3,
  "limit": { "points": 20, "windowSec": 1 }
}
```

Read `retryAfter` and wait that many seconds before retrying. See [Rate Limiting](/docs/rate-limiting).

## Error Handling

The API uses standard HTTP status codes. Every error includes a JSON body.

| Code | Meaning |
|  --- | --- |
| `200` | Success |
| `201` | Created |
| `400` | Bad request — see `message.details.fieldErrors` for per-field validation errors |
| `401` | Unauthorized — missing or invalid API key |
| `403` | Forbidden — key lacks permission |
| `404` | Not found — resource or endpoint does not exist |
| `429` | Too many requests — rate limit exceeded |
| `5xx` | Server error — retry with backoff |


See [Errors](/docs/errors) for the full catalog including application-level error codes.

## API Versioning

The current version is **v1**. All endpoint paths are prefixed `/v1/`. Non-breaking additions (new fields, new endpoints) are made without a version bump. Breaking changes are released as `/v2/` with at least 60 days of overlap. See [Changelog](/docs/changelog).

## Quick Reference: All Endpoints

| Path | Method | Description |
|  --- | --- | --- |
| `POST /v1/contacts` | POST | Create or upsert a contact |
| `PUT /v1/contacts` | PUT | Update a contact |
| `POST /v1/contacts/delete` | POST | Delete contact(s) |
| `POST /v1/contacts/createContactNote` | POST | Add a note to a contact |
| `GET /v1/deals` | GET | List or get deals |
| `POST /v1/deals` | POST | Create a deal |
| `PUT /v1/deals` | PUT | Update a deal |
| `POST /v1/deals/delete` | POST | Delete deal(s) |
| `GET /v1/transactions` | GET | List or get transactions |
| `POST /v1/transactions` | POST | Create a transaction |
| `PUT /v1/transactions` | PUT | Update a transaction |
| `DELETE /v1/transactions` | DELETE | Delete a transaction |
| `GET /v1/events/timeSlots` | GET | Get event time slots |
| `POST /v1/events/eventDates` | POST | Get available booking dates |
| `PUT /v1/events/status` | PUT | Update event status |
| `POST /v1/eventCalls` | POST | Create (book) an event call |
| `GET /v1/eventCalls` | GET | Search / list event calls |
| `PUT /v1/eventCalls/reschedule` | PUT | Reschedule a call |
| `PUT /v1/eventCalls/cancel` | PUT | Cancel a call |
| `POST /v1/fields/inviteeAnswers` | POST | Insert invitee answers |
| `GET /v1/fields/objects` | GET | Get custom fields by object type |
| `POST /v1/outcomes` | POST | Add or update a call outcome |
| `GET /v1/users` | GET | Search users |
| `POST /v1/setterClaims/assignOwner` | POST | Assign setter owner |


For full request/response schemas see the [API Reference](https://api-docs-iclosed.redocly.app/openapi/v1/openapi) or download the [OpenAPI YAML](https://api-docs-iclosed.redocly.app/_bundle/openapi/v1/openapi.yaml).

## Next Steps

1. [Create an API key](https://app.iclosed.io) in your account settings
2. Read [Authentication](/docs/authentication) for security best practices
3. Follow the [Event Call Booking guide](/docs/guides/event-call-booking) for an end-to-end walkthrough
4. Explore [Webhooks](/docs/webhooks/introduction) for real-time event notifications
5. Connect the [iClosed MCP server](https://api-docs-iclosed.redocly.app/docs/mcp/introduction) to use API docs directly from your AI assistant


## Documentation Index

| Page | Description |
|  --- | --- |
| [Authentication](/docs/authentication) | API keys, header format, security |
| [Rate Limiting](/docs/rate-limiting) | Limits, response headers, backoff |
| [Errors](/docs/errors) | HTTP codes and app-level error strings |
| [Guides Introduction](/docs/guides/introduction) | All integration walkthroughs |
| [Event Call Booking Guide](/docs/guides/event-call-booking) | End-to-end booking walkthrough |
| [Webhooks](/docs/webhooks/introduction) | Real-time event notifications |
| [Data Models](/docs/api-reference) | Contact, Call, Deal, Transaction, Event schemas |
| [Pagination](/docs/pagination) | Paginating list endpoints |
| [Changelog](/docs/changelog) | API version history |
| [Glossary](/docs/glossary) | iClosed-specific terms |


## Support

- App: [https://app.iclosed.io](https://app.iclosed.io)
- Support: [https://app.iclosed.io/support](https://app.iclosed.io/support)
- API Reference: [https://api-docs-iclosed.redocly.app/openapi/v1/openapi](https://api-docs-iclosed.redocly.app/openapi/v1/openapi)