> ## Documentation Index > Fetch the complete documentation index at: https://docs.api.aura-app.ai/llms.txt > Use this file to discover all available pages before exploring further. # List opportunities > Retrieve a paginated list of opportunities (deals) for your organization, newest first. Each opportunity is a booking call viewed as a deal, joined to its lead and any linked sale. The `stage` field is derived at read time from the lead's full call history using the same rules as the dashboard pipeline: 1. **disqualified** — latest form/intent disqualification (overridden by newer booking activity) 2. **booked / confirmed** — active future booking (confirmed when the guest accepted) 3. Most recent past outcome — **won / unfit / lost / cancelled / declined / attended / no_show / follow_up** 4. **qualified / interested** — qualification signals without a booking 5. Stored lead status fallback **Use Cases:** - Sync deals into an external CRM or reporting warehouse - Track pipeline movement without polling individual leads - Reconcile expected vs actual deal value **Filtering:** - Filter by derived stage, lead, or scheduled date range - Stage filtering is applied per page (see the `stage` parameter) - Most interested, qualified and disqualified leads have not booked a call, so they have no opportunity. List them with `GET /v1/leads?stage=`. Retrieve a paginated list of opportunities (deals) for your organization, newest first. Each opportunity is a booking call viewed as a deal, joined to its lead and any linked sale. The `stage` field is derived at read time from the lead's full call history using the same rules as the dashboard pipeline: 1. **disqualified** — latest form/intent disqualification (overridden by newer booking activity) 2. **booked / confirmed** — active future booking (confirmed when the guest accepted) 3. Most recent past outcome — **won / unfit / lost / cancelled / declined / attended / no\_show / follow\_up** 4. **qualified / interested** — qualification signals without a booking 5. Stored lead status fallback **Use Cases:** * Sync deals into an external CRM or reporting warehouse * Track pipeline movement without polling individual leads * Reconcile expected vs actual deal value **Filtering:** * Filter by derived stage, lead, or scheduled date range * Stage filtering is applied per page (see the `stage` parameter) * Most interested, qualified and disqualified leads have not booked a call, so they have no opportunity. List them with `GET /v1/leads?stage=`. ## OpenAPI ````yaml openapi.json GET /v1/opportunities openapi: 3.1.0 info: contact: email: support@aura-app.ai name: Aura Support description: >- # Aura Partner Integrations API > **Alpha Release** - This API is under active development. Endpoints, request/response schemas, and behaviors may change without prior notice. We recommend pinning to specific response fields you need and handling unknown fields gracefully. Enterprise REST API for external partner integrations including commission platforms, external mobile apps, and client booking widgets. ## MCP Connector Aura also exposes a **Model Context Protocol** server at `/mcp` so AI assistants (Claude, ChatGPT) can answer questions about a user's own sales data. If you are building an assistant integration rather than a server-to-server one, that is almost certainly the surface you want — it is task-shaped ("prep me for my next call") rather than resource-shaped, and it handles auth per-user. Read-only. OAuth 2.1 + PKCE, with Clerk as the authorization server; discover it from `/.well-known/oauth-protected-resource`. Setup guide: https://docs.api.aura-app.ai/mcp-connector ## Authentication Authenticated endpoints support two authentication methods: **1. API Key (for partners and integrations):** ``` Authorization: Bearer aura_pk_live_xxxxxxxxxxxxxxxx ``` Get your API key from the Aura dashboard at Settings > API Keys. **2. Clerk JWT (for mobile and web apps):** ``` Authorization: Bearer ``` Use Clerk's authentication SDK to obtain a JWT token with org claims. ## Rate Limiting - **Per API Key:** 100 requests/minute - **Per Organization:** 1000 requests/minute Rate limit headers are included in all responses: - `X-RateLimit-Limit`: Maximum requests allowed - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp when limit resets These counters are held per serving instance, so under concurrency the effective ceiling is higher than the number above and the headers describe one instance's view rather than a global total. Treat a 429 as backpressure to obey and pace your client to the documented rate — but do not rely on us to reject your 101st request, and do not derive a global remaining-quota figure from the headers. The limit may become globally enforced without notice, so a client that stays within it will not be affected when that happens. ## Pagination List endpoints support cursor-based pagination: - `limit`: Number of results per page (default: 50, max: 100) - `cursor`: Opaque cursor for next page ## Error Handling All errors follow a standard format: ```json { "success": false, "error": "Error message", "code": "ERROR_CODE" } ``` Common HTTP status codes: - **400** Bad Request - Invalid input (`VALIDATION_ERROR`) - **401** Unauthorized - Missing or invalid API key (`AUTHENTICATION_ERROR`) - **402** Payment Required - The key is valid, but the organization's subscription is not active (`PAYMENT_REQUIRED`). Every authenticated endpoint can return this. Retrying will not help until the account's payment method is updated in Aura; surface it to the account owner rather than treating it as an auth failure. - **403** Forbidden - Insufficient permissions (`AUTHORIZATION_ERROR`) - **404** Not Found - Resource not found (`NOT_FOUND`) - **409** Conflict - Resource state prevents the operation (`CONFLICT`) - **413** Payload Too Large - Request body exceeds 256KB (`PAYLOAD_TOO_LARGE`) - **429** Too Many Requests - Rate limit exceeded (`RATE_LIMIT_EXCEEDED`) - **500** Internal Server Error - Server error (`INTERNAL_ERROR`) ## Webhooks Subscribe to real-time events using the Webhooks API. All webhook payloads are signed with HMAC-SHA256 for security verification. Delivery is at-least-once. Every payload carries an `idempotency_key` that is stable across retries of the same event, so you can enforce exactly-once with a `(subscription_id, idempotency_key)` unique constraint on your side. For full documentation, visit [docs.aura-app.ai/api](https://docs.aura-app.ai/api) license: name: Proprietary title: Aura Partner Integrations API version: 1.0.0-alpha servers: - description: Production url: https://api.aura-app.ai - description: Staging url: https://staging-api.aura-app.ai - description: Local Development url: http://localhost:3001 security: - bearerAuth: [] tags: - description: Lead management operations name: Leads - description: Call booking and management name: Calls - description: Booking link configuration (read-only) name: Booking Links - description: Product catalog (read-only) name: Products - description: Payment tracking (read-only) name: Payments - description: Public booking creation name: Bookings - description: Real-time event subscriptions and webhook management name: Webhooks - description: >- Team member information for commission attribution. **Alpha** - schema may change without notice. name: Team (Alpha) - description: >- Dashboard analytics, lead source attribution, and objection analysis. **Alpha** - schema may change without notice. name: Analytics (Alpha) - description: System endpoints (health checks) name: System paths: /v1/opportunities: get: tags: - Opportunities summary: List opportunities description: >- Retrieve a paginated list of opportunities (deals) for your organization, newest first. Each opportunity is a booking call viewed as a deal, joined to its lead and any linked sale. The `stage` field is derived at read time from the lead's full call history using the same rules as the dashboard pipeline: 1. **disqualified** — latest form/intent disqualification (overridden by newer booking activity) 2. **booked / confirmed** — active future booking (confirmed when the guest accepted) 3. Most recent past outcome — **won / unfit / lost / cancelled / declined / attended / no_show / follow_up** 4. **qualified / interested** — qualification signals without a booking 5. Stored lead status fallback **Use Cases:** - Sync deals into an external CRM or reporting warehouse - Track pipeline movement without polling individual leads - Reconcile expected vs actual deal value **Filtering:** - Filter by derived stage, lead, or scheduled date range - Stage filtering is applied per page (see the `stage` parameter) - Most interested, qualified and disqualified leads have not booked a call, so they have no opportunity. List them with `GET /v1/leads?stage=`. parameters: - description: Number of opportunities to return (1-100) in: query name: limit required: false schema: default: 20 description: Number of opportunities to return (1-100) example: 20 maximum: 100 minimum: 1 type: integer - description: Pagination cursor from a previous response in: query name: cursor required: false schema: description: Pagination cursor from a previous response type: string - description: >- Filter by derived pipeline stage. The server scans a bounded set of candidates to fill the page. A scan-limited page can be short or empty. Continue with next_cursor while has_more is true. Most interested, qualified and disqualified leads have not booked a call, so they have no opportunity here; list them with GET /v1/leads?stage= instead. in: query name: stage required: false schema: description: >- Filter by derived pipeline stage. The server scans a bounded set of candidates to fill the page. A scan-limited page can be short or empty. Continue with next_cursor while has_more is true. Most interested, qualified and disqualified leads have not booked a call, so they have no opportunity here; list them with GET /v1/leads?stage= instead. enum: - interested - disqualified - qualified - booked - confirmed - declined - cancelled - attended - unfit - no_show - follow_up - lost - won example: booked type: string - description: Filter by lead ID in: query name: lead_id required: false schema: description: Filter by lead ID type: string - description: Filter calls scheduled on/after this date (ISO 8601) in: query name: from_date required: false schema: description: Filter calls scheduled on/after this date (ISO 8601) example: '2026-01-01' type: string - description: Filter calls scheduled on/before this date (ISO 8601) in: query name: to_date required: false schema: description: Filter calls scheduled on/before this date (ISO 8601) example: '2026-12-31' type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedOpportunities' description: Successfully retrieved opportunities '400': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: Request validation failed headers: X-Request-Id: description: Request identifier for support schema: type: string '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Invalid or missing API key '402': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The organization's subscription is not active headers: X-Request-Id: description: Request identifier for support schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The API key does not have the required scope headers: X-Request-Id: description: Request identifier for support schema: type: string '408': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: >- The request exceeded its processing time limit. Check the outcome before retrying a write headers: X-Request-Id: description: Request identifier for support schema: type: string '413': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The request body exceeds 256KB headers: X-Request-Id: description: Request identifier for support schema: type: string '429': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: Rate limit exceeded. Wait before retrying headers: Retry-After: description: Seconds to wait before retrying schema: type: string X-RateLimit-Limit: description: Requests allowed in the current window schema: type: string X-RateLimit-Remaining: description: Requests remaining in the current window schema: type: string X-RateLimit-Reset: description: Window reset as a Unix timestamp schema: type: string X-Request-Id: description: Request identifier for support schema: type: string '500': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: >- Unexpected server failure. Include the request identifier when contacting support headers: X-Request-Id: description: Request identifier for support schema: type: string security: - bearerAuth: [] components: schemas: PaginatedOpportunities: properties: data: items: $ref: '#/components/schemas/Opportunity' type: array pagination: properties: has_more: description: Whether more opportunities exist beyond this page type: boolean next_cursor: description: Cursor for the next page (null when no more pages) nullable: true type: string scan_limited: description: >- The stage search reached its scan limit before filling the page. Continue with next_cursor to search the remaining candidates. type: boolean required: - next_cursor - has_more type: object required: - data - pagination type: object MiddlewareErrorResponse: properties: code: type: string error: type: string requestId: type: string success: enum: - false type: boolean required: - success - error - code type: object ErrorResponse: properties: code: description: Error code for programmatic handling example: NOT_FOUND type: string error: description: Human-readable error message example: Lead not found type: string requestId: description: Request ID for support debugging example: req_abc123 type: string success: enum: - false type: boolean required: - success - error - code type: object Opportunity: properties: actual_value: description: >- Money collected on this deal so far (in dollars with decimals): the sum of its settled payments. For a payment plan it grows with each payment. A call recorded before deals sums every settled sale on it. Null until a payment is settled. example: 4500 nullable: true type: number actual_value_currency: description: >- Recorded currency of the settled payments' payment or product price links. Null when none records a currency or they disagree. No currency is assumed. example: CAD nullable: true type: string booking_link_id: description: Booking link the call was booked through nullable: true type: string call_status: description: >- Raw outcome status of the underlying call (shown, no_show, cancelled, rescheduled, closed, lost, follow_up, declined, unfit). Null when no outcome has been recorded yet. example: closed nullable: true type: string closed_at: description: >- When the deal closed: the latest settled payment's closed_at, falling back to the call's end time. Null while the deal is open. nullable: true type: string created_at: description: When the opportunity (booking call) was created (ISO 8601) type: string expected_deal_value: description: >- Expected deal value (in dollars with decimals), as set on the call. Null when not set. example: 5000 nullable: true type: number id: description: Opportunity ID (the underlying booking call's ID) example: 550e8400-e29b-41d4-a716-446655440000 type: string lead: $ref: '#/components/schemas/OpportunityLeadSummary' lead_id: description: Associated lead ID nullable: true type: string payments: description: >- Every payment recorded on the deal, in order. A payment plan has one per payment: what was paid when the deal closed, then each later payment with its due_at. A cancelled payment stays in the list with status `cancelled`. This is the schedule as it stands now; the `call.closed` webhook carries it as it was at close and is not sent again when payments change. Empty when no sale is recorded. items: $ref: '#/components/schemas/OpportunityPayment' type: array scheduled_at: description: When the call is/was scheduled (ISO 8601) example: '2026-07-01T15:00:00.000Z' nullable: true type: string stage: description: >- Derived pipeline stage, computed at read time from the lead's call history (disqualification, upcoming bookings, most recent past outcome, qualification signals, stored status fallback). enum: - interested - disqualified - qualified - booked - confirmed - declined - cancelled - attended - unfit - no_show - follow_up - lost - won example: booked type: string updated_at: description: When the underlying call was last updated (ISO 8601) nullable: true type: string required: - id - lead_id - lead - stage - call_status - expected_deal_value - actual_value - actual_value_currency - scheduled_at - closed_at - payments - booking_link_id - created_at - updated_at type: object OpportunityLeadSummary: description: Embedded lead summary (null if the lead was deleted) nullable: true properties: email: description: Email address of the lead example: jane@example.com nullable: true type: string id: description: Lead ID type: string name: description: Full name of the lead example: Jane Doe nullable: true type: string required: - id - name - email type: object OpportunityPayment: properties: amount: description: >- Recorded gross amount of this payment before refunds, in major units (1000 means 1,000.00), in the opportunity's currency (`actual_value_currency`); a payment carries no currency of its own. example: 1000 type: number due_at: description: >- When a later payment of a payment plan is due (ISO 8601). Null for any other payment. A due date is a day: it is stored at noon UTC, so read its date in UTC. example: '2026-12-15T12:00:00.000Z' nullable: true type: string paid_at: description: When the money arrived (ISO 8601). Null while pending. nullable: true type: string refunded_amount: description: >- Cumulative amount returned from this payment, in the same major units as amount. Zero when no refund is recorded. Net value is amount - min(max(amount, 0), max(refunded_amount, 0)). The amount field keeps its recorded gross value. example: 500 type: number sale_id: description: Sale record ID type: string status: description: >- `paid` once the money arrived, `pending` while it is still due, `cancelled` when it was cancelled before it was paid (it stays in the list and is neither paid nor owed), `refunded` when the money was given back. Other values are legacy or provider statuses. example: pending type: string required: - sale_id - amount - refunded_amount - status - due_at - paid_at type: object ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.