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/contactsReturns contacts newest first, 50 per page unless you pass limit.
Query Parameters#
- search (string) — Case-insensitive partial match on first name, last name, email, or company name.
- tag (string) — Only contacts carrying this tag, by its name or ID (see Tags below).
- limit (integer) — Records per page, from 1 to 1,000. 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"
},
"workspace_id": "e4b1c9a0-2d3f-4e5a-9b8c-7d6e5f4a3b2c",
"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": {
"id": "e4b1c9a0-2d3f-4e5a-9b8c-7d6e5f4a3b2c",
"name": "Main"
},
"tags": [
{ "id": "7a1c0e52-3b9d-4f6a-8c21-5d4e3f2a1b0c", "name": "Client enquiry", "color": "#2c53f0" }
]
}
],
"count": 1,
"total": 1,
"pagination": { "count": 1, "total": 1, "offset": 0, "limit": 10, "has_more": false }
}Each contact carries the fields listed under Create a Contact, plus id, organization_id, created_at, updated_at, the fields the CRM fills in itself (such as lead_score), its tags, 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 and total the number that match; request further pages until pagination.has_more is false.
Get a Contact#
GET /api/contacts/:idReturns 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/contactsRequest 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, position_level (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. Both must be records of your organization.
- status (string) — One of
lead,prospect,client,customer,inactive,team,partner,vendor. - lead_source (string) — Free text, for example
websiteorreferral. - 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) — Your own fields, by field key. Define them under Settings → Custom fields;
GET /api/custom-fields?entity_type=contactlists the keys. - contact_owner_id (string) — User ID of the owner, a member of your organization (
GET /api/userslists them). - manager_id, reports_to (string) — IDs of other contacts.
- workspace_id (string) — The workspace the contact belongs to (
GET /api/workspaces). Left out, the contact goes to your main workspace. - add_tags (array) — Tag names or IDs to put on the contact (see Tags below).
- next_follow_up_date, last_contacted_at (string) — ISO 8601 timestamps.
- is_primary (boolean), industry, company_size (string).
- sms_marketing_consent, whatsapp_opt_in (boolean) — Messaging consent flags, with sms_marketing_consent_source and whatsapp_opt_in_source (string) to say where the consent came from.
Fields the API does not write, such as lead_score, organization_id, or a misspelled name, are left out of the contact and named in the X-Ignored-Fields response header; they are not an error. An ID that is not a UUID, or that is not a record of your organization, is refused with 400 before anything is saved. The response is 201 with the created contact, its tags included.
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",
"add_tags": ["Website lead"],
"custom_fields": {
"plan_interest": "Growth"
}
}'Update a Contact#
PUT /api/contacts/:id
PATCH /api/contacts/:idUpdates an existing contact. Only include the fields you want to change — omitted fields are not modified. The response is the updated contact.
The two methods differ only in custom_fields. PUT replaces the whole custom_fields object with the one you send. PATCH merges the keys you send into the ones already there and removes a key you send as null. Sending "custom_fields": null with either method clears them all.
curl -X PATCH "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/:idPermanently deletes a contact. A contact deleted through the API does not go to Recently deleted, so this cannot be undone. Returns 404 ("Contact not found") when no contact with that ID exists in your organization.
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"
}Tags#
Every contact comes with its tags: a list of { "id", "name", "color" }, sorted by name, in the list, on a single contact, and in the answer to a create or an update. Customers and companies carry their tags the same way.
Add or Remove Tags#
Send add_tags or remove_tags when you create a contact (POST) or update one (PUT or PATCH): a list of tag names or tag IDs, or a single name.
- A name matches whatever its capitals, among the tags of the contact's workspace and the tags of every workspace. A name that is not a tag yet becomes a new tag of the contact's workspace.
- An ID must be a tag of the contact's workspace or of every workspace; any other ID is refused with
400before anything is saved. remove_tagsis applied first, thenadd_tags. A tag the contact already has, or one to remove that it does not have, is skipped, so sending the same request twice changes nothing.- A request with only these fields changes nothing else on the contact.
POST /api/bulktakes them on each item too.
curl -X PATCH "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 '{
"remove_tags": ["Client enquiry"],
"add_tags": ["Customer", "RW Roofing"]
}'List Contacts With a Tag#
Add tag to GET /api/contacts: a tag's name, whatever its capitals, or its ID. Only contacts carrying it are returned, page by page. A name no tag has returns an empty page. GET /api/customers and GET /api/companies take tag the same way.
curl -X GET "https://app.automatenexuscrm.com/functions/v1/api/contacts?tag=Client%20enquiry&limit=50" \
-H "Authorization: Bearer YOUR_API_KEY"Your Tags#
GET /api/tags lists your tags by name, each with its id, name, color, description, workspace_id (null for a tag of every workspace) and created_at. Add workspace_id to list the tags a record of that workspace can carry: its own and those of every workspace.
{
"data": [
{ "id": "7a1c0e52-3b9d-4f6a-8c21-5d4e3f2a1b0c", "name": "Client enquiry", "color": "#2c53f0", "description": null, "workspace_id": "e4b1c9a0-2d3f-4e5a-9b8c-7d6e5f4a3b2c", "created_at": "2026-10-20T16:05:00Z" }
],
"total": 1
}Search and Export by Tag#
GET /api/search also finds a contact by the name of a tag it carries. POST /api/export includes each contact's tags (in a CSV, their names in one cell, separated by semicolons) and takes "filters": { "tag": "Client enquiry" } to export only the contacts carrying that tag.
Bulk Create or Update Contacts#
POST /api/bulkCreate or update up to 200 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,
"ignored_fields": []
}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. ignored_fields names, by each record's position in data, the fields that were not written. A request with more than 200 records is refused with 400.
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/exportReturns 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/notesNotes 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: Thestatusvalue is not one of the allowed statuses listed above. - 400 mentioning the email format: The
emailvalue is not a valid email address. Send a valid address or leave the field out. - A field you sent did not change: Read the
X-Ignored-Fieldsresponse header. It names each field the API left out, for example a misspelled name or a field such aslead_scorethat the API does not write. - 400 "… not found in this organization": The
customer_id,company_id,contact_owner_id, orworkspace_idyou sent is not a record, member, or active workspace of the organization the API key belongs to. - 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 (GET /api/custom-fields?entity_type=contactlists them). APUTreplaces the whole object; usePATCHto change one key. - Contact not showing in the app: The app shows one workspace at a time. A contact created without
workspace_idis in your main workspace. - 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.