Our most capable AI model is now on the Scale plan. See plans

Docs/API referencev1

iGentrix API

Read and manage your agents, conversations, leads and data lists.

Authentication. Create an API key in Settings → API keys and send it as Authorization: Bearer <key>. Keys are either read-only or read & write, and reach all your agents or only the ones you choose.

Rate limits. Each key can make 120 requests per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds); a 429 also carries Retry-After.

Pagination. List endpoints return { data, nextCursor }. Pass nextCursor as cursor to get the next page.

Errors. Errors return { error: { code, message } } with a stable code, such as not_found, validation_error (with details), insufficient_scope, plan_limit or rate_limited.

Webhooks. To be notified of changes instead of polling, add a webhook endpoint under an agent's Developers → Webhooks, or subscribe one with POST /agents/{agentId}/webhook-endpoints.

Base URL https://www.igentrix.com/api/v1

API key

Check the key you're calling with.

Get the current API key

GET/keyAny key

Returns the key's scope and rate limit. Useful for checking a key works.

200 response · ApiKey
  • idstringrequired

    Opaque identifier

  • namestringrequired
  • access"read" | "write"required
  • allAgentsbooleanrequired
  • agentIdsstring[]required

    Agents the key can reach when allAgents is false

  • messagingbooleanrequired

    Whether the key may post customer messages for custom channels (messages:write)

  • expiresAtstring | nullrequired

    ISO 8601, UTC

  • rateLimitobjectrequired
    • requestsintegerrequired· -9007199254740991–9007199254740991
    • windowSecondsintegerrequired· -9007199254740991–9007199254740991
curl "https://www.igentrix.com/api/v1/key" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data }. Errors: 401429

Agents

Your AI agents and their configuration.

List agents

GET/agentsAny key

Agents the key can reach, newest first.

Query parameters

  • limitinteger· 1–100· default 25

    Items per page, 1–100

  • cursorstring· max 200 chars

    nextCursor from the previous page

200 response · list of Agent
  • idstringrequired

    Opaque identifier

  • namestringrequired
  • descriptionstringrequired
  • modelstringrequired
  • templateTypestringrequired
  • systemInstructionstringrequired
  • userTypesInstructionstringrequired
  • interactionsInstructionstringrequired
  • dataInstructionstringrequired
  • toneInstructionstringrequired
  • guardrailsInstructionstringrequired
  • adminSystemInstructionstringrequired
  • temperaturenumber | nullrequired
  • maxOutputTokensinteger | nullrequired
  • topPnumber | nullrequired
  • topKinteger | nullrequired
  • toolsobjectrequired
    • googleSearchbooleanrequired
    • codeExecutionbooleanrequired
    • urlContextbooleanrequired
    • emailbooleanrequired
    • captureLeadsbooleanrequired
    • scheduledTasksbooleanrequired
  • notificationEmailstring | nullrequired
  • channelsobjectrequired

    Which customer channels are switched on. Configure channels in the dashboard.

    • widgetbooleanrequired
    • whatsappbooleanrequired
    • emailbooleanrequired
  • leadTagsobject[]required

    Tags leads can carry; use the ids in a lead's tags

    • idstringrequired

      Opaque identifier

    • namestringrequired
    • color"gray" | "red" | "orange" | "amber" | "green" | "teal" | "blue" | "violet" | "pink"required
  • leadFieldsobject[]required

    Custom fields leads can carry, keyed by key in a lead's customFields

    • keystringrequired
    • labelstringrequired
    • type"text" | "number" | "date" | "select"required
    • optionsstring[]
  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl "https://www.igentrix.com/api/v1/agents" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data: [...], nextCursor }. Errors: 401422429

Create an agent

POST/agentsRead & write key

Needs a read & write key scoped to all agents. Counts towards your plan's agent limit.

Request body

  • namestringrequired· max 200 chars
  • descriptionstring· max 1000 chars
  • model"gemini-3.8-flash" | "gemini-3.5-flash" | "gemini-3.5-flash-lite"
  • systemInstructionstring· max 20000 chars
  • userTypesInstructionstring· max 20000 chars
  • interactionsInstructionstring· max 20000 chars
  • dataInstructionstring· max 20000 chars
  • toneInstructionstring· max 20000 chars
  • guardrailsInstructionstring· max 20000 chars
  • adminSystemInstructionstring· max 20000 chars
  • temperaturenumber· 0–2· default 0.1
  • maxOutputTokensinteger· 1–65536· default 8192
  • topPnumber· 0–1· default 0.85
  • topKinteger· 1–100· default 40
  • notificationEmailstring | null
  • templateType"custom" | "restaurant" | "booking" | "faq" | "catalog"· default "custom"
  • toolsobject
    • googleSearchboolean
    • codeExecutionboolean
    • urlContextboolean
    • emailboolean

      Let the agent email notificationEmail

    • captureLeadsboolean
    • scheduledTasksboolean

      Let admins ask the agent to do things on a schedule

201 response · Agent
  • idstringrequired

    Opaque identifier

  • namestringrequired
  • descriptionstringrequired
  • modelstringrequired
  • templateTypestringrequired
  • systemInstructionstringrequired
  • userTypesInstructionstringrequired
  • interactionsInstructionstringrequired
  • dataInstructionstringrequired
  • toneInstructionstringrequired
  • guardrailsInstructionstringrequired
  • adminSystemInstructionstringrequired
  • temperaturenumber | nullrequired
  • maxOutputTokensinteger | nullrequired
  • topPnumber | nullrequired
  • topKinteger | nullrequired
  • toolsobjectrequired
    • googleSearchbooleanrequired
    • codeExecutionbooleanrequired
    • urlContextbooleanrequired
    • emailbooleanrequired
    • captureLeadsbooleanrequired
    • scheduledTasksbooleanrequired
  • notificationEmailstring | nullrequired
  • channelsobjectrequired

    Which customer channels are switched on. Configure channels in the dashboard.

    • widgetbooleanrequired
    • whatsappbooleanrequired
    • emailbooleanrequired
  • leadTagsobject[]required

    Tags leads can carry; use the ids in a lead's tags

    • idstringrequired

      Opaque identifier

    • namestringrequired
    • color"gray" | "red" | "orange" | "amber" | "green" | "teal" | "blue" | "violet" | "pink"required
  • leadFieldsobject[]required

    Custom fields leads can carry, keyed by key in a lead's customFields

    • keystringrequired
    • labelstringrequired
    • type"text" | "number" | "date" | "select"required
    • optionsstring[]
  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl -X POST "https://www.igentrix.com/api/v1/agents" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

Returns 201 with { data }. Errors: 401403422429

Get an agent

GET/agents/{agentId}Any key

Path parameters

  • agentIdstringrequired

    The agent's id

200 response · Agent
  • idstringrequired

    Opaque identifier

  • namestringrequired
  • descriptionstringrequired
  • modelstringrequired
  • templateTypestringrequired
  • systemInstructionstringrequired
  • userTypesInstructionstringrequired
  • interactionsInstructionstringrequired
  • dataInstructionstringrequired
  • toneInstructionstringrequired
  • guardrailsInstructionstringrequired
  • adminSystemInstructionstringrequired
  • temperaturenumber | nullrequired
  • maxOutputTokensinteger | nullrequired
  • topPnumber | nullrequired
  • topKinteger | nullrequired
  • toolsobjectrequired
    • googleSearchbooleanrequired
    • codeExecutionbooleanrequired
    • urlContextbooleanrequired
    • emailbooleanrequired
    • captureLeadsbooleanrequired
    • scheduledTasksbooleanrequired
  • notificationEmailstring | nullrequired
  • channelsobjectrequired

    Which customer channels are switched on. Configure channels in the dashboard.

    • widgetbooleanrequired
    • whatsappbooleanrequired
    • emailbooleanrequired
  • leadTagsobject[]required

    Tags leads can carry; use the ids in a lead's tags

    • idstringrequired

      Opaque identifier

    • namestringrequired
    • color"gray" | "red" | "orange" | "amber" | "green" | "teal" | "blue" | "violet" | "pink"required
  • leadFieldsobject[]required

    Custom fields leads can carry, keyed by key in a lead's customFields

    • keystringrequired
    • labelstringrequired
    • type"text" | "number" | "date" | "select"required
    • optionsstring[]
  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl "https://www.igentrix.com/api/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data }. Errors: 401404429

Update an agent

PATCH/agents/{agentId}Read & write key

Only the fields you send change. Sends an agent.updated webhook event.

Path parameters

  • agentIdstringrequired

    The agent's id

Request body

  • namestring· max 200 chars
  • descriptionstring· max 1000 chars
  • model"gemini-3.8-flash" | "gemini-3.5-flash" | "gemini-3.5-flash-lite"
  • systemInstructionstring· max 20000 chars
  • userTypesInstructionstring· max 20000 chars
  • interactionsInstructionstring· max 20000 chars
  • dataInstructionstring· max 20000 chars
  • toneInstructionstring· max 20000 chars
  • guardrailsInstructionstring· max 20000 chars
  • adminSystemInstructionstring· max 20000 chars
  • temperaturenumber· 0–2
  • maxOutputTokensinteger· 1–65536
  • topPnumber· 0–1
  • topKinteger· 1–100
  • notificationEmailstring | null
  • toolsobject
    • googleSearchboolean
    • codeExecutionboolean
    • urlContextboolean
    • emailboolean

      Let the agent email notificationEmail

    • captureLeadsboolean
    • scheduledTasksboolean

      Let admins ask the agent to do things on a schedule

200 response · Agent
  • idstringrequired

    Opaque identifier

  • namestringrequired
  • descriptionstringrequired
  • modelstringrequired
  • templateTypestringrequired
  • systemInstructionstringrequired
  • userTypesInstructionstringrequired
  • interactionsInstructionstringrequired
  • dataInstructionstringrequired
  • toneInstructionstringrequired
  • guardrailsInstructionstringrequired
  • adminSystemInstructionstringrequired
  • temperaturenumber | nullrequired
  • maxOutputTokensinteger | nullrequired
  • topPnumber | nullrequired
  • topKinteger | nullrequired
  • toolsobjectrequired
    • googleSearchbooleanrequired
    • codeExecutionbooleanrequired
    • urlContextbooleanrequired
    • emailbooleanrequired
    • captureLeadsbooleanrequired
    • scheduledTasksbooleanrequired
  • notificationEmailstring | nullrequired
  • channelsobjectrequired

    Which customer channels are switched on. Configure channels in the dashboard.

    • widgetbooleanrequired
    • whatsappbooleanrequired
    • emailbooleanrequired
  • leadTagsobject[]required

    Tags leads can carry; use the ids in a lead's tags

    • idstringrequired

      Opaque identifier

    • namestringrequired
    • color"gray" | "red" | "orange" | "amber" | "green" | "teal" | "blue" | "violet" | "pink"required
  • leadFieldsobject[]required

    Custom fields leads can carry, keyed by key in a lead's customFields

    • keystringrequired
    • labelstringrequired
    • type"text" | "number" | "date" | "select"required
    • optionsstring[]
  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl -X PATCH "https://www.igentrix.com/api/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Returns 200 with { data }. Errors: 401403404422429

Delete an agent

DELETE/agents/{agentId}Read & write key

Permanently deletes the agent with its conversations, leads, data lists and knowledge.

Path parameters

  • agentIdstringrequired

    The agent's id

200 response · Deleted
  • idstringrequired

    Opaque identifier

  • deletedtruerequired
curl -X DELETE "https://www.igentrix.com/api/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data }. Errors: 401403404429

Conversations

Conversations customers have with an agent and their messages, plus escalating and sending messages for custom channels.

List conversations

GET/agents/{agentId}/conversationsAny key

Most recently active first.

Path parameters

  • agentIdstringrequired

    The agent's id

Query parameters

  • limitinteger· 1–100· default 25

    Items per page, 1–100

  • cursorstring· max 200 chars

    nextCursor from the previous page

  • source"widget" | "whatsapp" | "email" | "messenger" | "instagram" | "telegram" | "tiktok" | "custom" | "playground"

    Only conversations from this channel

  • status"escalated" | "assigned" | "resolved" | "closed"

    Only conversations in this handoff status: escalated (waiting for a team member), assigned, resolved or closed

200 response · list of Conversation
  • idstringrequired

    Opaque identifier

  • sourcestring | nullrequired

    widget, whatsapp, email, messenger, instagram, telegram, tiktok, custom (your own channel) or playground (dashboard test chats)

  • externalIdstring | nullrequired

    WhatsApp number, email:<address>, a Messenger or Instagram user id, or custom:<your conversation id>

  • contactobjectrequired
    • namestring | nullrequired
    • emailstring | nullrequired
    • phonestring | nullrequired
  • messageCountintegerrequired· -9007199254740991–9007199254740991

    Customer turns (each has a reply)

  • ratinginteger | nullrequired

    CSAT rating, when the customer gave one

  • sentiment"positive" | "neutral" | "frustrated" | "angry" | nullrequired

    How the customer sounds in their latest scored message; null before any message is scored

  • handoffobjectrequired
    • status"active" | "escalated" | "assigned" | "resolved" | "closed"required

      active (the AI is handling it), escalated (waiting for a team member), assigned (a team member is handling it), resolved or closed

    • priority"low" | "normal" | "high" | "urgent"required
    • escalationReason"ai_requested" | "customer_keyword" | "rule_unanswered" | "manual" | "api" | "automation" | "negative_sentiment" | nullrequired

      Why it was last escalated; null if it never was

    • assignedToobject | nullrequired

      The team member handling it, while assigned

    • escalatedAtstring | nullrequired

      ISO 8601, UTC

    • firstHumanResponseAtstring | nullrequired

      When a team member first replied after the last escalation

    • resolvedAtstring | nullrequired

      ISO 8601, UTC

    • categorystring | nullrequired

      The category id the team gave it, from the agent's handoff settings

    • slaobject | nullrequired

      SLA targets for the last escalation, when SLA tracking is on

    • mergedIntostring | nullrequired

      When this conversation was merged into another, that conversation's id

  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl "https://www.igentrix.com/api/v1/agents/$AGENT_ID/conversations" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data: [...], nextCursor }. Errors: 401404422429

Get a conversation

GET/agents/{agentId}/conversations/{conversationId}Any key

Path parameters

  • agentIdstringrequired

    The agent's id

  • conversationIdstringrequired

    The conversation's id

200 response · Conversation
  • idstringrequired

    Opaque identifier

  • sourcestring | nullrequired

    widget, whatsapp, email, messenger, instagram, telegram, tiktok, custom (your own channel) or playground (dashboard test chats)

  • externalIdstring | nullrequired

    WhatsApp number, email:<address>, a Messenger or Instagram user id, or custom:<your conversation id>

  • contactobjectrequired
    • namestring | nullrequired
    • emailstring | nullrequired
    • phonestring | nullrequired
  • messageCountintegerrequired· -9007199254740991–9007199254740991

    Customer turns (each has a reply)

  • ratinginteger | nullrequired

    CSAT rating, when the customer gave one

  • sentiment"positive" | "neutral" | "frustrated" | "angry" | nullrequired

    How the customer sounds in their latest scored message; null before any message is scored

  • handoffobjectrequired
    • status"active" | "escalated" | "assigned" | "resolved" | "closed"required

      active (the AI is handling it), escalated (waiting for a team member), assigned (a team member is handling it), resolved or closed

    • priority"low" | "normal" | "high" | "urgent"required
    • escalationReason"ai_requested" | "customer_keyword" | "rule_unanswered" | "manual" | "api" | "automation" | "negative_sentiment" | nullrequired

      Why it was last escalated; null if it never was

    • assignedToobject | nullrequired

      The team member handling it, while assigned

    • escalatedAtstring | nullrequired

      ISO 8601, UTC

    • firstHumanResponseAtstring | nullrequired

      When a team member first replied after the last escalation

    • resolvedAtstring | nullrequired

      ISO 8601, UTC

    • categorystring | nullrequired

      The category id the team gave it, from the agent's handoff settings

    • slaobject | nullrequired

      SLA targets for the last escalation, when SLA tracking is on

    • mergedIntostring | nullrequired

      When this conversation was merged into another, that conversation's id

  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl "https://www.igentrix.com/api/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data }. Errors: 401404429

Escalate to the team

POST/agents/{agentId}/conversations/{conversationId}/escalateRead & write key

Hands the conversation from the AI to your team, as if the customer had asked for a person: the customer is told on their channel whether someone is available now or when your team is back, the conversation is assigned to an available team member when possible, the team is notified, and a conversation.escalated webhook event is sent. The agent must have human handoff switched on. Returns 409 if the conversation is already with the team.

Path parameters

  • agentIdstringrequired

    The agent's id

  • conversationIdstringrequired

    The conversation's id

Request body

  • reasonstring· max 500 chars

    Shown to the team, e.g. why your system is escalating

  • priority"low" | "normal" | "high" | "urgent"

    Defaults to normal. urgent reaches the owner even outside office hours

200 response · Conversation
  • idstringrequired

    Opaque identifier

  • sourcestring | nullrequired

    widget, whatsapp, email, messenger, instagram, telegram, tiktok, custom (your own channel) or playground (dashboard test chats)

  • externalIdstring | nullrequired

    WhatsApp number, email:<address>, a Messenger or Instagram user id, or custom:<your conversation id>

  • contactobjectrequired
    • namestring | nullrequired
    • emailstring | nullrequired
    • phonestring | nullrequired
  • messageCountintegerrequired· -9007199254740991–9007199254740991

    Customer turns (each has a reply)

  • ratinginteger | nullrequired

    CSAT rating, when the customer gave one

  • sentiment"positive" | "neutral" | "frustrated" | "angry" | nullrequired

    How the customer sounds in their latest scored message; null before any message is scored

  • handoffobjectrequired
    • status"active" | "escalated" | "assigned" | "resolved" | "closed"required

      active (the AI is handling it), escalated (waiting for a team member), assigned (a team member is handling it), resolved or closed

    • priority"low" | "normal" | "high" | "urgent"required
    • escalationReason"ai_requested" | "customer_keyword" | "rule_unanswered" | "manual" | "api" | "automation" | "negative_sentiment" | nullrequired

      Why it was last escalated; null if it never was

    • assignedToobject | nullrequired

      The team member handling it, while assigned

    • escalatedAtstring | nullrequired

      ISO 8601, UTC

    • firstHumanResponseAtstring | nullrequired

      When a team member first replied after the last escalation

    • resolvedAtstring | nullrequired

      ISO 8601, UTC

    • categorystring | nullrequired

      The category id the team gave it, from the agent's handoff settings

    • slaobject | nullrequired

      SLA targets for the last escalation, when SLA tracking is on

    • mergedIntostring | nullrequired

      When this conversation was merged into another, that conversation's id

  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl -X POST "https://www.igentrix.com/api/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID/escalate" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Returns 200 with { data }. Errors: 401403404422429

Send a customer message (custom channel)

POST/agents/{agentId}/messagesAny key

Connects any messaging platform: post what a customer wrote, and the agent answers it like any other channel, with handoff, usage and plan limits. The conversation shows in the inbox with a Custom badge. Team replies and handoff notices are delivered as message.sent webhook events (role human_agent or system), so subscribe an endpoint to relay them. Needs a key with Send messages (messages:write). See Custom channels for an example relay.

Path parameters

  • agentIdstringrequired

    The agent's id

Request body

  • conversationIdstringrequired· max 200 chars

    Your id for the conversation or thread (e.g. a Telegram chat id). Messages with the same id continue one conversation

  • senderobjectrequired
    • idstringrequired· max 200 chars

      Your id for the customer

    • namestring· max 200 chars
  • contactobject

    The customer's contact details, when you have them. They fill the conversation's contact and help privacy requests find it

    • emailstring· email· max 254 chars
    • phonestring· max 50 chars
  • textstring· max 4000 chars

    What the customer wrote

  • mediaUrlsstring[]· max 3 items

    Up to three public https URLs of images, audio, video or PDFs (10 MB each)

  • mode"sync" | "async"· default "sync"

    sync waits and returns the reply. async returns 202 straight away and delivers the reply as a message.sent webhook event

200 response · SendMessageResult
  • conversationIdstringrequired

    iGentrix's id for the conversation

  • status"answered" | "held" | "blocked" | "limit" | "accepted"required

    answered: the AI replied. held: a team member has the conversation (their replies arrive as message.sent events). blocked: the message was refused by content safety. limit: the plan's monthly usage is used up. accepted: async mode, the reply follows as a webhook event

  • replystring | nullrequired

    The AI's reply, when it answered

  • noticesstring[]required

    Handoff notices to show the customer after the reply, in order

  • handoffobjectrequired

    Whether the AI or your team now has the conversation

    • status"active" | "escalated" | "assigned" | "resolved" | "closed"required
curl -X POST "https://www.igentrix.com/api/v1/agents/$AGENT_ID/messages" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"…","sender":"…"}'

Returns 200 with { data }. Errors: 401404422429

List messages

GET/agents/{agentId}/conversations/{conversationId}/messagesAny key

Oldest first.

Path parameters

  • agentIdstringrequired

    The agent's id

  • conversationIdstringrequired

    The conversation's id

Query parameters

  • limitinteger· 1–100· default 25

    Items per page, 1–100

  • cursorstring· max 200 chars

    nextCursor from the previous page

200 response · list of Message
  • idstringrequired

    Opaque identifier

  • role"user" | "model" | "human_agent" | "system"required

    user is the customer, model the AI agent, human_agent a team member and system a handoff notice

  • textstringrequired
  • attachmentsobject[]required
    • namestringrequired
    • mimeTypestringrequired
  • createdAtstring | nullrequired

    ISO 8601, UTC

curl "https://www.igentrix.com/api/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data: [...], nextCursor }. Errors: 401404422429

Leads

Contacts an agent has captured.

List leads

GET/agents/{agentId}/leadsAny key

Newest first.

Path parameters

  • agentIdstringrequired

    The agent's id

Query parameters

  • limitinteger· 1–100· default 25

    Items per page, 1–100

  • cursorstring· max 200 chars

    nextCursor from the previous page

  • status"new" | "contacted" | "qualified" | "converted" | "lost"
  • emailstring· email· max 254 chars

    Only leads with this email (any letter case). Not paginated

  • phonestring· max 50 chars

    Only leads with this phone number, however it was typed (082…, +27 82…). Not paginated

200 response · list of Lead
  • idstringrequired

    Opaque identifier

  • namestring | nullrequired
  • emailstring | nullrequired
  • phonestring | nullrequired
  • statusstringrequired
  • sourcestring | nullrequired

    widget, whatsapp, email, playground or api

  • conversationIdstring | nullrequired

    The contact's most recently linked conversation

  • conversationIdsstring[]required

    Every conversation linked to this contact, on any channel, oldest first

  • notesstring | nullrequired
  • tagsstring[]required
  • customFieldsmap of anyrequired
  • scoreinteger | nullrequired

    Lead score from 0 to 100, from the agent's scoring rules and the contact's engagement. Null when scoring is off

  • scoreBand"hot" | "warm" | "cold" | nullrequired

    hot, warm or cold, from the score. Null when scoring is off

  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl "https://www.igentrix.com/api/v1/agents/$AGENT_ID/leads" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data: [...], nextCursor }. Errors: 401404422429

Create a lead

POST/agents/{agentId}/leadsRead & write key

The lead's source is api. Sends a lead.captured webhook event.

Path parameters

  • agentIdstringrequired

    The agent's id

Request body

  • namestring· max 200 chars
  • emailstring· email· max 254 chars
  • phonestring· max 50 chars
  • status"new" | "contacted" | "qualified" | "converted" | "lost"· default "new"
  • notesstring· max 2000 chars
  • tagsstring[]· max 20 items

    Tag ids from the agent's leadTags

  • customFieldsmap of string | number | null

    Values keyed by the agent's leadFields keys; null clears a value

  • conversationIdstring· max 128 chars

    Conversation the lead came from

201 response · Lead
  • idstringrequired

    Opaque identifier

  • namestring | nullrequired
  • emailstring | nullrequired
  • phonestring | nullrequired
  • statusstringrequired
  • sourcestring | nullrequired

    widget, whatsapp, email, playground or api

  • conversationIdstring | nullrequired

    The contact's most recently linked conversation

  • conversationIdsstring[]required

    Every conversation linked to this contact, on any channel, oldest first

  • notesstring | nullrequired
  • tagsstring[]required
  • customFieldsmap of anyrequired
  • scoreinteger | nullrequired

    Lead score from 0 to 100, from the agent's scoring rules and the contact's engagement. Null when scoring is off

  • scoreBand"hot" | "warm" | "cold" | nullrequired

    hot, warm or cold, from the score. Null when scoring is off

  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl -X POST "https://www.igentrix.com/api/v1/agents/$AGENT_ID/leads" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Returns 201 with { data }. Errors: 401403404422429

Get a lead

GET/agents/{agentId}/leads/{leadId}Any key

Path parameters

  • agentIdstringrequired

    The agent's id

  • leadIdstringrequired

    The lead's id

200 response · Lead
  • idstringrequired

    Opaque identifier

  • namestring | nullrequired
  • emailstring | nullrequired
  • phonestring | nullrequired
  • statusstringrequired
  • sourcestring | nullrequired

    widget, whatsapp, email, playground or api

  • conversationIdstring | nullrequired

    The contact's most recently linked conversation

  • conversationIdsstring[]required

    Every conversation linked to this contact, on any channel, oldest first

  • notesstring | nullrequired
  • tagsstring[]required
  • customFieldsmap of anyrequired
  • scoreinteger | nullrequired

    Lead score from 0 to 100, from the agent's scoring rules and the contact's engagement. Null when scoring is off

  • scoreBand"hot" | "warm" | "cold" | nullrequired

    hot, warm or cold, from the score. Null when scoring is off

  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl "https://www.igentrix.com/api/v1/agents/$AGENT_ID/leads/$LEAD_ID" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data }. Errors: 401404429

Update a lead

PATCH/agents/{agentId}/leads/{leadId}Read & write key

Changing status sends a lead.statusChanged webhook event.

Path parameters

  • agentIdstringrequired

    The agent's id

  • leadIdstringrequired

    The lead's id

Request body

  • namestring· max 200 chars
  • emailstring· email· max 254 chars
  • phonestring· max 50 chars
  • status"new" | "contacted" | "qualified" | "converted" | "lost"
  • notesstring· max 2000 chars
  • tagsstring[]· max 20 items

    Replaces the lead's tags

  • customFieldsmap of string | number | null

    Merged into the lead's values; null clears one

200 response · Lead
  • idstringrequired

    Opaque identifier

  • namestring | nullrequired
  • emailstring | nullrequired
  • phonestring | nullrequired
  • statusstringrequired
  • sourcestring | nullrequired

    widget, whatsapp, email, playground or api

  • conversationIdstring | nullrequired

    The contact's most recently linked conversation

  • conversationIdsstring[]required

    Every conversation linked to this contact, on any channel, oldest first

  • notesstring | nullrequired
  • tagsstring[]required
  • customFieldsmap of anyrequired
  • scoreinteger | nullrequired

    Lead score from 0 to 100, from the agent's scoring rules and the contact's engagement. Null when scoring is off

  • scoreBand"hot" | "warm" | "cold" | nullrequired

    hot, warm or cold, from the score. Null when scoring is off

  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl -X PATCH "https://www.igentrix.com/api/v1/agents/$AGENT_ID/leads/$LEAD_ID" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Returns 200 with { data }. Errors: 401403404422429

Delete a lead

DELETE/agents/{agentId}/leads/{leadId}Read & write key

Path parameters

  • agentIdstringrequired

    The agent's id

  • leadIdstringrequired

    The lead's id

200 response · Deleted
  • idstringrequired

    Opaque identifier

  • deletedtruerequired
curl -X DELETE "https://www.igentrix.com/api/v1/agents/$AGENT_ID/leads/$LEAD_ID" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data }. Errors: 401403404429

Collections

Data lists: structured data an agent can read and write, such as orders or bookings.

List data lists

GET/agents/{agentId}/collectionsAny key

Path parameters

  • agentIdstringrequired

    The agent's id

200 response · list of Collection
  • namestringrequired
  • displayNamestringrequired
  • fieldsobject[]required
    • namestringrequired· max 64 chars
    • labelstringrequired· max 100 chars
    • type"string" | "number" | "boolean" | "date" | "enum"required
    • enumValuesstring[]· max 50 items

      Allowed values, for enum fields

    • requiredbooleanrequired
  • statusFieldstring | nullrequired
  • statusValuesstring[]required
  • permissionsmap of objectrequired
  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl "https://www.igentrix.com/api/v1/agents/$AGENT_ID/collections" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data: [...], nextCursor }. Errors: 401404429

Create a data list

POST/agents/{agentId}/collectionsRead & write key

Path parameters

  • agentIdstringrequired

    The agent's id

Request body

  • namestringrequired· max 64 chars

    Permanent identifier used in URLs, e.g. orders

  • displayNamestringrequired· max 200 chars
  • fieldsobject[]required· max 50 items
    • namestringrequired· max 64 chars
    • labelstringrequired· max 100 chars
    • type"string" | "number" | "boolean" | "date" | "enum"required
    • enumValuesstring[]· max 50 items

      Allowed values, for enum fields

    • requiredbooleanrequired
  • statusFieldstring· max 64 chars

    Label the agent uses for status, e.g. "Order status"

  • statusValuesstring[]· max 20 items

    Allowed record statuses

  • permissionsmap of object

    What the agent may do for each contact type (keys are contact type ids). Admin contacts have full access by default; others have none.

201 response · Collection
  • namestringrequired
  • displayNamestringrequired
  • fieldsobject[]required
    • namestringrequired· max 64 chars
    • labelstringrequired· max 100 chars
    • type"string" | "number" | "boolean" | "date" | "enum"required
    • enumValuesstring[]· max 50 items

      Allowed values, for enum fields

    • requiredbooleanrequired
  • statusFieldstring | nullrequired
  • statusValuesstring[]required
  • permissionsmap of objectrequired
  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl -X POST "https://www.igentrix.com/api/v1/agents/$AGENT_ID/collections" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","displayName":"…","fields":[]}'

Returns 201 with { data }. Errors: 401403404422429

Get a data list

GET/agents/{agentId}/collections/{collectionName}Any key

Path parameters

  • agentIdstringrequired

    The agent's id

  • collectionNamestringrequired

    The data list's name

200 response · Collection
  • namestringrequired
  • displayNamestringrequired
  • fieldsobject[]required
    • namestringrequired· max 64 chars
    • labelstringrequired· max 100 chars
    • type"string" | "number" | "boolean" | "date" | "enum"required
    • enumValuesstring[]· max 50 items

      Allowed values, for enum fields

    • requiredbooleanrequired
  • statusFieldstring | nullrequired
  • statusValuesstring[]required
  • permissionsmap of objectrequired
  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl "https://www.igentrix.com/api/v1/agents/$AGENT_ID/collections/$COLLECTION_NAME" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data }. Errors: 401404429

Update a data list

PATCH/agents/{agentId}/collections/{collectionName}Read & write key

Path parameters

  • agentIdstringrequired

    The agent's id

  • collectionNamestringrequired

    The data list's name

Request body

  • displayNamestring· max 200 chars
  • fieldsobject[]· max 50 items

    Replaces the field list. Existing record values are kept.

    • namestringrequired· max 64 chars
    • labelstringrequired· max 100 chars
    • type"string" | "number" | "boolean" | "date" | "enum"required
    • enumValuesstring[]· max 50 items

      Allowed values, for enum fields

    • requiredbooleanrequired
  • statusFieldstring· max 64 chars

    Label the agent uses for status, e.g. "Order status"

  • statusValuesstring[]· max 20 items

    Allowed record statuses

  • permissionsmap of object

    What the agent may do for each contact type (keys are contact type ids). Admin contacts have full access by default; others have none.

200 response · Collection
  • namestringrequired
  • displayNamestringrequired
  • fieldsobject[]required
    • namestringrequired· max 64 chars
    • labelstringrequired· max 100 chars
    • type"string" | "number" | "boolean" | "date" | "enum"required
    • enumValuesstring[]· max 50 items

      Allowed values, for enum fields

    • requiredbooleanrequired
  • statusFieldstring | nullrequired
  • statusValuesstring[]required
  • permissionsmap of objectrequired
  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl -X PATCH "https://www.igentrix.com/api/v1/agents/$AGENT_ID/collections/$COLLECTION_NAME" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Returns 200 with { data }. Errors: 401403404422429

Delete a data list

DELETE/agents/{agentId}/collections/{collectionName}Read & write key

Also deletes all of its records.

Path parameters

  • agentIdstringrequired

    The agent's id

  • collectionNamestringrequired

    The data list's name

200 response · Deleted
  • idstringrequired

    Opaque identifier

  • deletedtruerequired
curl -X DELETE "https://www.igentrix.com/api/v1/agents/$AGENT_ID/collections/$COLLECTION_NAME" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data }. Errors: 401403404429

Records

Rows in a data list.

List records

GET/agents/{agentId}/collections/{collectionName}/recordsAny key

Newest first.

Path parameters

  • agentIdstringrequired

    The agent's id

  • collectionNamestringrequired

    The data list's name

Query parameters

  • limitinteger· 1–100· default 25

    Items per page, 1–100

  • cursorstring· max 200 chars

    nextCursor from the previous page

  • statusstring· max 100 chars
200 response · list of Record
  • idstringrequired

    Opaque identifier

  • datamap of anyrequired
  • statusstring | nullrequired
  • conversationIdstring | nullrequired
  • createdBystring | nullrequired

    WhatsApp number, widget:…, dashboard or api

  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl "https://www.igentrix.com/api/v1/agents/$AGENT_ID/collections/$COLLECTION_NAME/records" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data: [...], nextCursor }. Errors: 401404422429

Create a record

POST/agents/{agentId}/collections/{collectionName}/recordsRead & write key

data is checked against the data list's fields.

Path parameters

  • agentIdstringrequired

    The agent's id

  • collectionNamestringrequired

    The data list's name

Request body

  • datamap of string | number | boolean | nullrequired

    Values keyed by the collection's field names

  • statusstring | null
201 response · Record
  • idstringrequired

    Opaque identifier

  • datamap of anyrequired
  • statusstring | nullrequired
  • conversationIdstring | nullrequired
  • createdBystring | nullrequired

    WhatsApp number, widget:…, dashboard or api

  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl -X POST "https://www.igentrix.com/api/v1/agents/$AGENT_ID/collections/$COLLECTION_NAME/records" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":"…"}'

Returns 201 with { data }. Errors: 401403404422429

Get a record

GET/agents/{agentId}/collections/{collectionName}/records/{recordId}Any key

Path parameters

  • agentIdstringrequired

    The agent's id

  • collectionNamestringrequired

    The data list's name

  • recordIdstringrequired

    The record's id

200 response · Record
  • idstringrequired

    Opaque identifier

  • datamap of anyrequired
  • statusstring | nullrequired
  • conversationIdstring | nullrequired
  • createdBystring | nullrequired

    WhatsApp number, widget:…, dashboard or api

  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl "https://www.igentrix.com/api/v1/agents/$AGENT_ID/collections/$COLLECTION_NAME/records/$RECORD_ID" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data }. Errors: 401404429

Update a record

PATCH/agents/{agentId}/collections/{collectionName}/records/{recordId}Read & write key

Path parameters

  • agentIdstringrequired

    The agent's id

  • collectionNamestringrequired

    The data list's name

  • recordIdstringrequired

    The record's id

Request body

  • datamap of string | number | boolean | null

    Merged into the record; null clears a value

  • statusstring | null
200 response · Record
  • idstringrequired

    Opaque identifier

  • datamap of anyrequired
  • statusstring | nullrequired
  • conversationIdstring | nullrequired
  • createdBystring | nullrequired

    WhatsApp number, widget:…, dashboard or api

  • createdAtstring | nullrequired

    ISO 8601, UTC

  • updatedAtstring | nullrequired

    ISO 8601, UTC

curl -X PATCH "https://www.igentrix.com/api/v1/agents/$AGENT_ID/collections/$COLLECTION_NAME/records/$RECORD_ID" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Returns 200 with { data }. Errors: 401403404422429

Delete a record

DELETE/agents/{agentId}/collections/{collectionName}/records/{recordId}Read & write key

Path parameters

  • agentIdstringrequired

    The agent's id

  • collectionNamestringrequired

    The data list's name

  • recordIdstringrequired

    The record's id

200 response · Deleted
  • idstringrequired

    Opaque identifier

  • deletedtruerequired
curl -X DELETE "https://www.igentrix.com/api/v1/agents/$AGENT_ID/collections/$COLLECTION_NAME/records/$RECORD_ID" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data }. Errors: 401403404429

Webhooks

Subscribe URLs to events (REST hooks), as Zapier and Make do when an automation is turned on.

List webhook event types

GET/webhook-eventsAny key

Every event type with an example envelope. Integrations use the samples to show fields before a real event arrives.

Query parameters

  • type"conversation.created" | "message.received" | "message.sent" | "lead.captured" | "lead.statusChanged" | "lead.updated" | "lead.deleted" | "booking.created" | "booking.rescheduled" | "booking.cancelled" | "csat.submitted" | "conversation.escalated" | "conversation.assigned" | "conversation.returnedToAi" | "conversation.resolved" | "conversation.slaBreached" | "agent.updated"

    Only this event type

200 response · list of WebhookEventType
  • type"conversation.created" | "message.received" | "message.sent" | "lead.captured" | "lead.statusChanged" | "lead.updated" | "lead.deleted" | "booking.created" | "booking.rescheduled" | "booking.cancelled" | "csat.submitted" | "conversation.escalated" | "conversation.assigned" | "conversation.returnedToAi" | "conversation.resolved" | "conversation.slaBreached" | "agent.updated"required
  • labelstringrequired
  • descriptionstringrequired
  • samplemap of anyrequired

    An example envelope, as the endpoint receives it

curl "https://www.igentrix.com/api/v1/webhook-events" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data: [...], nextCursor }. Errors: 401422429

List webhook endpoints

GET/agents/{agentId}/webhook-endpointsAny key

Endpoints registered for the agent, from the dashboard or this API. Secrets aren't included.

Path parameters

  • agentIdstringrequired

    The agent's id

200 response · list of WebhookEndpoint
  • idstringrequired

    Opaque identifier

  • urlstringrequired
  • descriptionstringrequired
  • events"conversation.created" | "message.received" | "message.sent" | "lead.captured" | "lead.statusChanged" | "lead.updated" | "lead.deleted" | "booking.created" | "booking.rescheduled" | "booking.cancelled" | "csat.submitted" | "conversation.escalated" | "conversation.assigned" | "conversation.returnedToAi" | "conversation.resolved" | "conversation.slaBreached" | "agent.updated"[]required
  • enabledbooleanrequired
  • createdAtstring | nullrequired

    ISO 8601, UTC

curl "https://www.igentrix.com/api/v1/agents/$AGENT_ID/webhook-endpoints" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data: [...], nextCursor }. Errors: 401404429

Subscribe a webhook endpoint

POST/agents/{agentId}/webhook-endpointsRead & write key

Registers a URL to receive events (REST hooks), e.g. when a Zap or Make scenario is turned on. Events are signed with the returned secret, retried with backoff, and shown in Agent → Developers → Webhooks. An agent can have up to 10 endpoints.

Path parameters

  • agentIdstringrequired

    The agent's id

Request body

  • urlstringrequired· uri· max 2048 chars

    Public https URL that receives the events

  • events"conversation.created" | "message.received" | "message.sent" | "lead.captured" | "lead.statusChanged" | "lead.updated" | "lead.deleted" | "booking.created" | "booking.rescheduled" | "booking.cancelled" | "csat.submitted" | "conversation.escalated" | "conversation.assigned" | "conversation.returnedToAi" | "conversation.resolved" | "conversation.slaBreached" | "agent.updated"[]required

    Event types to send

  • descriptionstring· max 200 chars

    Shown in the dashboard, e.g. Zapier: New lead → Google Sheets

201 response · WebhookEndpointWithSecret
  • idstringrequired

    Opaque identifier

  • urlstringrequired
  • descriptionstringrequired
  • events"conversation.created" | "message.received" | "message.sent" | "lead.captured" | "lead.statusChanged" | "lead.updated" | "lead.deleted" | "booking.created" | "booking.rescheduled" | "booking.cancelled" | "csat.submitted" | "conversation.escalated" | "conversation.assigned" | "conversation.returnedToAi" | "conversation.resolved" | "conversation.slaBreached" | "agent.updated"[]required
  • enabledbooleanrequired
  • createdAtstring | nullrequired

    ISO 8601, UTC

  • secretstringrequired

    Signing secret for X-Igentrix-Signature. Only returned here

curl -X POST "https://www.igentrix.com/api/v1/agents/$AGENT_ID/webhook-endpoints" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"…","events":[]}'

Returns 201 with { data }. Errors: 401403404422429

Unsubscribe a webhook endpoint

DELETE/agents/{agentId}/webhook-endpoints/{endpointId}Read & write key

Removes the endpoint and its delivery log, e.g. when a Zap is turned off.

Path parameters

  • agentIdstringrequired

    The agent's id

  • endpointIdstringrequired

    The webhook endpoint's id

200 response · Deleted
  • idstringrequired

    Opaque identifier

  • deletedtruerequired
curl -X DELETE "https://www.igentrix.com/api/v1/agents/$AGENT_ID/webhook-endpoints/$ENDPOINT_ID" \
  -H "Authorization: Bearer $IGENTRIX_API_KEY"

Returns 200 with { data }. Errors: 401403404429