Skip to main content

How to connect to Agorapulse's Open API

Learn how to connect to Agorapulse's Open API

The Agorapulse Open API allows you to work with your Agorapulse data outside of the Agorapulse app. You can pull analytics and social listening data into your own reporting tools, read and reply to Inbox items, manage calendar notes, and upload media to the Content Library.

In this article, we will cover:

Note: Open API is available to users on a Custom subscription plan. If you would like to change your plan to access this feature, feel free to reach out to us here.

How to generate an API key

Before reporting data retrieval and other actions can be performed using our Open API, you will first need to generate an API key. This can be done by:

  1. Click your avatar at the bottom left of the screen.

  2. Select Personal settings.

  3. Click API Keys.

  4. Click Create new API keys at the top right of the screen.

  5. Enter a name for the key and click Create.

  6. Click the Copy button
    ​Note: The secret key cannot be viewed again after you leave this screen

  7. Click Done.

Note: The API key is unique to each individual, and the permissions granted for API requests are contingent upon the access levels assigned to you. To be able to request data for all connected social profiles, it's recommended to use the API key of the org owner or manager with access to all social profiles.

How to authenticate your requests

The API authenticates requests with an API key sent in the X-API-KEY HTTP header. Every request must include it. A request without a valid key returns 401 Unauthorized.

To authenticate inside the API reference so that you can test calls in the browser, please follow the steps below:

  1. Open the API reference.

  2. Locate the Authentication panel in the right-hand column.

  3. Paste your API key into the Value field.

    Note: Click the X to the right of the field to delete the key.

Your key will remain in the Value field for the rest of your session, so you only need to enter it once.


How to obtain the required IDs

Before you can call the endpoints in the sections below, you will need to retrieve three IDs in the following order:

  1. Organization ID

  2. Workspace ID

  3. The Profile UID of the social profile you want to work with.

Note: To retrieve these IDs, you will need to use our API doc: https://api.agorapulse.com/docs


How to retrieve your Organization ID

First, you will need your organization's ID. This can be done by:

  1. Open the API reference and confirm that your API key is set in the Authentication panel.

  2. Under Account & Workspaces, click Organizations

  3. Select Get manager organizations from the drop-down

  4. Under Get manager organizations, click Test Request

  5. At the top of the window, click Send

A list will appear on the right side of the window showing a list of the organizations that you are part of, including the organizationId. You will want to copy the organization ID to retrieve your Workspace ID.


How to retrieve your Workspace ID

After you have copied the Organization ID of the Organization that you would like to use, you will need to retrieve the Workspace ID. This can be done by:

  1. Under Account & Workspaces, click Workspaces

  2. Then select Get organization workspaces

  3. Click Test Request

  4. Under Variables, enter your organization ID in the organizationID field

  5. Click Send

A list will appear on the right side of the window showing a list of the available workspaces in your organization. Copy the workspace ID of the workspace you want to use.

Please note: Unless Workspaces are enabled in your organization, only one workspace ID will be displayed.

How to retrieve your Profile UID

The last ID that you will need to retrieve is the ID of the social profile that you are going to be requesting data from. This can be done by:

  1. Under Account & Workspaces, click Profiles

  2. Then select Get workspace profiles

  3. Click Test Request

  4. Under Variables, enter your Organization ID and Workspace ID in the relevant fields

  5. Click Send

A list will appear on the right side of the window showing a list of the social profiles that you have access to in your organization. Copy the profile UIDs of the social profiles you would like to use

Important information

  • There is a limit of 500 requests per 30 minutes.

  • It's Read-only access - You won't be able to modify or take any action via the API.

  • Custom reports and Social Media ROI reports are not part of the API.

Did this answer your question?