Skip to content
SAVE4545% off every plan.See the offer

API ReferenceAPI Overview & Authentication

API Overview & Authentication

On this page· 20

Overview#

The AutomateNexus CRM API provides a RESTful interface for integrating your applications with AutomateNexus CRM. You can use the API to manage customers, contacts, companies, deals, tasks, notes, invoices, and support tickets programmatically, organize project work (task lists, folders, and project automations), run searches and bulk operations, and export records. This guide covers authentication, rate limiting, error handling, pagination, and general API conventions.

Base URL#

All API requests should be made to the following base URL:

https://app.automatenexuscrm.com/functions/v1/api

Resource paths follow directly after /api, for example /api/contacts or /api/deals/<id>. The /functions/v1 segment is a fixed part of the address, not an API version, and there is no version header.

All requests must use HTTPS. HTTP requests will be rejected with a 301 Moved Permanently redirect.

Available Resources#

  • /customers, /contacts, /companies, /deals, /tasks, /notes, /invoices — list, get, create, update, and delete records. Customers, contacts, and companies come with their tags, take add_tags and remove_tags, and their lists take tag.
  • /tasks/<id>/subtree, /tasks/<id>/checklists, /tasks/<id>/links, /task-lists, /folders, /project-automations — a task's subtasks, checklists, and linked tasks, a project's task lists, the folders that group projects, and a project's own automation rules. See the Tasks & Activities API.
  • /tickets — support tickets, with their conversation (/tickets/<id>/comments) and files (/tickets/<id>/attachments). Tickets are closed, not deleted: a DELETE is answered 405.
  • /signatures — create e-signature requests and read captured signatures.
  • /search, /bulk, /export — search across resources, create or update many records in one request, and export records as JSON or CSV.
  • /me, /users, /workspaces, /stages, /custom-fields, /task-statuses, /tags — read-only lookups: your organization and key, your team, workspaces, deal stages, custom fields, projects' own task statuses, and tags, for the IDs and names the other endpoints take.
  • /analytics — request counts, error rate, and response times for your organization's API calls.
  • /schema — an OpenAPI 3.0 description of the API.

A request to any other path returns 404 with an available_endpoints list.

Authentication#

The AutomateNexus CRM API uses Bearer token authentication. You must include your API key in the Authorization header of every request.

Generating an API Key#

Owners and admins of the organization create and manage API keys; other members see a note asking them to contact one.

  1. Go to Administration → Integrations → Developer and scroll to API keys.
  2. Under New key, say what the key is for (e.g., "Production Integration" or "Zapier") and click Create key.
  3. The Copy your new key now dialog shows the key, which starts with ak_. Copy it with the copy button, then close the dialog with Done (it reads I have copied it until you copy). This is the only time the key is shown: only its hash is kept, so a lost key is deleted and replaced.
  4. The list shows each key's name, the first characters of the key, Read only or Read and write, the day it was created, and when it was last used. A key the API refuses is marked Switched off or Expired.
  5. To retire a key, click the trash icon on its row and confirm with Delete. Anything that uses the key stops working at once, with 401.

Keys can also be created under Settings → API keys. Click Create key, enter a Name, optionally fill in Scopes and an Expiration (Never, 30 days, 90 days, or 1 year), and copy the key from the Key created dialog. Keys created there start with ank_; the table shows each key's status and expiry date, and the row menu offers Revoke and Delete. Both kinds of key work the same way with the API. An expired or revoked key is rejected with 401.

What a Key Can Do#

  • Read and write: A key with no scopes (the default, and every key created under Administration → Integrations → Developer) can read and write every resource of the organization it was created in.
  • Read only: A key whose Scopes list read without write can make GET requests and POST /api/export, and nothing else. Any other request is answered 403 ("This API key is read-only").
  • Its maker: A key acts for the person who created it and works only while they are still an owner or admin of the workspace. When they stop being one, the key is switched off and its requests are answered 401; an owner or admin creates a new one.
  • The plan: Keys work while the workspace has a live plan. When it has ended, requests are answered 403 with "code": "SUBSCRIPTION_REQUIRED". In the read-only days after an AppSumo refund, a key can still read but not change anything.
  • MCP keys: The key made on the MCP server card works only with the MCP server; the REST API refuses it with 401. See the MCP Integration Guide.

Using the API Key#

Include your API key as a Bearer token in the Authorization header:

curl -X GET "https://app.automatenexuscrm.com/functions/v1/api/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Request Format#

All request bodies must be sent as JSON with the Content-Type: application/json header. Parameters for GET requests should be passed as URL query parameters.

# POST request example
curl -X POST "https://app.automatenexuscrm.com/functions/v1/api/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com"
  }'

Response Format#

All responses are JSON. A request for a single record returns the record itself. Creating a record returns 201 with the new record, updating returns the updated record, and deleting returns a confirmation:

{
  "message": "Contact deleted successfully"
}

The record lists (customers, contacts, companies, deals, tasks, invoices, notes, and tickets) return the records under data, with a pagination object:

{
  "data": [ ... ],
  "pagination": {
    "count": 50,
    "total": 1250,
    "offset": 0,
    "limit": 50,
    "has_more": true
  }
}

Contacts, deals, tasks, and invoices also repeat count and total next to data. The lookups, task lists, and folders return data with a total and no paging.

Error Handling#

When an error occurs, the API returns an appropriate HTTP status code along with a JSON body that describes the problem in an error field:

{
  "error": "Invalid API key"
}

Validation errors carry the database's message, which names the field or rule involved (for example, a missing required field or a value outside the allowed set). Some server errors add a details field.

A field the API does not write is not an error. On customers, contacts, companies, deals, tasks, invoices, task lists, and folders, it is left out of the record and named in the X-Ignored-Fields response header; protected fields such as id, organization_id, created_by, created_at, and updated_at are treated the same way. A body with no field the API writes is refused with 400 ("No writable fields in the request body").

Error Code Reference#

  • 400 Bad Request — The JSON body is missing or malformed, a required field is missing, a value breaks a rule (for example, an unknown deal stage), an ID in the path or body is not a UUID, a record the body points at (a customer, company, project, user, or workspace) is not in your organization, or limit is out of range. Read the error message for the field or rule.
  • 401 Unauthorized — The Authorization header is missing or not in Bearer form ("Missing or invalid API key"), the key does not exist or was revoked ("Invalid API key"), the key has passed its expiry date ("API key has expired"), it is an MCP server key, or the person who made it no longer manages the workspace.
  • 403 Forbidden — The key is read-only and the request would change something, or the workspace's plan has ended ("code": "SUBSCRIPTION_REQUIRED").
  • 404 Not Found — No record with that ID exists in your organization, or the resource path is unknown (the body then lists available_endpoints).
  • 405 Method Not Allowed — The resource does not support that HTTP method.
  • 409 Conflict — A value that must be one of a kind in your organization is already taken, or the customer you are deleting has invoices, payments, or orders (change its status instead).
  • 429 Too Many Requests — You have exceeded the rate limit. Wait for the number of seconds in the Retry-After header and retry.
  • 500 Internal Server Error — An unexpected error occurred on our end. The body includes a message; if the error persists, contact support with the request you sent.

Rate Limiting#

Each API key may make 120 requests per minute, counted over the last 60 seconds. The limit is the same on every plan. Two headers on every response show where you stand:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87

When you exceed the limit, you receive a 429 Too Many Requests response with a Retry-After header of 30 seconds and a body that repeats the limit:

{
  "error": "Rate limit exceeded",
  "limit_per_minute": 120,
  "retry_after_seconds": 30
}

Pagination#

List endpoints use offset pagination. Pass limit and offset as query parameters:

# First page
GET /api/contacts?limit=50
&nbsp;
# Next page
GET /api/contacts?limit=50&offset=50

Pagination parameters:

  • limit (optional) — Number of records per page. Default: 50. It goes up to 1,000 for customers, contacts, deals, tasks, and invoices, and up to 200 for companies and tickets; a value outside the range is refused with 400. Notes return at most 100, whatever you ask for.
  • offset (optional) — Number of records to skip. Default: 0.

Request the next page until pagination.has_more is false. Pages are in a steady order, so a record does not appear on two pages while nothing changes.

Filtering and Sorting#

Lists are returned newest first, by creation date. Companies and tickets also take sort: a field name for ascending order, or the name with - in front for descending (for example sort=name or sort=-updated_at). Each resource accepts a set of filters as query parameters:

  • contacts — search (matches first name, last name, email, or company name), tag.
  • customers — search (matches name, email, or company), tag.
  • companies — search (name, domain, industry, phone, or city), domain, company_type, status, owner_id, workspace_id, customer_id, parent_company_id, created_since, updated_since, tag; sort by created_at, updated_at, or name.
  • deals — stage.
  • tasks — status, status_id, project_id, list_id, parent_task_id, assignee_id, client_visible.
  • tickets — status, priority, customer_id, assigned_to, internal_status, tag, search, updated_since; sort by created_at, updated_at, priority, or status.
  • invoices — status.
  • notes — search (title or body), target_type together with target_id.
  • signatures — document_id.

tag takes a tag's name, whatever its capitals, or its ID.

To search several resources at once, use the search endpoint. It returns up to limit matches per resource (default 10):

GET /api/search?q=acme&entities=contacts,deals,customers&limit=10
{
  "query": "acme",
  "results": {
    "contacts": [ ... ],
    "deals": [ ... ],
    "customers": [ ... ]
  },
  "total_results": 7,
  "entities_searched": ["contacts", "deals", "customers"]
}

entities may include customers, contacts, companies, deals, tasks, and invoices. When it is omitted, customers, contacts, and deals are searched. Customers, contacts, and companies are also found by the name of a tag they carry.

Bulk Operations and Export#

POST /api/bulk creates or updates up to 200 records of one type in a single request. Records are processed one by one, and the response lists the successes and the failures:

curl -X POST "https://app.automatenexuscrm.com/functions/v1/api/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "contacts",
    "operation": "create",
    "data": [
      {"first_name": "Alice", "last_name": "Nguyen", "email": "alice@example.com"},
      {"first_name": "Bob", "last_name": "Rivera", "email": "bob@example.com"}
    ]
  }'
{
  "message": "Bulk create completed",
  "results": [ ... ],
  "errors": [],
  "success_count": 2,
  "error_count": 0,
  "ignored_fields": []
}

entity_type may be customers, contacts, companies, deals, tasks, or invoices; operation is create or update (each record in an update needs its id). A request with more than 200 records is refused with 400; send the rest in further requests. The response is 200 even when some records fail, so check error_count and the errors array. ignored_fields lists, by each record's position in data, the fields that were not written.

POST /api/export returns every record of one type, optionally filtered by exact field values, as JSON or CSV:

curl -X POST "https://app.automatenexuscrm.com/functions/v1/api/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity_type": "deals", "format": "csv", "filters": {"stage": "closed_won"}}'

entity_type may be customers, contacts, companies, deals, tasks, or invoices. With format set to json (the default) the body is {"data": [...], "total": n, "truncated": false, "exported_at": "...", "format": "json"}; with csv the response is a text/csv download, with the row count in an X-Export-Rows header. An export stops at 50,000 rows and then reports truncated as true (in CSV, the X-Export-Truncated header). Customers, contacts, and companies come with their tags, and "filters": {"tag": "..."} exports only those carrying one.

Every export is recorded in your organization's audit log with the key that made it. If that entry cannot be written, nothing is sent and the API answers 503; try again.

Client Libraries#

There is no official SDK. The API is plain JSON over HTTPS and works with any HTTP client. GET /api/schema returns an OpenAPI 3.0 document that you can import into API tools or a code generator.

Webhooks vs. Polling#

For real-time data synchronization, we strongly recommend using Webhooks instead of polling the API. Webhooks push data to your endpoint when events occur, reducing API calls and latency. Webhooks are created in the app under Administration → Integrations → Developer → Webhooks; see the Webhooks API article for events, payloads, and signature verification.

In-App Reference#

  • Base URL: Administration → Integrations → Developer shows it under API endpoint, with a copy button and a Docs button that opens the in-app API documentation.
  • Documentation: The Documentation section on the same page links to the API reference, the Webhook guide, and Code examples.
  • Usage: GET /api/analytics?time_range=7d (1h, 24h, 7d, or 30d) returns request counts, error rate, and average response time for your organization's API calls.
  • Your key: GET /api/me returns your organization, the key in use (with access set to read or read_write), the main workspace, and the rate limit.

Troubleshooting#

Common Issues#

  • "401 Unauthorized" on every request: Ensure you are using Bearer YOUR_KEY (not just the key alone) in the Authorization header. Check for extra whitespace, and confirm the key is still listed under Administration → Integrations → Developer → API keys or Settings → API keys and not marked Switched off, Expired, or Revoked. A key is switched off when the person who made it stops being an owner or admin.
  • "403" with "This API key is read-only": The key's scopes list read without write. Use a key with write access for requests that change records.
  • "403" with SUBSCRIPTION_REQUIRED: The workspace's plan has ended. An admin can choose a plan under Administration → Plans.
  • "Endpoint not found": The first path segment after /api must be one of the resources listed above, for example /api/contacts, not /api/v1/contacts.
  • A field you sent did not change: Read the X-Ignored-Fields response header. It names every field the API left out, such as a misspelled name or a field that is not written through the API.
  • 400 with a database message: The message names the field. Check the allowed values (for example, deal stages and contact statuses) in the resource guides.
  • Empty response data: Check your filter parameters. Overly restrictive filters may return zero results.
  • Rate limit exceeded frequently: Wait for the Retry-After period, queue requests on your side, and use /api/bulk for mass creates and updates.

Was this page helpful?

Last updated