Menu

Mattering Automations Agile CRM integration

Connect Agile CRM to Mattering Automations: contacts and companies, deals and tracks, tasks, events, notes and campaign enrollment as workflow steps, authenticated with your account domain, login email and REST API key.

The Mattering Automations Agile CRM integration puts 60 Agile CRM operations on your automation canvas: find, create and update contacts and companies, set tags and lead scores, open and move deals through tracks, create and close tasks, write notes and calendar events, and enroll or remove people from campaigns.

The credential is three values rather than one, because that is what Agile CRM needs before it can answer a call. Requests are HTTP Basic with your account email as the username and your REST API key as the password, and they go to your own subdomain, so the integration stores the domain, the email and the key together. Only the key is secret. The key is in Admin Settings under API and Analytics, and it is the first one listed, labelled for a REST client. Setup takes a few minutes and this guide walks through each step before the full node reference.

Two behaviours of this API shape everything downstream and are handled for you rather than left as surprises. Agile CRM answers in XML unless a request asks for JSON, so Mattering sends the JSON accept header on every call without exception. And Agile CRM documents no PATCH verb anywhere: partial updates arrive as PUT on some paths and POST on others, with merge, replace and create-if-missing behaviours hiding among them, so each node's description states which one it is.

Before you start

  • An Agile CRM account and the login email of the user whose key you will use. The email is the HTTP Basic username, so the key and the email belong together and swapping in a different address will not authenticate.
  • Your account subdomain, which is the part of your Agile CRM web address before agilecrm.com. It goes on the credential rather than on the nodes, so one connection means one account.
  • The REST API key from Admin Settings under API and Analytics. Take the first key on that screen, the one labelled as the API key for a REST client, rather than any of the others listed below it.
  • An idea of your daily call budget. Agile CRM publishes no rate limit in its REST documentation, so the ceiling is a plan property listed on its pricing page as a calls per day row. The lowest value in that row is 500 and by column position it belongs to the free plan, though the page renders its headers separately from the rows, so confirm the alignment on the pricing page before you design around it. Either way, a budget in the hundreds is small enough that a five minute polling schedule spends most of it on nothing.
  • A Mattering workspace with access to the Automations app.
  • Not required: any per-node domain or host. No node in this connector carries one.

Find your Agile CRM REST API key

Mattering authenticates to Agile CRM with HTTP Basic, where the username is a user's account email and the password is that user's REST API key. There are no scopes to choose and no OAuth app to register. The one thing worth deciding before you start is which user the key should belong to, because the key inherits that person's access and their name is what appears against anything the automation does.

Sign in to Agile CRM as the user whose key you want to use, and note the subdomain in your address bar. If the address is examplecorp.agilecrm.com, the domain value is examplecorp.
Open Admin Settings and go to API and Analytics.
Copy the first key on that screen, the one labelled as the API key for a REST client, and keep the signed-in user's email beside it.
Agile CRM publishes no scope model for REST keys, so a key that can read contacts is expected to reach the rest of the account as well. Choose the user accordingly rather than assuming the key is narrower than the person.
The key belongs with that user's email. If the account owner changes or the user is removed, the credential stops working, so use a long-lived operations account rather than an individual's personal login where you can.

Connect Agile CRM to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Agile CRM from the list.
Click Create new credential, fill in Domain, Email and API Key, then save.
Only the API key is stored as a secret in Google Secret Manager. The domain and email are ordinary configuration values, held so the request address and the Basic header can be built.
Click Test Connection. Mattering asks your account for a single contact, which is the cheapest safe read in the connector. An account with no contacts yet still passes, because an empty result proves the credential worked.
The two failure modes here look different for a reason. A 401 means the email or the key is wrong. A 404 means the domain is wrong and the request never reached an Agile CRM account at all.
Click Connect. All 60 Agile CRM nodes appear in your canvas palette.

Verify it works

Open any automation canvas and check the palette for an Agile CRM section listing the read and action nodes. Drop Agile CRM: List Contacts onto the canvas and run a test step. It needs nothing but a page size, and it is the same call the connection test makes, so it should return quickly. Note the shape while you are here, because it explains a lot of later wiring: the response is a plain array with no envelope, and a contact's first name, last name and email live inside its properties array rather than as top-level fields.

Now run Agile CRM: List Tracks, which is the most useful second step in this integration. It returns your pipelines with their milestone names as a comma separated string, and those spellings are what the deal nodes have to match, because Agile CRM compares milestone names case sensitively and accepts a wrong-case name without complaining. Keeping that output in front of you while you build the first deal workflow prevents the most common silent failure on this API.

If you want one more, drop Agile CRM: List Tasks and run it. Everything in this verify path is read-only, so it cannot reach any of the nine destructive nodes and is safe to re-run whenever you rotate the key. Each of these calls counts against your plan's daily API budget, which is worth remembering if that budget is a few hundred.

Node reference

60 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 23

Agile CRM: Filter Contacts and Companies

agile_crm_filter_contacts

Query contacts or companies with Agile's rule-based filter. This is the only documented way to select records by tag, by custom-field value or by an updated-time window - the plain list endpoint offers no filtering at all, so an incremental sync is built here. A rule is {LHS: field, CONDITION: operator, RHS: value}; contact_type picks PERSON or COMPANY. Sent form-encoded with the filter serialized as JSON text. Read-only despite the POST verb.

Agile CRM: Find Contact by Email

agile_crm_get_contact_by_email

Fetch the contact stored against an exact email address. This is an EXACT, CASE-SENSITIVE match, not a search - Alex@example.com and alex@example.com are different addresses to Agile. Returns 204 with an empty body when nothing matches, which is the idiomatic way to check whether a contact already exists before creating one.

Agile CRM: Find Contact by Phone Number

agile_crm_get_contact_by_phone

Fetch the contact stored against a phone number. Matching is exact on the stored string, so a number saved with punctuation will not be found by the digits alone. Returns 204 with an empty body when nothing matches. Useful for inbound-call workflows.

Agile CRM: Get Company

agile_crm_get_company

Fetch one company by id. Shares the /contacts/{id} path with Get Contact because Agile keeps both in one table; this node exists so the id field asks for a company. Returns 204 with an empty body when nothing matches.

Agile CRM: Get Contact

agile_crm_get_contact

Fetch one contact by its numeric id. Returns 204 with an empty body when no contact has that id, which surfaces as a successful node with empty data rather than as an error.

Agile CRM: Get Deal

agile_crm_get_deal

Fetch one deal by id, with its related contacts, owner and custom_data embedded.

Agile CRM: Get Task

agile_crm_get_task

Fetch one task by id, with its related contacts and owner embedded.

Agile CRM: List Campaigns

agile_crm_list_campaigns

List the account's marketing campaigns. Agile calls them workflows on the wire, which is why the campaign id a contact is enrolled with is called workflow-id. Each entry also carries a large 'rules' string holding the whole campaign definition as escaped JSON - useful to nobody downstream, and large, so read data[].id and data[].name and leave it alone. This is what fills the campaign pickers.

Agile CRM: List Companies

agile_crm_list_companies

List companies. Read-only despite the POST verb: Agile takes the paging parameters as form fields rather than on the query string. Same cursor convention as the contact list - the next-page cursor is grafted onto the LAST element of the returned array. A company's name lives inside the properties array as the SYSTEM property named 'name', not at the top level.

Agile CRM: List Contacts

agile_crm_list_contacts

List contacts in the account, newest-created first. Paged with page_size and cursor. Agile returns a plain JSON array with no envelope: the record count is grafted onto the FIRST element and the next-page cursor onto the LAST element, so a paging loop has to carry the cursor forward by hand. A contact's name and email live inside the properties array, not at the top level. This is also the connector's auth probe: an invalid credential answers 401 here.

Agile CRM: List Deals

agile_crm_list_deals

List every deal in the account, newest-created first, with the related contacts embedded. Same cursor convention as the contact list: the count rides on the first element and the next-page cursor on the last. Deals are the one CRM entity Agile returns with a top-level name, which is what lets the deal pickers elsewhere in this connector show readable labels.

Agile CRM: List Deals Grouped by Milestone

agile_crm_list_deals_by_pipeline_milestone

List a track's deals GROUPED BY MILESTONE - the board view, in other words. Pass pipeline_id 0 for the default track. Note the output shape: this returns an OBJECT keyed by milestone name, not an array, so downstream paths have to name a milestone literally (data.Prospect[].name) and a chart consumer will not find rows to fan out over. Use List Deals in Track when you want a flat list.

Agile CRM: List Deals for Contact

agile_crm_list_contact_deals

List the deals related to one contact. Unpaged: it returns whatever is linked to that contact.

Agile CRM: List Deals in Track

agile_crm_list_deals_by_pipeline

List the deals on one track, as a flat paged array. Two magic values are documented: pipeline_id 0 means the account's default track, and pipeline_id 1 means every deal on every track. Same cursor convention as the other lists.

Agile CRM: List Events

agile_crm_list_events

List calendar events inside a time window. BOTH bounds are mandatory and both are epoch SECONDS - there is no way to ask for all events, which is why nothing in this connector offers an event picker. Returns a flat array with the related contacts embedded.

Agile CRM: List Events for Contact

agile_crm_list_contact_events

List the events related to one contact, sorted by date. Takes no time window, so this is the way to see a contact's whole calendar history.

Agile CRM: List Notes for Contact

agile_crm_list_contact_notes

List the notes attached to one contact. Unpaged. This is also what fills the note picker on Delete Note from Contact.

Agile CRM: List Notes for Deal

agile_crm_list_deal_notes

List the notes attached to one deal. Unpaged.

Agile CRM: List Tasks

agile_crm_list_tasks

List every task in the account, newest-created first, with related contacts and the task owner embedded. This endpoint documents no parameters at all - no paging, no filter - so use List Tasks by Filter when the account has many tasks. It is what fills the task picker elsewhere in this connector.

Agile CRM: List Tasks by Filter

agile_crm_list_tasks_filtered

List tasks filtered by category, status or priority, and optionally limited to pending ones. The pairing is strict: the criteria you choose decides which values type may take, and a mismatched pair returns nothing rather than an error. This also covers 'what is due' - set pending true - which is why the separate pending-tasks-by-days endpoint is not built as its own node. Paged with page_size and cursor, same cursor convention as the other lists.

Agile CRM: List Tasks for Contact

agile_crm_list_contact_tasks

List the tasks related to one contact, most recent first. Unpaged.

Agile CRM: List Tracks

agile_crm_list_tracks

List the account's tracks - Agile's word for deal pipelines - each with its milestones. Read this before writing any deal: milestones come back as ONE COMMA-SEPARATED STRING per track ("Open,New,Prospect,Proposal,Won,Lost"), and Agile matches milestone names case-sensitively, so this is where the exact spelling comes from. It is also what fills the track pickers on the deal nodes.

Agile CRM: Search Contacts and Companies

agile_crm_search

Free-text search across a contact's or company's default fields and any custom fields marked searchable in Agile. All three parameters are mandatory per the vendor's docs, including the PERSON / COMPANY switch - one call cannot return both. This endpoint has no cursor, so page_size is the whole result set.

Action nodes 37

Agile CRM: Add Tags by Email

agile_crm_add_tags_by_email

Find the contact with this exact email address and add tags to it, without needing the contact id first. Additive. Sent form-encoded, with the tag list serialized as JSON text into the form value - supply a real list here and the connector does that for you. Answers 204 with no body, so it returns no contact to chain from.

Agile CRM: Add Tags to Contact

agile_crm_add_contact_tags

Add one or more tags to a contact by id. Additive: existing tags are kept. Tag names are case-sensitive, must start with a letter, and may only contain letters, digits, underscores and spaces. Reversible with Remove Tags from Contact. Returns the updated contact.

Agile CRM: Adjust Contact Score by Email

agile_crm_add_contact_score_by_email

ADJUST a contact's lead score by a delta, keyed on email. This adds to the existing score rather than replacing it, and a negative number subtracts - which is what a behavioural scoring workflow wants. Use Set Contact Lead Score when you want an absolute value instead. Sent form-encoded. Returns the updated contact.

Agile CRM: Bulk Delete Deals

agile_crm_bulk_delete_deals

PERMANENTLY delete several deals at once, by id. Same irreversibility as Delete Deal, multiplied: there is no trash and no restore endpoint, and no partial-failure report - the call answers 200 for the batch. Wire-shape warning: Agile's own documentation contradicts itself here, sending a raw JSON body under a form-encoded content type. This node reproduces the documented request exactly rather than guessing, so if it misbehaves that is the first thing to check.

Agile CRM: Bulk Delete Notes

agile_crm_delete_notes_bulk

PERMANENTLY delete note records by id. Agile documents this under the deal-notes section but the path is the contacts one, and it takes note ids either way. There is no trash and no restore endpoint, and it answers 204 with an empty body, so nothing here can bring a note back. Sent form-encoded with the id list serialized as JSON text.

Agile CRM: Change Contact Owner

agile_crm_change_contact_owner

Reassign a contact to a different Agile user, named by that user's email address. Both fields are mandatory. If no user in the account has that email, Agile answers 200 with a message saying the user does not exist rather than with an error status, so check the body rather than the status code. Reversible by calling it again with the previous owner.

Agile CRM: Create Company

agile_crm_create_company

Create a company. Agile stores companies in the same table as contacts, so this posts to the contacts endpoint with type set to COMPANY - the node sends that for you. The company's name goes in as the SYSTEM property named 'name'. Lead score and star value do not apply to companies. No duplicate check is documented, so a retry creates a second company.

Agile CRM: Create Contact

agile_crm_create_contact

Create a person. Agile has no documented duplicate check on this endpoint, so calling it twice with the same email creates two contacts; use Find Contact by Email first if a workflow can retry. first_name is mandatory inside properties. Do not send null values: Agile's docs say to omit the field or send an empty value instead. Returns the created contact with its new id. A 406 means the account's contact limit is reached.

Agile CRM: Create Contact Note

agile_crm_create_note

Create a note and attach it to one or more contacts in the same call. Both subject and description are mandatory. Returns the note with its new id, which is what makes this the note node to use in a chain - there is no update endpoint for a contact note, so a correction means deleting and re-creating.

Agile CRM: Create Deal

agile_crm_create_deal

Create a deal. This endpoint is an UPSERT, not a pure create: Agile's docs state that if the posted data includes a valid deal id, that deal is UPDATED instead - so never template an id in here unless you mean it. name and expected_value are mandatory. The milestone must match a milestone on the chosen track exactly, including case, or the deal is created but does not appear in the milestone view. Returns the created deal with its new id.

Agile CRM: Create Deal Note

agile_crm_create_deal_note

Create a note and attach it to one or more deals. Deal notes are a separate surface from contact notes and, unlike them, can be edited afterwards with Update Deal Note.

Agile CRM: Create Deal for Contact by Email

agile_crm_create_deal_for_contact_email

Create a deal already linked to the contact with this email address, saving a lookup. If no contact has that address Agile creates NO deal at all - so a silent no-op here means the email did not match, not that the deal failed. Same upsert caveat as Create Deal: a valid deal id in the body updates that deal instead.

Agile CRM: Create Event

agile_crm_create_event

Create a calendar event. title, start and end are mandatory, and the times are epoch SECONDS. Colour is Agile's priority signal rather than decoration: red for high, #36C for normal, green for low. Returns the created event with its new id.

Agile CRM: Create Task

agile_crm_create_task

Create a task. subject, type, priority_type and due are the mandatory fields, and all the enumerated values are CASE-SENSITIVE - Agile takes MEETING, not Meeting. due is epoch SECONDS. Returns the created task with its new id.

Agile CRM: Create Task for Contact by Email

agile_crm_create_task_for_contact_email

Create a task already linked to the contact with this email address, saving a lookup when a webhook only carries an email. Same mandatory fields and case-sensitive vocabularies as Create Task.

Agile CRM: Create Track

agile_crm_create_track

Create a deal track with its milestones. Two documented rules: the name must not be "Default", and milestones go in as one comma-separated string, not a list, with every milestone's first letter capitalised. Returns the created track with its new id.

Agile CRM: Delete Company

agile_crm_delete_company

PERMANENTLY delete a company. Agile's REST documentation describes no trash, restore or undelete endpoint, and answers 204 with an empty body, so nothing in this connector can bring the record back. What happens to the people whose contact_company_id pointed at it is not documented, so check the affected contacts afterwards.

Agile CRM: Delete Contact

agile_crm_delete_contact

PERMANENTLY delete a contact. Agile's REST documentation describes no trash, recycle bin, restore or undelete endpoint for contacts, and returns 204 with an empty body, so nothing in this connector can bring the record back - its notes, tasks, deals links and property history go with it. Whether the Agile web UI keeps a copy is not stated in the API docs, so do not count on one. Read the contact first if you need to keep anything.

Agile CRM: Delete Deal

agile_crm_delete_deal

PERMANENTLY delete a deal. Agile's REST documentation describes no trash, restore or undelete endpoint for deals, and answers 204 with an empty body, so nothing in this connector can bring it back - its notes and its links to contacts go with it. Agile does document an 'archived' flag on the deal object, so if you only want the deal out of the way, set archived through Update Deal instead of deleting it.

Agile CRM: Delete Event

agile_crm_delete_event

PERMANENTLY delete a calendar event. Agile's REST documentation describes no trash, restore or undelete endpoint, and answers 204 with an empty body, so nothing in this connector can bring it back.

Agile CRM: Delete Note from Contact

agile_crm_delete_contact_note

Detach a note from a contact. Be precise about what this does: Agile describes it as removing the RELATIONSHIP between the note and the contact rather than as deleting the note record, and it answers 204 with an empty body. Either way it is not recoverable through this connector, because Agile publishes no endpoint that re-links an existing note to a contact - the only way back is to create a new note with the same text. Use Bulk Delete Notes to remove note records by id.

Agile CRM: Delete Task

agile_crm_delete_task

PERMANENTLY delete a task. Agile's REST documentation describes no trash, restore or undelete endpoint for tasks, so nothing in this connector can bring it back. If what you want is to close the task rather than erase it, use Update Task with status COMPLETED instead - that keeps the history.

Agile CRM: Delete Track

agile_crm_delete_track

PERMANENTLY delete a track. Agile documents no restore endpoint, so the track itself cannot be recovered through this connector - and it does not document what happens to the deals whose pipeline_id pointed at it, which is the more expensive unknown. Re-creating a track with the same name gives it a NEW id, so any deal still carrying the old id stays orphaned. Move the deals to another track first.

Agile CRM: Enroll Contact in Campaign

agile_crm_enroll_contact_in_campaign

Add a contact to a marketing campaign, keyed on the contact's email address. This STARTS REAL OUTBOUND ACTIVITY - the campaign's emails and actions begin running against that contact - so it is reversible in the record-keeping sense (Remove Contact from Campaign unsubscribes them) but not in the sense that a sent email can be recalled. Sent form-encoded; the campaign id travels as the hyphenated key workflow-id, which this node handles for you.

Agile CRM: Remove Contact from Campaign

agile_crm_remove_contact_from_campaign

Unsubscribe a contact from a campaign, stopping any further campaign steps for them. Reversible - Enroll Contact in Campaign puts them back, though the campaign restarts rather than resuming. Nothing is deleted: neither the contact nor the campaign is affected beyond the subscription. Answers 204 with an empty body.

Agile CRM: Remove Contacts from Deal

agile_crm_remove_deal_contacts

Unlink specific contacts from a deal, leaving the deal's other contacts and every other field alone. This is the targeted counterpart to Update Deal, whose contact_ids replaces the whole list. Only the link is removed - no contact and no deal is deleted - and it is reversible by adding the ids back through Update Deal. Returns the updated deal.

Agile CRM: Remove Tags by Email

agile_crm_remove_tags_by_email

Find the contact with this exact email address and remove the named tags from it. Names that are not on the contact are ignored, and only the tag link is removed, never the contact. Reversible with Add Tags by Email. Sent form-encoded with the tag list serialized as JSON text. Answers 204 with no body.

Agile CRM: Remove Tags from Contact

agile_crm_remove_contact_tags

Remove one or more tags from a contact or company by id. Agile matches each name against the record's tag list and removes the matches; names that are not present are ignored. Only the tag link is removed, never the contact. Reversible with Add Tags to Contact. Returns the remaining tag list.

Agile CRM: Set Contact Lead Score

agile_crm_update_contact_lead_score

SET a contact's lead score to an absolute value, by id. This replaces the score rather than adjusting it; use Adjust Contact Score by Email when you want to add or subtract. No other field on the contact is affected. Returns the updated contact.

Agile CRM: Update Company Properties

agile_crm_update_company_properties

Partial update of a company's properties, on the same endpoint the contact update uses - this node exists so the id field asks for a company rather than a person. A MERGE: properties you do not name are left untouched, and no property can be deleted through it. Returns the updated company.

Agile CRM: Update Contact Properties

agile_crm_update_contact_properties

Partial update of a contact's properties. This is a MERGE, not a replace: properties you do not name are left untouched. Three limits are documented and matter. It CANNOT DELETE a property. It CANNOT change lead score, star value or tags (those have their own nodes). And where a multi-value SYSTEM field already has the subtype you send, the existing value is OVERWRITTEN rather than a second value being added, so sending phone/work replaces the work phone. Returns the updated contact.

Agile CRM: Update Deal

agile_crm_update_deal

Partial update of a deal: fields you leave blank are not sent and are not changed. Two things behave as REPLACE rather than merge, and both bite. contact_ids REPLACES the deal's contact links with exactly the list you send, so sending one id unlinks the others - use Remove Contacts from Deal for a targeted removal. Sending a milestone in the wrong case is accepted but hides the deal from the milestone view. Returns the updated deal.

Agile CRM: Update Deal Note

agile_crm_update_deal_note

Edit an existing deal note. The note id is mandatory; the endpoint is the same URL as the create, with PUT. Send deal_ids as well, because the documented request carries them on the update too. Contact notes have no equivalent - this asymmetry is Agile's, not the connector's.

Agile CRM: Update Event

agile_crm_update_event

Update a calendar event. Read the id warning before wiring this: Agile's docs state that without an id in the body the call is treated as a NEW EVENT, so a blank id field silently creates a duplicate instead of failing. The update goes to the same /events URL as the create, with PUT. Send the full event - title, start and end are mandatory here too.

Agile CRM: Update One Contact Property by Email

agile_crm_update_contact_property_by_email

Add or overwrite ONE property on the contact with this email address. A POST that behaves as a partial update: it touches only the named property and leaves the rest of the contact alone. Note the documented hazard - Agile's docs state that if there is no matching contact it treats the call as a NEW CONTACT, so a blank or mistyped email address silently creates a record instead of failing. The email goes on the query string and the single property object is the JSON body. Returns the updated contact.

Agile CRM: Update Task

agile_crm_update_task

Partial update of a task: fields left blank are not sent and are not changed. This is also how a workflow closes a task - set status COMPLETED and is_complete true. One replace-not-merge trap: contacts REPLACES the task's related contacts with exactly the list you send. Returns the updated task.

Agile CRM: Update Track

agile_crm_update_track

Update a track's name or milestones. Read the id warning first: Agile's docs state that without an id in the body the call is treated as a NEW TRACK, so a blank id silently creates a duplicate track instead of failing. Renaming a milestone does not migrate the deals sitting in it - Agile matches deals to milestones by name, so a rename can orphan deals from the board view. Check the affected deals afterwards.

Using the integration

On the automation canvas

Agile CRM nodes chain with every other node in Mattering. A form submission can look someone up with Agile CRM: Find Contact by Email and then either create or update them, a nightly schedule can read Agile CRM: List Deals in Track and open a task on anything that has not moved, and a support conversation elsewhere can land in the record with Agile CRM: Create Contact Note. Pickers do the id wiring where the vendor's payloads allow it: deals, tracks, tasks, campaigns, and a contact's notes, which chain from the contact already chosen on the node.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same surface. A comfortable agent surface is the read nodes plus the reversible writes: find a contact, read the deals on a track, list open tasks, write a note, open a follow-up. We could not find an MCP server published by Agile CRM itself, and its developer documentation is a REST reference that mentions none, so this integration is how Agile CRM reaches an assistant today rather than one option among several. Treat that as a finding rather than a permanent state of the world. Keep the nine destructive nodes and campaign enrollment behind conditions or approval steps: enrollment starts real outbound email to a real person.

One connection is one Agile CRM account

The domain lives on the credential rather than on the nodes, because an Agile CRM key is minted inside one account and means nothing against another subdomain. The practical effects are worth stating. No node in this connector carries a domain field, so there is no way for half a workflow to point at the wrong account. If you run more than one Agile CRM account, connect one credential per account and select the right one on the nodes. And because the address is built from the credential, the connection test is not a fixed URL: Mattering assembles it from your domain, which is why a wrong domain shows up as a 404 rather than as an authentication error.

How partial updates actually behave

There is no PATCH verb in this API, and the three behaviours that replace it are the main source of surprise. Merging: Agile CRM: Update Contact Properties touches only the properties you name and leaves the rest alone, but it cannot delete a property, it cannot change lead score, star value or tags, since each of those has its own node, and a second value of the same subtype overwrites rather than adds, so sending another work phone number replaces the work number rather than appending one. Replacing: the contact list on Agile CRM: Update Deal and on Agile CRM: Update Task is overwritten wholesale, so sending one id unlinks every other contact, which is exactly why Agile CRM: Remove Contacts from Deal exists as its own targeted node. Creating: four endpoints make a new record when the id is missing rather than failing, covering deals, events, tracks and the single-property contact update. Every affected node marks the id required so a run stops before the request goes out.

Reading records, and the two shapes that catch people

Agile CRM wraps nothing, so a list response is a plain top-level array and a downstream path reads straight into it. Two shapes deviate. First, paging: the total count is grafted onto the first element of the array and the cursor for the next page onto the last one, rather than living in an envelope, and the absence of a cursor is how you know you have reached the end, so a paging loop has to carry the cursor forward itself. Second, Agile CRM: List Deals Grouped by Milestone returns an object keyed by milestone name rather than an array, so a path has to name a milestone literally instead of fanning out over rows. There is also a status convention worth building conditions around: several reads answer with an empty success rather than a 404 when nothing matches, including the contact lookups by id, email and phone, so an empty result is the normal not-found signal rather than an error.

Names, pickers, and why some fields are free text

A contact's first name, last name and email, and a company's name, live inside a properties array as name and value pairs rather than as top-level fields. That is the single most consequential shape in this API. It is why a consumer reads a name out of the array rather than from a plain field, and it is why the contact and company id fields are free text: a picker built from the listers would show a dropdown of bare numeric ids, since there is nothing addressable to label each row with. Pickers are declared everywhere the payload supports them, which is deals by name with their milestone, tracks by name with their milestones, tasks by subject grouped by type, campaigns by name, and a contact's notes by subject. Milestone names are free text for the same reason: a track returns its stages as one comma separated string, so read the spelling from Agile CRM: List Tracks and copy it exactly.

The nine destructive nodes, and the softer alternatives

Agile CRM's REST documentation describes no trash, restore or undelete endpoint for any entity, so the honest claim at this scope is that nothing deleted through this connector can be recovered through this connector. Whether the web interface keeps a copy is not something the API documentation states, so no claim is made either way. The nine are Agile CRM: Delete Contact, Agile CRM: Delete Company, Agile CRM: Delete Deal, Agile CRM: Bulk Delete Deals, Agile CRM: Delete Task, Agile CRM: Delete Event, Agile CRM: Delete Track, Agile CRM: Delete Note from Contact and Agile CRM: Bulk Delete Notes. Two have gentler substitutes that keep the history: a deal has an archived flag you can set through Agile CRM: Update Deal, and a task can be moved to completed status through Agile CRM: Update Task. Two carry extra risk worth planning around. Deleting a track is not just the track: Agile CRM does not document what happens to deals whose pipeline pointed at it, and recreating a track with the same name produces a new id, so move deals off first. And deleting a company leaves the people who referenced it in an undocumented state, so check the affected contacts afterwards.

Campaigns reach real people

Agile CRM: List Campaigns reads your campaigns and Agile CRM: Enroll Contact in Campaign puts a person into one by email. It is not flagged destructive, because the record keeping is reversible, but it is the node in this connector most likely to do something you cannot take back: it starts genuine outbound marketing activity against a real person, and no API call recalls an email that has already been sent. Agile CRM: Remove Contact from Campaign unsubscribes them from future sends, and enrolling again restarts the campaign from the beginning rather than resuming it. Gate enrollment behind a condition that checks consent and a deduplication step, particularly in any workflow that can retry.

Troubleshooting

Test Connection fails with a 401
A 401 is about the pair of values rather than the address: Agile CRM documents this status as the username and password fields being wrong. The username is the account email of the user the key belongs to, not an API identifier, so confirm the email matches the user whose key you copied. Then re-copy the key from Admin Settings under API and Analytics, taking the first one, the one labelled for a REST client, and watch for whitespace on the paste. If the user has been removed from the account, the key goes with them.
Every node returns 404, even ones that should exist
A 404 across the board almost always means the domain is wrong, not that the path is. The request is addressed to your own subdomain, so a typo there resolves to nothing and the call never reaches an Agile CRM account, which is a different failure from a rejected credential. Open the credential and check the Domain field holds only the subdomain, the part before agilecrm.com, with no protocol, no dots and no trailing path. A single node returning 404 while others work is a different problem and usually means the record id no longer exists.
A node ran twice and created a duplicate record
Two separate causes, both documented. Contact creation has no duplicate check, so a retried run makes a second contact for the same person: put Agile CRM: Find Contact by Email in front of it and branch. The nastier one is create-on-missing-id, where four endpoints make a brand new record when the id is absent rather than failing, covering deals, events, tracks and the single-property contact update. A template that resolves to an empty string therefore does not error, it silently creates something. Those nodes mark the id required so the run stops first, but check any workflow that fills an id from an earlier step's output and can legitimately produce nothing.
A deal was created but does not appear in the milestone view
The milestone name is almost certainly the wrong case. Agile CRM matches milestone names case sensitively and accepts a name that does not match without raising an error, which leaves the deal created and invisible where you expected it. Run Agile CRM: List Tracks and copy the spelling from the milestones string exactly as it comes back. The same case sensitivity applies more widely than deals: email lookups, tag names, and the fixed vocabularies for task types, priorities and statuses are all case sensitive.
An update unlinked contacts that were already on the record
That is the replace behaviour hiding inside a partial update. The contact list on Agile CRM: Update Deal and on Agile CRM: Update Task is overwritten wholesale, so sending a single id removes every other contact from the record rather than adding to them. If you meant to detach one specific contact from a deal, use Agile CRM: Remove Contacts from Deal, which is built for exactly that. If you meant to add someone, read the current list first and send the full set.
A node returns success with an empty body and nothing to chain from
This is normal on this API in two different situations. Several reads answer with an empty success rather than a 404 when nothing matches, including the contact lookups by id, by email and by phone, so an empty result is a not-found signal and a condition should test for content rather than for failure. And several writes return no body at all, including the tag add and remove by email and the bulk note delete, so there is nothing to chain from after them. Where a workflow needs the new record's id, use the node that returns the object, such as Agile CRM: Create Contact Note rather than an email-addressed variant.
Dates land in the far future or in 1970
Agile CRM takes epoch SECONDS, not milliseconds, on due dates, close dates and event start and end times. A millisecond timestamp passed straight through from another system lands tens of thousands of years out, and a value divided twice lands near 1970. Convert once, in the step before the Agile CRM node, and keep the convention in your workflow templates. While you are checking date handling, note that Agile CRM: List Events requires a start and end window rather than defaulting to anything.
The response looks like a string of XML rather than data
Agile CRM's default response format is XML, and JSON only comes back when a request asks for it. Mattering sends the JSON accept header on every call, so a node returning raw XML text means that header did not reach Agile CRM, which points at a proxy or a rewritten request rather than at the connector's configuration. The connection test checks for this deliberately: a 200 whose body is not JSON fails it with a message saying so, rather than passing and leaving the problem to surface later as an unparseable value halfway through a workflow.
Change Contact Owner returned success but the owner did not change
Agile CRM answers this call with a 200 and a message saying the user does not exist when the owner email is unknown, rather than returning an error status. So the status code is not enough: read the body. Confirm the owner email exactly matches a user in the account, remembering that email matching here is case sensitive. There is no users endpoint in this API, which is also why the owner fields on these nodes are free text rather than pickers, and why an owner typo is easy to make and easy to miss.
Workflows start failing partway through the day
Check the plan's daily API budget before looking anywhere else. Agile CRM publishes no rate limit in its REST documentation and documents no 429, so exhausting a daily plan quota does not present the way a throttle would. The pricing page lists a calls per day row whose lowest value is 500. A five minute polling schedule alone is 288 calls before any real work, so move triggers from polling to events where you can, widen schedules, and prefer one list call with a page size over many single-record lookups.

Agile CRM is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products