Skip to content

Contacts & Leads API

Updated

On this page17

Overview#

The Contacts & Leads API allows you to programmatically manage your contact database in AutomateNexus CRM. You can list, search, create, update, and delete contacts, create or update them in bulk, export them, and attach notes to them. Every request needs an API key in the Authorization header; see API Overview & Authentication for keys, rate limits, and error handling.

List Contacts#

GET /api/contacts

Returns contacts newest first, 50 per page unless you pass limit.

Query Parameters#

  • search (string) — Case-insensitive partial match on first name, last name, or email.
  • limit (integer) — Records per page. Default: 50.
  • offset (integer) — Records to skip. Default: 0.

Example Request#

curl -X GET "https://app.automatenexuscrm.com/functions/v1/api/contacts?search=smith&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response#

{
  "data": [
    {
      "id": "3f9c2a1e-7b4d-4c8e-9a12-5d6e7f8a9b0c",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone": "+15550123",
      "mobile_phone": null,
      "job_title": "VP of Marketing",
      "department": null,
      "company_name": "Acme Corp",
      "company_id": null,
      "customer_id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "status": "lead",
      "lead_source": "website",
      "lead_score": 85,
      "city": "Austin",
      "state": "TX",
      "country": "US",
      "custom_fields": {
        "industry": "Technology"
      },
      "created_at": "2026-01-15T09:30:00Z",
      "updated_at": "2026-03-20T14:22:00Z",
      "customer": {
        "id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "name": "Acme Corp",
        "email": "billing@acme.example",
        "company": "Acme Corp"
      },
      "workspace": null
    }
  ],
  "count": 1,
  "total": null
}

Each contact carries the fields listed under Create a Contact, plus id, organization_id, created_at, updated_at, and two embedded objects: customer (id, name, email, company) when the contact is linked to a customer record, and workspace (id, name). count is the number of records in this page; total is not computed for contacts and is always null, so request further pages until a page returns fewer records than limit.

Get a Contact#

GET /api/contacts/:id

Returns a single contact with the same fields and embedded objects as the list. Returns 404 when no contact with that ID exists in your organization.

curl -X GET "https://app.automatenexuscrm.com/functions/v1/api/contacts/3f9c2a1e-7b4d-4c8e-9a12-5d6e7f8a9b0c" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a Contact#

POST /api/contacts

Request Body#

  • first_name (string, required) — Contact's first name.
  • last_name (string, required) — Contact's last name.
  • email (string) — Contact's email address. Must be a valid address if provided.
  • phone, mobile_phone (string) — Phone numbers.
  • job_title, department (string) — Role details.
  • company_name (string) — Company name as text. company_id (string) — ID of a company record. customer_id (string) — ID of a customer record to link the contact to.
  • status (string) — One of lead, prospect, client, customer, inactive, team, partner, vendor.
  • lead_source (string) — Free text, for example website or referral.
  • lead_score (number) — Numeric score.
  • address_line1, address_line2, city, state, zip_code, country (string) — Address fields.
  • website, linkedin, twitter (string) — Links.
  • notes (string) — Free-text notes stored on the record.
  • custom_fields (object) — Key-value pairs. Define the fields under Settings → Custom fields.
  • contact_owner_id (string) — User ID of the owner.
  • next_follow_up_date, last_contacted_at (string) — ISO 8601 timestamps.
  • is_primary (boolean), industry, company_size, position_level (string).
  • sms_marketing_consent, whatsapp_opt_in (boolean) — Messaging consent flags.

Fields that are not part of the contact record are rejected with 400. The response is 201 with the created contact.

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": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+15550199",
    "company_name": "TechStart Inc",
    "status": "lead",
    "lead_source": "api",
    "custom_fields": {
      "industry": "SaaS",
      "company_size": "10-50"
    }
  }'

Update a Contact#

PUT /api/contacts/:id

Updates an existing contact. Only include the fields you want to change — omitted fields are not modified. The response is the updated contact.

curl -X PUT "https://app.automatenexuscrm.com/functions/v1/api/contacts/3f9c2a1e-7b4d-4c8e-9a12-5d6e7f8a9b0c" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "customer",
    "custom_fields": { "plan": "enterprise" }
  }'

Delete a Contact#

DELETE /api/contacts/:id

Permanently deletes a contact. This action cannot be undone.

curl -X DELETE "https://app.automatenexuscrm.com/functions/v1/api/contacts/3f9c2a1e-7b4d-4c8e-9a12-5d6e7f8a9b0c" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "message": "Contact deleted successfully"
}

Bulk Create or Update Contacts#

POST /api/bulk

Create or update many contacts in a single request. Records are processed one at a time; the response counts the successes and lists any failures with their reason.

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

Response#

{
  "message": "Bulk create completed",
  "results": [ ... ],
  "errors": [],
  "success_count": 2,
  "error_count": 0
}

For updates, set "operation": "update" and include the id of each contact in data. The response is 200 even when some records fail, so check error_count.

Search Contacts#

To search within contacts, use the search parameter of the list endpoint. To search contacts together with other records in one call, use the search endpoint, which returns up to limit matches per resource:

curl -X GET "https://app.automatenexuscrm.com/functions/v1/api/search?q=acme&entities=contacts&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "query": "acme",
  "results": {
    "contacts": [ ... ]
  },
  "total_results": 3,
  "entities_searched": ["contacts"]
}

Export Contacts#

POST /api/export

Returns all contacts, optionally filtered by exact field values, as JSON (default) 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": "contacts", "format": "csv", "filters": {"status": "lead"}}'

Contact Notes#

GET /api/notes?target_type=contact&target_id=:id
POST /api/notes

Notes are plain text records that can be attached to a contact, company, deal, or customer. To create a note on a contact:

curl -X POST "https://app.automatenexuscrm.com/functions/v1/api/notes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Call summary",
    "body_text": "Spoke with Jane about renewal timing.",
    "target_type": "contact",
    "target_id": "3f9c2a1e-7b4d-4c8e-9a12-5d6e7f8a9b0c"
  }'

Provide at least a title or body_text. The response is 201 with id, title, body_text, created_at, updated_at, and targets. Listing with target_type and target_id returns the notes attached to that contact, newest first, with a pagination object.

Troubleshooting#

  • 400 mentioning check_contact_status: The status value is not one of the allowed statuses listed above.
  • 400 mentioning the email format: The email value is not a valid email address. Send a valid address or leave the field out.
  • 400 naming a column you did not expect: The field is not part of the contact record. Check the spelling against the list above and remove fields that do not exist.
  • Custom fields not showing: Custom fields are stored as a JSON object under custom_fields. Define the fields themselves under Settings → Custom fields and use the same keys in the API.
  • 404 on Get, Update, or Delete: The ID must be the contact's UUID as returned by the API, and the contact must belong to the organization the API key was created in.

Was this page helpful?