API Documentation

Build integrations and automate workflows with the IdeaDunes REST API. Full CRUD support, JWT authentication, and real-time webhooks.

Getting Started

The IdeaDunes API is a RESTful JSON API. All requests must include an Authorization: Bearer <token> header with a valid JWT obtained from the login endpoint. All API responses return JSON with consistent error formatting.

Base URL

https://app.ideadunes.com/api/

Content Type

application/json

Rate Limit

100 requests/minute (Standard), 1000 requests/minute (Enterprise)

Authentication

Obtain a JWT token by sending credentials to the login endpoint. Include the token in all subsequent requests.

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your-password"
}

Response 200:
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 1,
    "email": "[email protected]",
    "name": "John Doe"
  }
}

Authentication

MethodEndpointDescription
POST /api/auth/login Authenticate with email/password. Returns JWT token and session.
POST /api/auth/signup Create a new user account with email verification.
POST /api/auth/logout Invalidate current session and JWT token.
POST /api/auth/refresh Refresh an expired JWT token using refresh token.
POST /api/auth/forgot-password Request a password reset email.
POST /api/auth/reset-password Reset password using token from email.
POST /api/auth/verify-email Verify email address using verification token.
POST /api/auth/magic-link Request a passwordless login link via email.
POST /api/auth/setup-2fa Enable two-factor authentication (TOTP or SMS).
POST /api/auth/verify-2fa Verify 2FA code during login.

Users & Profiles

MethodEndpointDescription
GET /api/users/me Get the authenticated user profile.
PUT /api/users/me Update the authenticated user profile.
GET /api/users/{id} Get a user by ID (admin only).
GET /api/users List all users with pagination and filtering (admin only).

Contacts & CRM

MethodEndpointDescription
GET /api/crm/contacts List all contacts with search and pagination.
POST /api/crm/contacts Create a new contact record.
GET /api/crm/contacts/{id} Get contact details by ID.
PUT /api/crm/contacts/{id} Update an existing contact.
DELETE /api/crm/contacts/{id} Delete a contact (soft delete).
GET /api/crm/leads List all leads with filtering.
GET /api/crm/accounts List all accounts/companies.

Projects & Tasks

MethodEndpointDescription
GET /api/projects List all projects accessible to the user.
POST /api/projects Create a new project.
GET /api/projects/{id} Get project details and summary.
GET /api/projects/{id}/tasks List all tasks in a project.
POST /api/tasks Create a new task.
PUT /api/tasks/{id} Update task status, assignee, or details.

Invoicing & Billing

MethodEndpointDescription
GET /api/invoices List invoices with filters (status, date, client).
POST /api/invoices Create a new invoice with line items.
GET /api/invoices/{id} Get invoice details with line items and payments.
POST /api/invoices/{id}/send Send invoice to client via email.

Files & Documents

MethodEndpointDescription
GET /api/files List files and folders in the file manager.
POST /api/files/upload Upload a file (max 50MB, multipart/form-data).
GET /api/files/{id}/download Download a file by ID.
DELETE /api/files/{id} Delete a file (moves to trash).

Webhooks

MethodEndpointDescription
GET /api/webhooks List configured webhooks for the account.
POST /api/webhooks Create a new webhook subscription.
DELETE /api/webhooks/{id} Remove a webhook subscription.

Error Codes

CodeMeaningAction
400Bad RequestCheck request body and parameters
401UnauthorizedProvide or refresh your JWT token
403ForbiddenInsufficient permissions for this resource
404Not FoundResource does not exist
422Validation ErrorFix the validation errors in the response body
429Rate Limit ExceededWait and retry after the Retry-After header value
500Server ErrorContact support with the request ID from the response

Webhooks

Register webhook endpoints to receive real-time notifications when resources are created, updated, or deleted in IdeaDunes. Webhook payloads include the event type, timestamp, and full resource data.

Available Events

contact.created contact.updated lead.created project.created task.updated task.completed invoice.created invoice.paid file.uploaded user.created

Need Help with Your Integration?

Our developer support team can assist with API questions, custom integration design, and troubleshooting.

Contact Developer Support