Connect with the API

Connect any tool to GuardenerAI with the API.

Any tool that can send an HTTP request can put leads and contacts into GuardenerAI. This is a connection you build with the public API, not a native integration: create a key with Read and write scope, search for the person by email, then create a new lead or update the one you found.

Not a native integration. Your tool sends JSON to your workspace’s API. Records land in GuardenerAI. Nothing is sent back automatically.

Start free → Developer API and MCP

What you need

  • An admin in your GuardenerAI workspace, to create the API key.
  • Your workspace address, https://YOUR-ORG.guardenerai.com. The API lives under /api/ on it.
  • A tool, script or service that can send HTTP requests with a custom header and a JSON body.

Step by step

  1. Create a key that can write

    In GuardenerAI open Settings, API keys. Under Create key, give it a name you will recognise later, set Role to Member (read and write records) and Scope to Read and write, then choose Create key. The key is shown once, so copy it into your tool’s secret store straight away.

  2. Look for the person first

    There is no upsert, so ask before you write. Filter leads by exact email. The match is case-sensitive, so lower-case emails before you send them. The answer is a page of results: if totalElements is above zero, content[0].id is the lead to update.

    Find a lead by email
    curl "https://YOUR-ORG.guardenerai.com/api/leads?filter=email:equals:dana%40fernhill.example"   --header "X-Api-Key: $GUARDENERAI_KEY"

  3. Create the lead if there was no match

    firstName, lastName and email are required. Put free text such as a form message in message, and record where the lead came from in sourceMedium and sourceCampaign. The source field only accepts codes from your workspace’s lead source list, so leave it out unless an admin has set one up. A new lead starts at status New.

    Create a lead
    curl -X POST "https://YOUR-ORG.guardenerai.com/api/leads"   --header "X-Api-Key: $GUARDENERAI_KEY"   --header "Content-Type: application/json"   --data '{
    "firstName": "Dana",
    "lastName": "Whitlock",
    "email": "dana@fernhill.example",
    "phone": "+1 555 0142",
    "company": "Fernhill Dental",
    "message": "Asked about moving off spreadsheets.",
    "sourceMedium": "web form",
    "sourceCampaign": "pricing page"
  }'

  4. Or update the lead you found

    An update is a PUT to /api/leads/{id}, and it replaces the whole record. Read the lead, change the fields you need, and send all of it back. Fields you leave out are cleared.

  5. Handle the answers

    201 means created and 200 means updated. 409 duplicate_blocked means one of your duplicate rules matched, and the body lists the matches: update one of them instead. 429 means you went over the rate limit: wait the one second in Retry-After and try again. 403 api_key_read_only means the key cannot write.

Before you rely on it

What to know about this connection.

With Any tool, with the API

  • Leads, persons, companies, opportunities, tasks, cases and notes can be written. Custom objects cannot be written through the API.
  • Searching filters built-in fields only, not custom fields.
  • A note cannot be attached to a lead. Put the text in the lead’s message field instead.
  • There is no CSV import through the API. Large one-off imports go through the importer in the app.

With every API connection

  • The key must have the Member role and Read and write scope. A Read only key gets a 403 on every write.
  • There is no upsert. Search for the record by email first, then create it or update the one you found.
  • There are no outbound webhooks. Data flows into GuardenerAI; nothing tells the other tool when a record changes, so anything reading back has to ask on a schedule.
  • Each key allows 10 requests per second. Above that the API answers 429 with Retry-After: 1, so wait a second and retry.
  • An update with PUT replaces the whole record. Send every field you want to keep, not only the one that changed.
  • If one of your duplicate rules blocks it, a create answers 409 duplicate_blocked with the matching records. Update the match instead of forcing a second copy.
Where it lands

The modules this feeds.

See also Zapier, Make, n8n and Claude and MCP agents. See every integration.

FAQ

Fair questions.

Is this a native integration?
No. GuardenerAI does not ship a connector for the tool you are using. You connect it yourself with the public API, and you own the connection.
Can GuardenerAI tell my other tool when a record changes?
No. There are no outbound webhooks, so data flows into GuardenerAI only. If another tool needs GuardenerAI data, it has to ask the API on a schedule.
Where is the full API reference?
Inside your workspace at /developers/, with an OpenAPI file and a Postman collection to download. It lists every endpoint your key can call.
Can I add to a person instead of a lead?
Yes. Persons have their own endpoints at /api/persons and work the same way: search by email, then create or update. Use leads for people who have not become customers yet.