HTTP API

API reference

Every endpoint a project key can call: send messages, label chats, read conversations. Open one to see a sample, its answers, and try it with your key.

Your key stays in this tab. It is never saved, and it is only sent to api.olee.ai.

Messages

Send a message to a customer on a connected channel.

Send a message

Send one or more messages to customers on a channel. Each message goes to a conversation by its id, and shows up in the Inbox like any message your team sends.

Always read data.results[].status. The request answers 200 as a whole even when a message is refused.

Sending to a number with to finds the contact the project already has for it, or makes one, so you never need to look up a user_id first. Someone who has not written to you in the last 24 hours can only be sent an approved template.

On WhatsApp you can write freely for 24 hours after the customer's last message. Oleon does not check the window: a free message sent outside it comes back sent, then fails a moment later, and List messages shows it with message_state: "failed". Outside the window, send a template.

Path

channelstringrequired

The channel to send on. It must be connected to the project, and the conversations must be on it. olee_ws is the chat on your website.

whatsappmessengerinstagramtelegramolee_ws

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

Body

messagesarrayrequired

The messages to send. The whole batch is checked first: if any message has no recipient, a phone number that is not valid, no type, a type this endpoint does not send, or a conversation that is not in this project, nothing is sent.

messages[].user_iduuid

The conversation to send to, from List conversations or Create a contact. Needed unless you send to; if a message has both, user_id is used.

messages[].tostring

WhatsApp only: the customer's phone number instead of a conversation, written any common way: 0771234567, 077 123 4567, +94 77 123 4567. If they are not a contact yet, they become one. Ignored when the message also has a user_id.

default_regionstringdefault LK

Where a number written without its country code (a leading 0) is from, as a two-letter country code: LK, GB, IN.

messages[].typestringrequired

What kind of message this is. The field named after the type carries its content. Website chat takes text only; template is WhatsApp only; cta_url works on WhatsApp, Messenger and Telegram.

textimagevideoaudiofiletemplatecta_url

messages[].text.bodystring

For text: the words to send. text can also be the string itself.

messages[].image.linkurl

For image, video, audio and file: a public link to the file, or id for media already uploaded to WhatsApp. Add caption to say something with an image, video or file, and filename for a file.

messages[].templateobject

For template: name and language of an approved WhatsApp template, and components for the values that fill it in. Needed to start a chat, or to write after 24 hours of silence.

messages[].cta_urlobject

For cta_url: a message with one link button. body (cut to 1024 characters), button_text (cut to 20) and url (http or https).

messages[].context_msg_idstring

Optional. The message to reply to, so it shows as a reply in the customer's app: its id from List messages, or its integration_message_id. It must be in the same conversation.

curl -X POST "https://api.olee.ai/v4/webhooks/ech/whatsapp/my-shop" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "user_id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
      "type": "text",
      "text": {
        "body": "Hi Nimasha, your order is ready to collect."
      }
    }
  ]
}'

1 of 12

The channel took the message. send is the channel's own answer.

{
  "success": true,
  "message": "ECH webhook processed successfully",
  "data": {
    "success": true,
    "results": [
      {
        "user_id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
        "to": "94771234567",
        "type": "text",
        "status": "sent",
        "send": {
          "success": true,
          "message": "Message sent successfully",
          "messageId": "wamid.HBgLOTQ3NzEyMzQ1NjcVAgARGBI...",
          "data": {
            "…": "the channel's raw reply"
          }
        },
        "dbError": null
      }
    ]
  }
}

Try itAdd your API key at the top of the page

POST/v4/webhooks/ech/whatsapp/my-shop

Parameters

channelpathrequiredprojectSlugpathrequired

Body application/json

This sends a real messageThe customer receives it, and it shows in your Inbox.

List templates

The active WhatsApp templates saved in the project. Check messageData.submissionStatus: only an APPROVED template can be sent.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

curl -X GET "https://api.olee.ai/v4/meta/templates/my-shop" \
  -H "Authorization: Bearer $OLEON_API_KEY"

1 of 4

Always, with an empty list when there are none.

{
  "success": true,
  "message": "Meta templates retrieved successfully",
  "data": [
    {
      "id": 318,
      "projectId": 1204,
      "templateName": "order_ready",
      "isActive": true,
      "messageData": {
        "name": "order_ready",
        "language": "en",
        "category": "UTILITY",
        "submissionStatus": "APPROVED",
        "components": [
          "…"
        ]
      },
      "createdBy": null,
      "updatedBy": null,
      "command": null,
      "createdAt": "2026-09-02T08:14:22.000Z",
      "updatedAt": "2026-09-02T08:20:05.000Z"
    }
  ]
}

Try itAdd your API key at the top of the page

GET/v4/meta/templates/my-shop

Parameters

projectSlugpathrequired

Contacts

Make sure someone is a contact before you message them first.

Create a contact

Add someone who has not messaged you yet, without sending them anything. To message a new WhatsApp number straight away you do not need this: send with to. If they are already a contact you get their id back instead, so it is safe to call every time.

For many at once: 201 when all were new, 409 when all existed, 207 when some were created and some were not, and 400 when none were created and at least one failed. The body says success: true in every case; read data.summary and data.results[].

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

channelstringrequired

The channel this contact is on.

whatsappmessengerinstagramtelegramolee_ws

Body

custom_idstringrequired

Who they are on that channel. For WhatsApp, the full number with the country code and no + or spaces: 94771234567.

custom_user_namestring

The name to show in the Inbox.

usersarray

To add many at once, send users: [{ custom_id, custom_user_name }] instead of the two fields above.

curl -X POST "https://api.olee.ai/v4/oleon/user/projects/my-shop/whatsapp" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "custom_id": "94771234567",
  "custom_user_name": "Nimasha Silva"
}'

1 of 6

A new contact was made. id is the conversation id you send to.

{
  "success": true,
  "message": "User created successfully",
  "data": {
    "id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
    "projectId": 1204
  }
}

Try itAdd your API key at the top of the page

POST/v4/oleon/user/projects/my-shop/whatsapp

Parameters

projectSlugpathrequiredchannelpathrequired

Body application/json

Labels

Put labels on a chat, list them, take them off.

List label names

Every label name used in the project, with how many chats carry it.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

curl -X GET "https://api.olee.ai/v4/labels/my-shop/names" \
  -H "Authorization: Bearer $OLEON_API_KEY"

1 of 4

Always.

{
  "success": true,
  "message": "Label names retrieved successfully",
  "data": {
    "items": [
      {
        "name": "Paid",
        "conversation_count": 48
      },
      {
        "name": "Wholesale",
        "conversation_count": 12
      }
    ],
    "total": 2
  }
}

Try itAdd your API key at the top of the page

GET/v4/labels/my-shop/names

Parameters

projectSlugpathrequired

List labels on chats

Every label on every chat in the project, newest first. Each row is one label on one chat; its id is what you use to take it off. Labels that were taken off are not listed.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

Query

limitintegerdefault 100

How many per page.

pageintegerdefault 1

Which page, from 1.

curl -X GET "https://api.olee.ai/v4/labels/my-shop" \
  -H "Authorization: Bearer $OLEON_API_KEY"

1 of 4

Always.

{
  "success": true,
  "message": "Labels retrieved successfully",
  "data": {
    "labels": [
      {
        "id": 90211,
        "name": "Paid",
        "oleonUserId": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
        "isActive": true,
        "isTemplate": false,
        "templateId": null,
        "createdBy": null,
        "updatedBy": null,
        "deletedBy": null,
        "createdAt": "2026-10-08T06:12:40.000Z",
        "updatedAt": "2026-10-08T06:12:40.000Z"
      }
    ],
    "limit": 100,
    "page": 1,
    "total": 1,
    "totalPages": 1,
    "hasMore": false
  }
}

Try itAdd your API key at the top of the page

GET/v4/labels/my-shop

Parameters

projectSlugpathrequiredlimitquerypagequery

Add a label

Put a label on a chat. The project comes from the chat itself, so there is no slug in the path. If a Scout bot on WhatsApp is waiting for this label, it carries on.

Adding the same name twice gives the chat two labels. Check the chat's labels in List conversations first if you might call this more than once.

Body

oleon_user_iduuidrequired

The conversation to label.

namestringrequired

The label's name, as it shows in the Inbox.

is_templateboolean

Set to true with template_id to use one of the project's saved labels, with its colour and icon.

template_idinteger

The saved label to use, when is_template is true. It must be one of this project's.

curl -X POST "https://api.olee.ai/v4/labels" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "oleon_user_id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
  "name": "Paid"
}'

1 of 7

The label is on the chat. id is what you use to take it off.

{
  "success": true,
  "message": "Label created successfully",
  "data": {
    "id": 90211,
    "name": "Paid",
    "oleon_user_id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
    "is_active": true,
    "is_template": false,
    "template_id": null,
    "created_by": null,
    "created_via": null,
    "created_at": "2026-10-08T06:12:40.000Z",
    "update_at": null,
    "updated_by": null,
    "deleted_by": null,
    "project_slug": "my-shop",
    "project_id": 1204
  }
}

Try itAdd your API key at the top of the page

POST/v4/labels

Body application/json

Remove a label

Take a label off a chat, or put it back. Use the label's id from Add a label, List labels on chats, or a chat's labels in List conversations.

Path

idintegerrequired

The label's id.

Body

is_activebooleanrequired

false takes the label off. true puts it back.

curl -X PATCH "https://api.olee.ai/v4/labels/90211" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "is_active": false
}'

1 of 5

Done. id comes back as the string you sent.

{
  "success": true,
  "message": "Label active status updated successfully",
  "data": {
    "id": "90211",
    "is_active": false
  }
}

Try itAdd your API key at the top of the page

PATCH/v4/labels/90211

Parameters

idpathrequired

Body application/json

Conversations

Read chats and messages, mark them read, hand them to a person, leave notes.

List conversations

The project's chats, most recent first, with the last message, unread count and labels of each.

total is null when you filter by label or by team member.

In a message, type says who sent it: user is the customer, agent is you (your team, a bot or the API). message_type says what it is: message, media, template, interactive.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

Query

pageintegerdefault 1

Which page, from 1.

limitintegerdefault 200

How many per page, up to 1000. More is a 400.

labelsstring

Only chats carrying at least one of these labels, separated by commas: Paid,Wholesale. Names must match exactly, including capitals.

assignedTouuid

Only chats waiting for, or accepted by, this team member (their user id). Ignored when labels is set.

windowMonthsintegerdefault 4

How far back to look, in months, up to 120. Ignored when labels or assignedTo is set.

withUnreadbooleandefault true

Set to false to skip unread counts and answer faster.

curl -X GET "https://api.olee.ai/v4/oleon/convos/my-shop/history/conversations" \
  -H "Authorization: Bearer $OLEON_API_KEY"

1 of 4

Always.

{
  "success": true,
  "message": "Conversation summaries retrieved successfully",
  "data": {
    "items": [
      {
        "user_id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
        "custom_id": "94771234567",
        "display_name": "Nimasha Silva",
        "integration_id": 1,
        "last_message": {
          "id": "7c1e4b2a-0d3f-4a8e-b1c2-9e8f7a6d5c41",
          "message": "Is the blue one in stock?",
          "type": "user",
          "message_type": "message",
          "message_state": "received",
          "message_sent_by": null,
          "created_at": "2026-10-08T05:58:11.000Z"
        },
        "unread_count": 2,
        "labels": [
          {
            "id": 90212,
            "name": "Wholesale",
            "is_template": false,
            "template_id": null,
            "oleon_user_id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
            "created_by": null,
            "created_at": "2026-10-07T10:02:51.000Z",
            "update_at": null,
            "updated_by": null,
            "is_active": true
          }
        ],
        "is_pinned": false
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 200,
      "total": 1,
      "hasMore": false
    }
  }
}

Try itAdd your API key at the top of the page

GET/v4/oleon/convos/my-shop/history/conversations

Parameters

projectSlugpathrequiredpagequerylimitquerylabelsqueryassignedToquerywindowMonthsquerywithUnreadquery

List messages

The messages in one chat, oldest first unless you ask otherwise.

message_state is received for the customer's messages. Yours go sent, then delivered, then seen, or failed with the reason in error_msg.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

conversationIduuidrequired

The conversation's id.

Query

pageintegerdefault 1

Which page, from 1.

limitintegerdefault 50

How many per page, up to 1000. More is a 400.

orderstringdefault asc

Oldest or newest first.

ascdesc

fromdate-time

Only messages from this time.

todate-time

Only messages up to this time.

updatedSincedate-time

Only messages created or changed since this time, such as a delivery or read update. Good for keeping a copy in step.

curl -X GET "https://api.olee.ai/v4/oleon/convos/my-shop/history/messages/4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90" \
  -H "Authorization: Bearer $OLEON_API_KEY"

1 of 4

Always. A conversation that is not in this project gives an empty list.

{
  "success": true,
  "message": "User message history retrieved successfully",
  "data": {
    "items": [
      {
        "id": "7c1e4b2a-0d3f-4a8e-b1c2-9e8f7a6d5c41",
        "user_id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
        "message": "Is the blue one in stock?",
        "type": "user",
        "message_type": "message",
        "file_url": null,
        "mime_type": null,
        "message_state": "received",
        "message_sent_by": null,
        "parent_message_id": null,
        "error_msg": null,
        "integration_message_id": "wamid.HBgLOTQ3NzEyMzQ1NjcVAgASGBQ...",
        "created_at": "2026-10-08T05:58:11.000Z",
        "updated_at": "2026-10-08T05:58:11.000Z",
        "integration": {
          "name": "whatsapp"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "hasMore": false
    },
    "date_range": {
      "from": null,
      "to": null
    },
    "user_id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90"
  }
}

Try itAdd your API key at the top of the page

GET/v4/oleon/convos/my-shop/history/messages/4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90

Parameters

projectSlugpathrequiredconversationIdpathrequiredpagequerylimitqueryorderqueryfromquerytoqueryupdatedSincequery

Mark as read

Mark a chat read up to a message. It clears the unread mark for the whole team, the same as someone opening the chat.

For many chats at once, POST /v4/chat/seen/batch with { items: [{ oleonUserId, messageId }] }, up to 500.

Path

conversationIduuidrequired

The conversation's id.

messageIduuidrequired

The newest message that has been read, from List messages.

curl -X POST "https://api.olee.ai/v4/chat/4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90/7c1e4b2a-0d3f-4a8e-b1c2-9e8f7a6d5c41/seen" \
  -H "Authorization: Bearer $OLEON_API_KEY"

1 of 5

Done.

{
  "success": true,
  "message": "Seen status updated",
  "data": {
    "oleon_user_id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
    "last_seen_message_id": "7c1e4b2a-0d3f-4a8e-b1c2-9e8f7a6d5c41",
    "last_status_update_by": null,
    "updated_at": "2026-10-08T06:30:00.000Z"
  }
}

Try itAdd your API key at the top of the page

POST/v4/chat/4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90/7c1e4b2a-0d3f-4a8e-b1c2-9e8f7a6d5c41/seen

Parameters

conversationIdpathrequiredmessageIdpathrequired

Hand to a person

Take a chat away from the bot and give it to your team, or give it back to the bot. While a person has it, Scout and the AI stay quiet.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

conversationIduuidrequired

The conversation's id.

Body

statusbooleanrequired

true gives it to a person. false gives it back to the bot.

curl -X PATCH "https://api.olee.ai/v4/oleon/user/projects/my-shop/users/4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90/live" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": true
}'

1 of 5

Done.

{
  "success": true,
  "message": "Live agent flags updated",
  "data": {
    "id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
    "is_live_agent": true,
    "is_live_agent_notifier": true
  }
}

Try itAdd your API key at the top of the page

PATCH/v4/oleon/user/projects/my-shop/users/4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90/live

Parameters

projectSlugpathrequiredconversationIdpathrequired

Body application/json

This changes a real chatYour team sees the change in the Inbox straight away.

Add a note

Leave a private note on a chat for your team. The customer never sees it.

A note added with a key has no author, so nobody can edit or delete it later, with a key or in the workspace.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

conversationIduuidrequired

The conversation's id.

Body

notestringrequired

The note, up to 2000 characters. A chat holds up to 500 notes.

curl -X POST "https://api.olee.ai/v4/oleon/convos/my-shop/history/conversations/4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90/notes" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Paid the deposit by bank transfer. Collecting Friday."
}'

1 of 6

The note is on the chat.

{
  "success": true,
  "message": "Note added",
  "data": {
    "id": 5521,
    "oleon_user_id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
    "body": "Paid the deposit by bank transfer. Collecting Friday.",
    "is_readable": true,
    "created_at": "2026-10-08T06:20:02.000Z",
    "edited_at": null,
    "is_edited": false,
    "author": null,
    "author_id": null
  }
}

Try itAdd your API key at the top of the page

POST/v4/oleon/convos/my-shop/history/conversations/4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90/notes

Parameters

projectSlugpathrequiredconversationIdpathrequired

Body application/json

List notes

The notes on a chat, newest first.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

conversationIduuidrequired

The conversation's id.

Query

pageintegerdefault 1

Which page, from 1.

limitintegerdefault 25

How many per page, up to 100.

curl -X GET "https://api.olee.ai/v4/oleon/convos/my-shop/history/conversations/4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90/notes" \
  -H "Authorization: Bearer $OLEON_API_KEY"

1 of 4

Always.

{
  "success": true,
  "message": "Contact notes retrieved successfully",
  "data": {
    "items": [
      {
        "id": 5521,
        "oleon_user_id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
        "body": "Paid the deposit by bank transfer. Collecting Friday.",
        "is_readable": true,
        "created_at": "2026-10-08T06:20:02.000Z",
        "edited_at": null,
        "is_edited": false,
        "author": null,
        "author_id": null
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 25,
      "total": 1,
      "hasMore": false
    },
    "available": true,
    "max_length": 2000
  }
}

Try itAdd your API key at the top of the page

GET/v4/oleon/convos/my-shop/history/conversations/4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90/notes

Parameters

projectSlugpathrequiredconversationIdpathrequiredpagequerylimitquery

Deals

Put a sale on the Deals board from anywhere, move it along, and record how it ends.

List pipelines and stages

The project's pipelines, each with its stages in order, and the reasons a deal can be lost. Read it once to know which ids to send.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

curl -X GET "https://api.olee.ai/v4/deals/my-shop/settings" \
  -H "Authorization: Bearer $OLEON_API_KEY"

1 of 4

Always. A project that has never opened Deals gets its first pipeline now.

{
  "success": true,
  "message": "Deal settings",
  "data": {
    "pipelines": [
      {
        "id": 12,
        "name": "Sales",
        "is_default": true,
        "ad_deals": false,
        "win_on_paid": true,
        "stages": [
          {
            "id": 101,
            "pipeline_id": 12,
            "name": "New",
            "kind": "open",
            "position": 1,
            "color": "gray",
            "probability": 10,
            "rot_days": 3
          },
          {
            "id": 102,
            "pipeline_id": 12,
            "name": "Quoted",
            "kind": "open",
            "position": 2,
            "color": "purple",
            "probability": 60,
            "rot_days": 5
          },
          {
            "id": 105,
            "pipeline_id": 12,
            "name": "Won",
            "kind": "won",
            "position": 1000,
            "color": "green",
            "probability": 100,
            "rot_days": null
          },
          {
            "id": 106,
            "pipeline_id": 12,
            "name": "Lost",
            "kind": "lost",
            "position": 1001,
            "color": "red",
            "probability": 0,
            "rot_days": null
          }
        ]
      }
    ],
    "lost_reasons": [
      {
        "id": 7,
        "label": "Price too high",
        "position": 1
      }
    ],
    "limits": {
      "open_stages": 12,
      "lost_reasons": 20,
      "pipelines": 10
    }
  }
}

Try itAdd your API key at the top of the page

GET/v4/deals/my-shop/settings

Parameters

projectSlugpathrequired

Create a deal

Put a sale on the board for one customer, named by their conversation or by phone number. It lands at the top of its stage, owned by nobody.

A deal made with a key says it came from the API, and has no person beside it in its history.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

Body

titlestringrequired

What the sale is, up to 120 characters.

phonestring

The customer's WhatsApp number, written any common way. Someone the project has never spoken to becomes a contact. Send this or oleon_user_id.

default_regionstringdefault LK

Two-letter country a local number (no country code) is read in.

oleon_user_iduuid

The customer's conversation id, instead of phone.

valuenumber

What it is worth, in major units. "Rs 25,000" is read too.

currencystringdefault LKR

Three-letter code.

pipeline_idintegerdefault the default pipeline

Which pipeline. Its first stage, unless stage_id is sent.

stage_idinteger

An open stage to start in. Its pipeline goes with it.

expected_close_datedate

YYYY-MM-DD.

owner_iduuiddefault nobody

A team member to give it to.

fieldsobject

Deal fields by key, like {"event_date": "2026-11-30"}. Checked before anything is saved: one that does not fit refuses the whole deal.

notestring

A first note on the deal, up to 2000 characters.

curl -X POST "https://api.olee.ai/v4/deals/my-shop" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+94 77 123 4567",
  "title": "Wedding cake for 30 Nov",
  "value": 25000,
  "fields": {
    "event_date": "2026-11-30"
  },
  "note": "From the website form: three tiers, chocolate."
}'

1 of 6

The deal is on the board. contact_created says whether a new number became a contact.

{
  "success": true,
  "message": "Deal added",
  "data": {
    "id": "9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f",
    "title": "Wedding cake for 30 Nov",
    "value": 25000,
    "currency": "LKR",
    "status": "open",
    "pipeline_id": 12,
    "stage_id": 101,
    "stage": {
      "id": 101,
      "name": "New",
      "kind": "open",
      "color": "gray"
    },
    "contact": {
      "id": "4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90",
      "name": null,
      "number": "94771234567"
    },
    "owner": null,
    "expected_close_date": null,
    "source": "api",
    "created_at": "2026-10-11T06:20:02.000Z",
    "contact_created": true
  }
}

Try itAdd your API key at the top of the page

POST/v4/deals/my-shop

Parameters

projectSlugpathrequired

Body application/json

Get a deal

One deal: where it stands, its products, its fields, its notes, and everything that happened to it.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

dealIduuidrequired

The deal's id.

curl -X GET "https://api.olee.ai/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $OLEON_API_KEY"

1 of 5

The deal is in this project.

{
  "success": true,
  "message": "Deal",
  "data": {
    "id": "9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f",
    "title": "Wedding cake for 30 Nov",
    "value": 25000,
    "currency": "LKR",
    "status": "open",
    "stage": {
      "id": 101,
      "name": "New",
      "kind": "open",
      "color": "gray"
    },
    "items": [
      {
        "id": 3,
        "name": "Three-tier cake",
        "variant_label": "Chocolate",
        "quantity": 1,
        "unit_price": 25000,
        "line_total": 25000
      }
    ],
    "fields": [
      {
        "id": 4,
        "key": "event_date",
        "label": "Event date",
        "type": "date",
        "options": [],
        "value": "2026-11-30",
        "is_readable": true
      }
    ],
    "notes": [
      {
        "id": 81,
        "body": "From the website form: three tiers, chocolate.",
        "is_readable": true,
        "author": null,
        "created_at": "2026-10-11T06:20:02.000Z"
      }
    ],
    "history": [
      {
        "id": 1,
        "at": "2026-10-11T06:20:02.000Z",
        "from_stage": null,
        "to_stage": {
          "id": 101,
          "name": "New"
        },
        "status": "open",
        "actor": null
      }
    ],
    "activity": [
      {
        "id": 9,
        "kind": "field",
        "at": "2026-10-11T06:20:02.000Z",
        "actor": null,
        "data": {
          "field_id": 4,
          "label": "Event date",
          "action": "set"
        }
      }
    ]
  }
}

Try itAdd your API key at the top of the page

GET/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f

Parameters

projectSlugpathrequireddealIdpathrequired

Update a deal

Change its name, value, currency, expected close or owner. Send only what changes; each change is a line in its history.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

dealIduuidrequired

The deal's id.

Body

titlestring

Up to 120 characters.

valuenumber

Null clears it.

currencystring

Three-letter code.

expected_close_datedate

YYYY-MM-DD; null clears it.

owner_iduuid

A team member; null for nobody.

curl -X PATCH "https://api.olee.ai/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "value": 18000,
  "expected_close_date": "2026-11-28"
}'

1 of 5

Saved.

{
  "success": true,
  "message": "Saved",
  "data": {
    "id": "9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f",
    "value": 18000,
    "expected_close_date": "2026-11-28"
  }
}

Try itAdd your API key at the top of the page

PATCH/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f

Parameters

projectSlugpathrequireddealIdpathrequired

Body application/json

Move a deal

To another stage of its own pipeline, at the top of the column.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

dealIduuidrequired

The deal's id.

Body

stage_idintegerrequired

A stage of the deal's own pipeline.

curl -X POST "https://api.olee.ai/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f/move" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "stage_id": 102
}'

1 of 5

Moved.

{
  "success": true,
  "message": "Moved",
  "data": {
    "id": "9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f",
    "stage_id": 102,
    "moved": true
  }
}

Try itAdd your API key at the top of the page

POST/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f/move

Parameters

projectSlugpathrequireddealIdpathrequired

Body application/json

Mark a deal won

The sale happened. Send the value it was won for if it differs.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

dealIduuidrequired

The deal's id.

Body

valuenumber

What it was won for.

curl -X POST "https://api.olee.ai/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f/won" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "value": 26500
}'

1 of 4

Won.

{
  "success": true,
  "message": "Won",
  "data": {
    "id": "9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f",
    "status": "won",
    "value": 26500,
    "closed_at": "2026-10-12T09:00:00.000Z"
  }
}

Try itAdd your API key at the top of the page

POST/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f/won

Parameters

projectSlugpathrequireddealIdpathrequired

Body application/json

Mark a deal lost

The sale did not happen, and why: one of the project's lost reasons.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

dealIduuidrequired

The deal's id.

Body

lost_reason_idintegerrequired

From List pipelines and stages.

lost_notestring

Up to 500 characters.

curl -X POST "https://api.olee.ai/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f/lost" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lost_reason_id": 7,
  "lost_note": "Found one cheaper"
}'

1 of 5

Lost.

{
  "success": true,
  "message": "Lost",
  "data": {
    "id": "9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f",
    "status": "lost",
    "lost_reason": {
      "id": 7,
      "label": "Price too high"
    }
  }
}

Try itAdd your API key at the top of the page

POST/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f/lost

Parameters

projectSlugpathrequireddealIdpathrequired

Body application/json

Set deal fields

Fill in some of a deal's fields, by key. Fields you leave out are left alone; an empty string or null clears one.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

dealIduuidrequired

The deal's id.

Body

valuesobjectrequired

Field key (or id) to value. All or nothing: one that does not fit refuses the save, and says which.

curl -X PATCH "https://api.olee.ai/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f/fields" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "values": {
    "event_date": "2026-11-30",
    "deposit_paid": true
  }
}'

1 of 5

Saved. Every field comes back, with this deal's value for it.

{
  "success": true,
  "message": "Fields saved",
  "data": {
    "fields": [
      {
        "id": 4,
        "key": "event_date",
        "label": "Event date",
        "type": "date",
        "options": [],
        "value": "2026-11-30",
        "is_readable": true
      },
      {
        "id": 5,
        "key": "deposit_paid",
        "label": "Deposit paid",
        "type": "checkbox",
        "options": [],
        "value": true,
        "is_readable": true
      }
    ],
    "available": true
  }
}

Try itAdd your API key at the top of the page

PATCH/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f/fields

Parameters

projectSlugpathrequireddealIdpathrequired

Body application/json

Add a note to a deal

Leave a note on a sale for your team. The customer never sees it.

A note added with a key has no author, so nobody can edit or remove it later.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

dealIduuidrequired

The deal's id.

Body

bodystringrequired

The note, up to 2000 characters.

curl -X POST "https://api.olee.ai/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f/notes" \
  -H "Authorization: Bearer $OLEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Paid the deposit by bank transfer."
}'

1 of 4

The note is on the deal.

{
  "success": true,
  "message": "Note added",
  "data": {
    "id": 82,
    "body": "Paid the deposit by bank transfer.",
    "is_readable": true,
    "created_at": "2026-10-12T04:00:00.000Z",
    "edited_at": null,
    "is_edited": false,
    "author": null,
    "author_id": null
  }
}

Try itAdd your API key at the top of the page

POST/v4/deals/my-shop/9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f/notes

Parameters

projectSlugpathrequireddealIdpathrequired

Body application/json

List a customer's deals

Every deal for one customer, open ones first.

Path

projectSlugstringrequired

Your project's slug, the last part of its address in the workspace. The key must belong to this project.

conversationIduuidrequired

The conversation's id.

curl -X GET "https://api.olee.ai/v4/deals/my-shop/contacts/4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90" \
  -H "Authorization: Bearer $OLEON_API_KEY"

1 of 5

Always.

{
  "success": true,
  "message": "Contact deals",
  "data": {
    "deals": [
      {
        "id": "9d2b6c1e-3f4a-4e5b-8c7d-1a2b3c4d5e6f",
        "title": "Wedding cake for 30 Nov",
        "value": 25000,
        "currency": "LKR",
        "status": "open",
        "stage": {
          "id": 101,
          "name": "New",
          "kind": "open",
          "color": "gray"
        }
      }
    ]
  }
}

Try itAdd your API key at the top of the page

GET/v4/deals/my-shop/contacts/4f6a1c2e-8b1d-4d7e-9a0b-2c5e7f1d3a90

Parameters

projectSlugpathrequiredconversationIdpathrequired