Skip to content

API Overview & Authentication

Updated

On this page19

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, deals, tasks, notes, and invoices programmatically, 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, /deals, /tasks, /notes, /invoices — list, get, create, update, and delete records.

  • /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.

  • /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#

  1. Go to Settings → Integrations → Developer and scroll to the API keys section.

  2. Under Generate New API Key, enter a descriptive name in API Key Name (e.g., "Production Integration" or "Zapier Connection") and click Generate.

  3. Copy the key right away with the copy button next to it. Keys start with ak_. The full key is shown only once; afterwards Your API Keys lists just the name, the first characters of the key, the creation date, and the date it was last used.

  4. To retire a key, click the trash icon on its row. Requests made with a deleted key are rejected with 401.

Keys can also be created under Settings → API keys. Click Create key, enter a Name, optionally set 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.

The REST API does not restrict keys by scope: any active key can read and write every resource of the organization it was created in. Pro Tip: Create separate API keys for each integration. This way, you can revoke access to a single integration without affecting others.

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"
}

List endpoints return the records under data. Customers and notes include a pagination object:

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

Contacts, deals, tasks, and invoices return the page count next to the records. total is not computed for these resources and comes back as null:

{
  "data": [ ... ],
  "count": 50,
  "total": null
}

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, a field that is not part of the record, or a value outside the allowed set). Some server errors add a details field.

Error Code Reference#

  • 400 Bad Request — The JSON body is missing or malformed, a required field is missing, a field is not part of the record, or a value breaks a rule (for example, an unknown deal stage). 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"), or the key has passed its expiry date ("API key has expired").

  • 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.

  • 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
 
# Next page
GET /api/contacts?limit=50&offset=50

Pagination parameters:

  • limit (optional) — Number of records per page. Default: 50. Notes accept at most 100.

  • offset (optional) — Number of records to skip. Default: 0.

For customers and notes, stop when pagination.has_more is false. For contacts, deals, tasks, and invoices, stop when a page comes back with fewer records than limit.

Filtering and Sorting#

Lists are always returned newest first, by creation date; there is no sort parameter. Each resource accepts a small set of filters as query parameters:

  • contacts — search (matches first name, last name, or email).

  • customers — search (matches name, email, or company).

  • deals — stage.

  • tasks — status, project_id.

  • invoices — status.

  • notes — search (title or body), target_type together with target_id.

  • signatures — document_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, deals, tasks, and invoices. When it is omitted, customers, contacts, and deals are searched.

Bulk Operations and Export#

POST /api/bulk creates or updates many 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
}

entity_type may be customers, contacts, deals, tasks, or invoices; operation is create or update (each record in an update needs its id). The response is 200 even when some records fail, so check error_count and the errors array.

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"}}'

With format set to json (the default) the body is {"data": [...], "total": n, "exported_at": "...", "format": "json"}; with csv the response is a text/csv download.

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 Settings → Integrations → Developer → Webhooks; see the Webhooks API article for events, payloads, and signature verification.

In-App Reference#

  • Base URL: Settings → 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 in-app API documentation and the Webhook Guide.

  • 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.

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 and active under Settings → Integrations → Developer → API keys or Settings → API keys.

  • "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.

  • 400 with a database message: The message names the field. Remove fields that are not part of the record, and 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?