Reference

Organization and channels Beta

On this page

These endpoints describe your key, your organization, its channels and its people. Use them to find the IDs that other endpoints take.

Describe the key

GET /v1/apiKey · any scope

Returns the key that issued the token, and the person the token acts for. Use it to check a new key or token.

curl https://api.conclude.io/v1/apiKey -H "Authorization: Bearer $ACCESS_TOKEN"
{
  "id": "J-1k3m5o7q9",
  "name": "Helpdesk",
  "scopes": ["connections:readwrite", "org:read"],
  "expires": "2027-10-27T00:00:00Z",
  "global": true,
  "organization": {
    "id": "O-2a4c6e8g",
    "name": "Example Corp"
  },
  "actsFor": {
    "id": "U-3b5d7f9h",
    "name": "Kim Lee"
  }
}
FieldTypeDescription
idstringThe key’s ID. It is also its client ID.
namestringThe name the admin gave the key.
scopesarray of stringsThe key’s scopes.
expirestimeWhen the key expires.
globalbooleantrue when the key acts as Conclude.
organizationobjectYour organization’s id and name.
actsForobjectThe id and name of the person the token acts for. A key that acts as Conclude, used without a subject, acts for no one and has no actsFor.
StatusCodeWhen
403forbiddenThe token doesn’t come from an API key.

Get the organization

GET /v1/organization · scope org:read

Returns your organization and its workspaces. A workspace is a Slack workspace or a Microsoft Teams tenant.

curl https://api.conclude.io/v1/organization -H "Authorization: Bearer $ACCESS_TOKEN"
{
  "id": "O-2a4c6e8g",
  "name": "Example Corp",
  "workspaces": [
    {
      "id": "T-4c6e8g0i",
      "name": "Example",
      "platform": "slack",
      "sysID": "T04ABCDEF12"
    },
    {
      "id": "T-5d7f9h1j",
      "name": "Example Corp",
      "platform": "teams",
      "sysID": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    }
  ]
}
FieldTypeDescription
idstringYour organization’s ID.
namestringYour organization’s name.
workspacesarrayYour Slack workspaces and Microsoft Teams tenants.
workspaces[].idstringThe workspace’s Conclude ID.
workspaces[].namestringThe workspace’s name.
workspaces[].platformstringslack or teams.
workspaces[].sysIDstringThe Slack workspace ID, or the Microsoft Teams tenant ID. Use it as sysTeamID in GET /v1/findChannel.
StatusCodeWhen
403forbiddenThe person the token acts for has no access to your organization.

Find channels

GET /v1/findChannel · scope org:read

Finds channels by name or by their Slack or Teams ID. It returns the Conclude channel IDs that the Connections requests take.

ParameterDescription
nameThe channel’s name. The match is exact but ignores case. A leading # is ignored.
sysChannelIDThe Slack channel ID, such as C07ABCDEF12, or the Microsoft Teams channel ID, such as 19:a1b2c3@thread.tacv2.
sysTeamIDOptional. Limits the search to one Slack workspace, one team in Microsoft Teams, or one Microsoft Teams tenant. Use the Slack workspace ID, the team’s group ID, or the tenant ID.

Give either name or sysChannelID, not both.

curl -G https://api.conclude.io/v1/findChannel \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "name=it-help"
{
  "channels": [
    {
      "id": "C-6e8g0i2k",
      "name": "it-help",
      "platform": "slack",
      "sysID": "C07ABCDEF12",
      "private": false,
      "shared": false,
      "connected": false,
      "workspace": {
        "id": "T-4c6e8g0i",
        "name": "Example",
        "sysID": "T04ABCDEF12"
      },
      "team": {
        "name": "Example",
        "sysID": "T04ABCDEF12"
      },
      "url": "slack://channel?team=T04ABCDEF12&id=C07ABCDEF12"
    }
  ]
}
FieldTypeDescription
idstringThe channel’s Conclude ID.
namestringThe channel’s name.
platformstringslack or teams.
sysIDstringThe Slack or Microsoft Teams channel ID.
privatebooleantrue for a private channel.
sharedbooleantrue for a Slack Connect channel or a Microsoft Teams shared channel.
connectedbooleantrue when the channel is already in a connection.
workspaceobjectThe Slack workspace or Microsoft Teams tenant, with its id, name and sysID.
teamobjectThe channel’s team in Microsoft Teams, with its name and sysID. On Slack, it is the workspace.
urlstringA link that opens the channel in Slack or Microsoft Teams. A Slack link opens the Slack app.

The search returns regular channels only. It leaves out direct messages, group chats, and archived or deleted channels. The results are sorted by name and are not paged. No match returns an empty list.

A search can return more than one channel:

  • The same name can exist in several teams or workspaces. Add sysTeamID to pick one
  • In Slack Enterprise Grid, a channel shared between workspaces appears once for each workspace

The search finds the channels that the person the token acts for can access. That means channels in teams where they have an account, and private channels where they are a member. A key that acts as Conclude, used without a subject, finds every channel, including private channels that Conclude is not in.

StatusCodeWhen
400invalid_requestNeither or both of name and sysChannelID are given. param is name.
403forbiddenThe person the token acts for has no access to your organization.

Find users

GET /v1/findUser · scope users:read

Finds people in your organization by email address or by their Slack or Microsoft Teams user ID. It returns the Conclude user IDs that the Chats requests take, and each person’s accounts.

ParameterDescription
emailThe email address of one of the person’s accounts. The match ignores case.
sysUserIDThe Slack user ID, such as U07ABCDEF12, or the Microsoft Teams user’s object ID in Entra ID.

Give either email or sysUserID, not both.

curl -G https://api.conclude.io/v1/findUser \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "email=ana@example.com"
{
  "users": [
    {
      "id": "U-2b4d6f8h",
      "mention": "Ana",
      "name": "Ana Silva",
      "email": "ana@example.com",
      "accounts": [
        {
          "platform": "slack",
          "sysUserID": "U07ABCDEF12",
          "email": "ana@example.com",
          "workspace": {
            "id": "T-4c6e8g0i",
            "name": "Example",
            "sysID": "T04ABCDEF12"
          }
        }
      ]
    }
  ]
}
FieldTypeDescription
idstringThe person’s Conclude user ID.
mentionstringThe name people use to mention the person in Slack or Microsoft Teams.
namestringThe person’s full name. It is the same as mention when Conclude doesn’t know the full name.
emailstringThe person’s email address, when Conclude knows it.
avatarstringThe URL of the person’s picture, when there is one.
accountsarrayThe person’s active accounts in your Slack workspaces and Microsoft Teams tenants. Each has a platform, slack or teams, the account’s sysUserID and email, and its workspace, the Slack workspace or Microsoft Teams tenant, with its id, name and sysID.

The search finds people with an active account in one of your workspaces. No match returns an empty list. One person who has an account on each platform appears once, with both accounts.

StatusCodeWhen
400invalid_requestNeither or both of email and sysUserID are given. param is email.
403forbiddenThe person the token acts for has no access to your organization.