Open main menu
Start monitoring communities

API Documentation

 

Introduction

A REST API to retrieve groups data, powered by Leadhall.com
Rate limit: 60 requests per minute.
For any tech issues, just reach out to: mike@flatnine.co

Base URL

The base URL for all API requests is:
https://groups.leadhall.com/api

Authorization

All POST requests must be authorized by passing the following parameter to the request:
  • apiKey (required) (var): your API key, which you can retrieve in your account’s settings.
 

Endpoints

POST /account/info

Returns information on your Groouply account.

Parameters

  • No additional parameters are required.

Response

Returns a JSON object with the following properties:
  • account
    • groups
      • all: Number of total groups on the account
      • tracking: Number of groups Groouply is actually monitoring
  • registered: Date the account was registered

Example

Request:
POST /account/info
Response:
{
  "code": 1,
  "status": 200,
  "data": "Success",
  "request": {
    "user": {
      "name": "Account name",
      "id": "1"
    }
  },
  "account": {
    "registered": "2019-02-03",
    "groups": {
      "all": 4,
      "tracking": 3
    }
  }
}

POST /account/groups

Returns information on groups in your account.

Parameters

  • No additional parameters are required

Response

Returns a JSON object with the following properties:
  • groups
    • id: the Fb id of the group
    • status: a numerical identifier of the status of the group (0-2)
    • statusString: a text identifier of the status of the group (tracking, pending access)
    • url
      • facebook: the Fb URL of the group
      • groouply: the groouply URL of the group
 

Example

Request:
POST /account/groups
Response:
{
  "code": 1,
  "status": 200,
  "data": "Success",
  "request": {
    "user": {
      "name": "Account name",
      "id": "1"
    }
  },
  "groups": [
    {
      "id": "965673390154514",
      "status": "2",
      "statusString": "tracking",
      "url": {
        "facebook": "https://facebook.com/groups/965673390154514",
        "groouply": "https://groouply.com/group/965673390154514"
      }
    },
    {
      "id": "1613874192275516",
      "status": "2",
      "statusString": "tracking",
      "url": {
        "facebook": "https://facebook.com/groups/1613874192275516",
        "groouply": "https://groouply.com/group/1613874192275516"
      }
    },
    {
      "id": "1617905175110739",
      "status": "2",
      "statusString": "tracking",
      "url": {
        "facebook": "https://facebook.com/groups/1617905175110739",
        "groouply": "https://groouply.com/group/1617905175110739"
      }
    },
    {
      "id": "2044902829088090",
      "status": "1",
      "statusString": "pending access",
      "url": {
        "facebook": "https://facebook.com/groups/2044902829088090",
        "groouply": "https://groouply.com/group/2044902829088090"
      }
    }
  ]
}

POST /account/group

Returns mentions of your keywords in a certain group

Parameters

  • groupId (required) (int): the Fb group ID of a group in your account, which you can retrieve by querying /account/groups

Response

Returns a JSON object with the following properties:
  • group
    • info
      • id: the Fb ID of the group
      • status: a numerical identifier of the status of the group (0-2)
      • statusString: a text identifier of the status of the group (tracking, pending access)
      • name: the group name
      • description: the description of the group
      • owner: name of the owner of the group
      • privacy: privacy of the group (public, private, secret)
    • keywords :an array of keywords Groouply is monitoring in the group)
      • name: keyword name
      • type: broad or exact
    • posts: an array of mentions
      • owner
        • id: the Fb id of the owner of the post on Fb
        • name: the name of the owner of the post on Fb
      • keyword: the keyword that was spotted
      • link: the link to the conversation on Fb
      • timestamps
        • spotted: a timestamp indicating when Groouply spotted the keyword
        • sent: a timestamp indicating when Groouply notified the user
         

Example

Request:
POST /account/group
Response:
{
  "code": 1,
  "status": 200,
  "data": "Success",
  "request": {
    "user": {
      "name": "Account name",
      "id": "1"
    }
  },
  "group": {
    "info": {
      "name": "Group name",
      "description": "Description of the group",
      "owner": "Owner name",
      "privacy": "private",
      "id": "965673390154514",
      "status": "2",
      "statusString": "tracking"
    },
    "keywords": [
      {
        "name": "your keyword 1",
        "type": "broad",
      },
			..
    ],
    "posts": [
      {
        "owner": {
          "name": "Post owner name",
          "id": "663928841"
        },
        "keyword": "your keyword 1",
        "link": "https://facebook.com/groups/965673390154514/permalink/6719635918091537",
        "timestamps": {
          "spotted": "1699453217",
          "sent_email": "1699462865",
          "sent_sms": null,
          "sent_slack": "1699462863",
          "sent": "1699462865"
        }
      },
      ..
    ]
  }
}

POST /account/mentions

Returns the last 100 mentions in your account. You can query this endpoint at regular intervals to always fetch the latest mentions.

Parameters

  • No additional parameters are required

Response

Returns a JSON object with the following properties:
  • mentions: an array of mentions
    • id: the Fb ID of the post
    • keyword: the keyword Groouply spotted in the post
    • position: where Groouply spotted the keyword (in the body of the post, in a comment of the post, or in a link in the post)
    • content: the content of the post
    • link: the link to the conversation on Fb
    • owner
      • name: the name of the owner of the post
      • id: the Fb ID of the owner of the post
      • link: the link to the profile of the owner of the post
    • group
      • id: the Fb ID of the group where Groouply spotted the keyword
      • name: the name of the group where Groouply spotted the keyword
    • spotted: a timestamp indicating when Groouply spotted the keyword
 

Example

Request:
POST /account/mentions
Response:
{
  "code": 1,
  "status": 200,
  "data": "Success",
  "request": {
    "user": {
      "name": "Account name",
      "id": "1"
    }
  },
  "mentions": [
    {
      "id": "29439935",
      "keyword": "Keyword name 1",
      "position": "post",
      "content": "Post content",
      "link": "https://facebook.com/groups/1617905175110739/permalink/3805136229720945",
      "owner": {
        "name": "Post owner name",
        "id": "100073695043540",
        "link": "https://facebook.com/profile.php?id=100073695043540"
      },
      "group": {
        "id": "1617905175110739",
        "name": "Real Estate Referral Network"
      },
      "spotted": "1699459488"
    },
    ..
  ]
}
 

Errors

This API uses the following error codes:
  • 400 Bad Request: The request was malformed or missing the required parameters.
  • 401 Unauthorized: The API key provided was invalid or missing.
  • 403 Forbidden: The API key provided was invalid or missing.
  • 404 Not Found: The requested resource was not found.
  • 500 Internal Server Error: An unexpected error occurred on the server.