> ## Documentation Index > Fetch the complete documentation index at: https://docs.clientcommander.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Deal > Create a new deal in a pipeline. ## OpenAPI ````yaml POST /v1/deals openapi: 3.0.3 info: title: v1.0 description: > ## Authentication All API requests require authentication via API key in the `Authorization` header with Bearer scheme: ```bash curl -H "Authorization: Bearer your_api_key_here" https://api.clientcommander.com/v1/people ``` Generate API keys from **Settings > API Keys** in your Client Commander dashboard. ## Rate Limiting API requests are rate-limited to ensure system stability: - **Rate Limit:** 1000 requests per hour per API key - **Headers:** Every response includes rate limit information ``` X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1640995200 ``` When rate limit is exceeded, you'll receive a `429 Too Many Requests` response with a `Retry-After` header. ## Pagination List endpoints support pagination with consistent parameters: - `limit`: Number of items per page (default: 10, max: 100) - `cursor`: Opaque cursor for next page (returned in response) Response includes pagination metadata: ```json { "data": [...], "meta": { "count": 10, "hasMore": true, "nextCursor": "eyJpZCI6IjEyMyJ9" } } ``` ## Error Handling Errors follow a consistent structure with machine-readable codes: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Invalid email address", "details": [ { "field": "email", "message": "Must be a valid email address", "code": "INVALID_FORMAT" } ], "requestId": "req_abc123", "timestamp": "2023-11-15T10:00:00Z" } } ``` ## Idempotency POST and PUT requests support idempotency via the `Idempotency-Key` header: ```bash curl -X POST -H "Idempotency-Key: unique-key-123" ... ``` ## Versioning - **Current Version:** v1 - **Version Header:** `X-API-Version: 1` (optional) - **Deprecation Policy:** 12 months notice before sunset ## Support - **Documentation:** https://docs.clientcommander.com - **Status Page:** https://status.clientcommander.com - **Support:** support@clientcommander.me version: 1.0.0 contact: name: Client Commander API Support email: api@clientcommander.me url: https://clientcommander.com/support license: name: Proprietary url: https://clientcommander.com/terms servers: - url: https://api.clientcommander.com description: Production API variables: {} security: - Authentication: [] tags: - name: People description: > Contact management endpoints. Create, read, update, and delete contacts with rich profile data including emails, phones, addresses, custom fields, and lifecycle stages. **Permissions:** Requires `people.view.*` and `people.edit.*` scopes based on operation. - name: Tasks description: > Task management for contact follow-ups and to-dos. Supports due dates, priorities, and assignment to team members. **Permissions:** Requires `tasks.manage` scope. - name: Deals description: > Deal pipeline management with customizable stages. Track opportunities, revenue, and close dates. **Permissions:** Requires `deals.view.*` and `deals.manage` scopes. - name: Appointments description: > Calendar and appointment scheduling. Supports recurring appointments, timezones, and guest management. **Permissions:** Requires `appointments.manage` scope. - name: Activities description: > Activity logging and interaction history. Track calls, emails, meetings, and custom activities. **Permissions:** Requires `activities.view` and `activities.create` scopes. - name: Tags description: | Tag management for contact categorization and segmentation. **Permissions:** Requires `tags.manage` scope. - name: Stages description: | Contact lifecycle stage management (Lead, Prospect, Client, etc.). **Permissions:** Requires `stages.manage` scope (Owner/Admin only). - name: Pipelines description: | Deal pipeline configuration and stage management. **Permissions:** Requires `pipelines.manage` scope. - name: Users description: | User and agent information endpoints. **Permissions:** Requires `users.view` scope. - name: Teams description: | Team and member management. **Permissions:** Requires `teams.manage` scope. - name: Smart Lists description: | Dynamic contact segmentation with advanced filtering. **Permissions:** Requires `smartlists.manage` scope. paths: /v1/deals: post: tags: - Deals summary: Create deal description: Create a new deal in a pipeline. operationId: createDeal requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DealInput' examples: createDeal: summary: Create new deal value: title: 123 Main St - Purchase pipelineId: k97pipe123 stageId: k97stage456 peopleIds: - jd79person123 pricing: 450000 closeDate: '2023-12-31T00:00:00Z' responses: '201': description: Deal created content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessResponse' - type: object properties: data: type: object properties: id: type: string '422': $ref: '#/components/responses/ValidationError' security: - Authentication: - deals.manage components: schemas: DealInput: type: object required: - title - pipelineId properties: title: type: string minLength: 1 maxLength: 200 pipelineId: type: string stageId: type: string peopleIds: type: array items: type: string teamIds: type: array items: type: string pricing: type: number format: double description: Deal value (maps to 'price' internally) commission: type: number format: double closeDate: type: string format: date-time SuccessResponse: type: object required: - meta properties: meta: type: object required: - requestId - timestamp properties: requestId: type: string format: uuid description: Unique request ID for tracing timestamp: type: string format: date-time description: Response timestamp version: type: string default: 1.0.0 ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code enum: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - VALIDATION_ERROR - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - BAD_REQUEST - CONFLICT example: VALIDATION_ERROR message: type: string description: Human-readable error message example: Invalid email address format details: type: array description: Field-level validation errors items: type: object properties: field: type: string example: email message: type: string example: Must be a valid email address code: type: string example: INVALID_FORMAT requestId: type: string format: uuid description: Request ID for support timestamp: type: string format: date-time retryAfter: type: integer description: Seconds to wait before retry (for rate limits) responses: ValidationError: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: value: error: code: VALIDATION_ERROR message: Validation failed details: - field: email message: Must be a valid email address code: INVALID_FORMAT - field: phone message: Phone number is required code: REQUIRED_FIELD requestId: 123e4567-e89b-12d3-a456-426614174000 timestamp: '2023-11-15T10:00:00Z' securitySchemes: Authentication: type: http scheme: bearer bearerFormat: API Key description: | API key for authentication using Bearer token scheme. **How to get your API key:** 1. Log into Client Commander 2. Go to **Admin > API Keys** 3. Click **Create API Key** 4. Copy the key and use it in the Authorization header: ``` Authorization: Bearer ccmd_live_your_key_here ``` ````