# hootsuite OpenAPI overview

> Below is an overview of the hootsuite openapi in simple language. This API contains 48 endpoints.

For more detailed information of an endpoint, visit https://oapis.org/summary/hootsuite/[idOrRoute]

Hootsuite REST API v1.0 - https://platform.hootsuite.com
[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/eeda0fcdf55ea26bd0ec#?env%5BHootsuite%5D=W3sidHlwZSI6InRleHQiLCJlbmFibGVkIjp0cnVlLCJrZXkiOiJ1cmwiLCJ2YWx1ZSI6Imh0dHBzOi8vcGxhdGZvcm0uaG9vdHN1aXRlLmNvbSJ9LHsidHlwZSI6InRleHQiLCJlbmFibGVkIjp0cnVlLCJrZXkiOiJhdXRob3JpemF0aW9uX3VybCIsInZhbHVlIjoiaHR0cHM6Ly9wbGF0Zm9ybS5ob290c3VpdGUuY29tL29hdXRoMi9hdXRoIn0seyJ0eXBlIjoidGV4dCIsImVuYWJsZWQiOnRydWUsImtleSI6InRva2VuX3VybCIsInZhbHVlIjoiaHR0cHM6Ly9wbGF0Zm9ybS5ob290c3VpdGUuY29tL29hdXRoMi90b2tlbiJ9LHsidHlwZSI6InRleHQiLCJlbmFibGVkIjp0cnVlLCJrZXkiOiJjbGllbnRfaWQiLCJ2YWx1ZSI6IiJ9LHsidHlwZSI6InRleHQiLCJlbmFibGVkIjp0cnVlLCJrZXkiOiJjbGllbnRfc2VjcmV0IiwidmFsdWUiOiIifV0=)
# Introduction
The Hootsuite API is built on REST principles and uses JSON as a data interchange format.
### Base URL
All URLs referenced in this document use the following base: https://platform.hootsuite.com. The Hootsuite API is served over HTTPS to ensure data privacy.
### Request Format
The Hootsuite API supports the following HTTP verbs:
| Verb       | Description  |
|--------|------|
| GET    | GET requests retrieve resources. GET requests with query parameters should be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding).  |
| POST   | POST requests create or update resources. POST requests can partially update a resource by passing a subset of the fields that should be updated. To remove a single field set it to null. POST requests should always set content-type and character encoding to: application/json;charset=utf-8. |
| DELETE | DELETE requests delete resources. Delete requests return a 200 OK with an empty data envelope if the request was successful.|
### Response Format
All responses are returned in JSON. The response is wrapped in a top level data envelope which is an object or array depending on whether a single item or a collection is returned. If a single item is returned the data field will be an object. If a collection is returned the field will be an array.
If the response was unsuccessful an errors array will be returned. Responses that partially fail will return both a data and errors object.
A single item response:
```
{
  "data": {},
  "errors": [{},{},{}]
}
```
A collection response:
```
{
  "data": [{},{},{}],
  "errors": [{},{},{}]
  "metadata": {}
}
```
### HTTP Response Codes
The Hootsuite API uses HTTP status codes to indicate the status of your request.
|Code |Description |
|---|---|
|200 OK|Resource was successfully created, updated, deleted or retrieved.|
|400 Bad Request|Invalid request, possibly due to missing parameters|
|401 Unauthorized|Missing or invalid authentication|
|403 Forbidden|Access denied|
|404 Not Found|Requested resource does not exist|
|429 Too Many Requests|Rate Limit Exceeded. Please contact dev.support@hootsuite.com for assistance|
|500 Server Error|Unexpected error occurred on the server|
### API Error Handling
Error responses are returned with the following fields. Note, the schema for OAuth2 error responses are different and comply with the RFC. Please refer to the Authorization endpoint documentation for details.
|Field|Description|
|---|---|
|code|Unique number indicating type of error|
|message|Description of error|
|id|Unique id for tracing purposes|
|resource|(optional) type and id are used to point to the field(s) that caused the error|
```
{
  "errors": [
    {
      "code" : 1234,
      "message": "Could not create message for social profile",
      "id" : "f7d32670-4e6a-48c0-a2a7-87803536a712",
      "resource": {
        "type":"socialProfile",
        "id":"7534653235"
      }
    }
  ]
}
```
### Error Codes
Here is a list of error codes and descriptions returned by our APIs:
|Code|Description|
|---|---|
|1000|Missing or duplicate access token|
|1001|Invalid access token|
|1002|Invalid API key|
|1003|Account plan limit exceeded|
|1004|API plan limit exceeded|
|1005|Token could not be retrieved|
|1006|Token removal failed|
|1007|The client could not be authenticated due to missing or invalid client credentials|
|1008|Resource Owner authentication failed|
|1009|Invalid grant_type|
|1010|Invalid OAuth request|
|1011|Duplicate OAuth parameters|
|1012|Invalid authorization code|
|1013|Must be confidential client|
|1014|Unauthorized JWT user|
|1015|Client registration could not be deleted|
|1016|Client info could not be retrieved|
|1017|Client info could not be updated|
|1018|Client could not be registered|
|1019|A registration type must be selected|
|1020|Client key could not be deleted|
|1021|The id_token values could not be retrieved|
|1022|id_token could not be registered|
|1023|id_token could not be removed therefore user logout could not be executed|
|1024|Token could not be revoked|
|1025|Token could not be registered|
|1026|Non-valid parameter list for this operation|
|1027|Missing authorization code|
|1028|Authorization code could not be validated|
|1029|id_token could not be validated|
|1030|The client is not authorized to execute a status check|
|1031|Invalid oauth parameters|
|1032|Token could not be validated|
|1033|The requested scope is not valid|
|1034|The session is not valid|
|1035|Missing oauth_token parameter|
|1036|oauth_token invalid or expired|
|1037|The required scope to access this endpoint was not granted by the user|
|1038|token_type_hint is not supported|
|1039|Client not authorized to revoke token|
|1040|oauth_consumer_key invalid or expired|
|1041|The token may not have been revoked due to an unknown error|
|1042|Missing oauth_signature|
|1043|Too many requests|
|1044|Invalid oauth_signature_method|
|1100|Invalid JSON schema|
|1201|Not authorized to make changes to organization|
|2000|Invalid member password|
|2001|Invalid member email|
|2002|Invalid member name (please enter name between 2 and 100 chars in length)|
|2003|Invalid member default timezone|
|2004|Invalid initials|
|2005|Missing member name|
|2006|Missing member email|
|2007|Missing member password|
|2008|No more available seats in organization|
|2303|Invalid organization ID|
|2304|Invalid member ID|
|2305|Missing member ID|
|2306|Missing social profile ID|
|3002|Team name has to be between 2-200 characters|
|3003|Unable to find an organization with that ID|
|3004|Missing team ID|
|3005|Invalid team ID|
|3006|Team name has to be unique in the organization|
|3008|Member is not seated in the organization|
|3010|Email is already in use|
|3020|Invalid cursor format|
|3021|Invalid social network type|
|3301|Payment member can’t be removed from the organization|
|4000|Schema validation failed|
|4001|Resource not found|
|4002|Insufficient permissions to view organization members|
|4003|Insufficient permissions to view member permissions|
|4004|Insufficient permissions to view member organizations|
|4005|Insufficient permissions to view team members|
|4006|Insufficient permissions to view team|
|4007|Insufficient permissions to create team|
|4008|Insufficient permissions to view team social profile|
|4009|Insufficient organization permissions|
|4010|Insufficient permissions to view organization teams|
|4303|Member does not exist in organization|
|5000|An unknown error occurred|
|5001|HTTP method not permitted|
|5002|Unsupported operation|
|9000|An internal error occurred|
|40001|Social profile isn’t owned by organization (required for posting messages with tags)|
|40003|You have attempted to delete a message that cannot be deleted in its current state|
|40004|Only attachments from http://static.ow.ly or http://ow.ly/i/ are currently allowed|
|40005|Insufficient permission to create new message tags|
|40019|Message state filter not supported|
|40020|Specified date range is too large|
|40021|Uploaded media is not yet ready to be used (further processing required)|
|40022|Invalid boolean for includeUnscheduledReviewMsgs flag|
|40023|Twitter only allows 1 network per message|
|40024|Posting to Facebook Groups is no longer supported|
|40025|Scheduled message limit reached|


## Authentication

Hootsuite uses OAuth2 to authenticate end users. Members authenticated with the Hootsuite API are subject to the same permissions configured as when using the Hootsuite Web Dashboard. Learn more about managing permissions at the [Hootsuite Help Center](https://help.hootsuite.com/hc/en-us/articles/204598170-About-organizations-teams-and-permissions).

- [oauth2Authorize](https://oapis.org/openapi/hootsuite/oauth2Authorize): GET https://platform.hootsuite.com/oauth2/auth?response_type=string&client_id=string&scope=string&redirect_uri=string&state=string - OAuth2 Authorize
- [oauth2Token](https://oapis.org/openapi/hootsuite/oauth2Token): POST https://platform.hootsuite.com/oauth2/token - OAuth2 Token

## Comments

- [retrieveComment](https://oapis.org/openapi/hootsuite/retrieveComment): GET https://platform.hootsuite.com/v1/comments/{commentId} - Retrieve comment
- [approveComment](https://oapis.org/openapi/hootsuite/approveComment): POST https://platform.hootsuite.com/v1/comments/{commentId}/approve - Approve comment
- [rejectComment](https://oapis.org/openapi/hootsuite/rejectComment): POST https://platform.hootsuite.com/v1/comments/{commentId}/reject - Reject comment

## Me

The Me API returns information about the user that has authenticated with the API.

- [retrieveMe](https://oapis.org/openapi/hootsuite/retrieveMe): GET https://platform.hootsuite.com/v1/me - Retrieve authenticated member
- [retrieveMeOrganizations](https://oapis.org/openapi/hootsuite/retrieveMeOrganizations): GET https://platform.hootsuite.com/v1/me/organizations - Retrieve authenticated member's organizations
- [getMySocialProfiles](https://oapis.org/openapi/hootsuite/getMySocialProfiles): GET https://platform.hootsuite.com/v1/me/socialProfiles - Retrieve authenticated member's social profiles
- [getMyAdAccounts](https://oapis.org/openapi/hootsuite/getMyAdAccounts): GET https://platform.hootsuite.com/v1/me/adAccounts?organization_id=string - Retrieve authenticated member's ad accounts

## Media

- [createMedia](https://oapis.org/openapi/hootsuite/createMedia): POST https://platform.hootsuite.com/v1/media - Create media upload url
- [getMedia](https://oapis.org/openapi/hootsuite/getMedia): GET https://platform.hootsuite.com/v1/media/{mediaId} - Retrieve media upload status

## Members

- [retrieveMember](https://oapis.org/openapi/hootsuite/retrieveMember): GET https://platform.hootsuite.com/v1/members/{memberId} - Retrieve member
- [createMember](https://oapis.org/openapi/hootsuite/createMember): POST https://platform.hootsuite.com/v1/members - Create member
- [retrieveMemberOrganizationsById](https://oapis.org/openapi/hootsuite/retrieveMemberOrganizationsById): GET https://platform.hootsuite.com/v1/members/{memberId}/organizations - Retrieve member's organizations

## Messages

- [retrieveMessages](https://oapis.org/openapi/hootsuite/retrieveMessages): GET https://platform.hootsuite.com/v1/messages?startTime=string&endTime=string&state=string&socialProfileIds=integer&limit=integer&cursor=string&includeUnscheduledReviewMsgs=boolean - Retrieve outbound messages
- [scheduleMessage](https://oapis.org/openapi/hootsuite/scheduleMessage): POST https://platform.hootsuite.com/v1/messages - Schedule messages
- [retrieveMessage](https://oapis.org/openapi/hootsuite/retrieveMessage): GET https://platform.hootsuite.com/v1/messages/{messageId} - Retrieve message
- [deleteMessage](https://oapis.org/openapi/hootsuite/deleteMessage): DELETE https://platform.hootsuite.com/v1/messages/{messageId} - Delete message
- [approveMessage](https://oapis.org/openapi/hootsuite/approveMessage): POST https://platform.hootsuite.com/v1/messages/{messageId}/approve - Approve message
- [rejectMessage](https://oapis.org/openapi/hootsuite/rejectMessage): POST https://platform.hootsuite.com/v1/messages/{messageId}/reject - Reject message
- [getMessageHistory](https://oapis.org/openapi/hootsuite/getMessageHistory): GET https://platform.hootsuite.com/v1/messages/{messageId}/history - Get message review history

## Organizations

- [getOrganizationTeams](https://oapis.org/openapi/hootsuite/getOrganizationTeams): GET https://platform.hootsuite.com/v1/organizations/{organizationId}/teams - Retrieve organization teams
- [retrieveOrganizationMembers](https://oapis.org/openapi/hootsuite/retrieveOrganizationMembers): GET https://platform.hootsuite.com/v1/organizations/{organizationId}/members - Retrieve organization members
- [removeMemberFromOrganization](https://oapis.org/openapi/hootsuite/removeMemberFromOrganization): DELETE https://platform.hootsuite.com/v1/organizations/{organizationId}/members/{memberId} - Remove member from organization
- [retrieveOrganizationMemberOrganizationPermissions](https://oapis.org/openapi/hootsuite/retrieveOrganizationMemberOrganizationPermissions): GET https://platform.hootsuite.com/v1/organizations/{organizationId}/members/{memberId}/permissions - Retrieve org member's organization permissions
- [retrieveOrganizationMembersTeams](https://oapis.org/openapi/hootsuite/retrieveOrganizationMembersTeams): GET https://platform.hootsuite.com/v1/organizations/{organizationId}/members/{memberId}/teams - Retrieve org member's teams
- [retrieveOrganizationMembersSocialProfiles](https://oapis.org/openapi/hootsuite/retrieveOrganizationMembersSocialProfiles): GET https://platform.hootsuite.com/v1/organizations/{organizationId}/members/{memberId}/socialProfiles - Retrieve org member’s social profiles
- [retrieveOrganizationSocialProfilePermissions](https://oapis.org/openapi/hootsuite/retrieveOrganizationSocialProfilePermissions): GET https://platform.hootsuite.com/v1/organizations/{organizationId}/members/{memberId}/socialProfiles/{socialProfileId}/permissions - Retrieve org member’s social profile permissions

## SCIM 2.0

- [getScimUsers](https://oapis.org/openapi/hootsuite/getScimUsers): GET https://platform.hootsuite.com/scim/v2/Users?filter=string&count=number&startIndex=number - Get Users
- [createScimUser](https://oapis.org/openapi/hootsuite/createScimUser): POST https://platform.hootsuite.com/scim/v2/Users - Create User
- [getScimUser](https://oapis.org/openapi/hootsuite/getScimUser): GET https://platform.hootsuite.com/scim/v2/Users/{memberId} - Get User
- [replaceScimUser](https://oapis.org/openapi/hootsuite/replaceScimUser): PUT https://platform.hootsuite.com/scim/v2/Users/{memberId} - Replace User
- [modifyScimUser](https://oapis.org/openapi/hootsuite/modifyScimUser): PATCH https://platform.hootsuite.com/scim/v2/Users/{memberId} - Modify User
- [getScimGroups](https://oapis.org/openapi/hootsuite/getScimGroups): GET https://platform.hootsuite.com/scim/v2/Groups?filter=string&count=number&startIndex=number - Get Groups
- [createScimGroup](https://oapis.org/openapi/hootsuite/createScimGroup): POST https://platform.hootsuite.com/scim/v2/Groups - Create Group
- [getScimGroup](https://oapis.org/openapi/hootsuite/getScimGroup): GET https://platform.hootsuite.com/scim/v2/Groups/{groupId} - Get Group
- [replaceScimGroup](https://oapis.org/openapi/hootsuite/replaceScimGroup): PUT https://platform.hootsuite.com/scim/v2/Groups/{groupId} - Replace Group
- [modifyScimGroup](https://oapis.org/openapi/hootsuite/modifyScimGroup): PATCH https://platform.hootsuite.com/scim/v2/Groups/{groupId} - Modify Group
- [getScimResourceTypes](https://oapis.org/openapi/hootsuite/getScimResourceTypes): GET https://platform.hootsuite.com/scim/v2/ResourceTypes - Get Resource Types

## Social Profiles

A social profile is a publishing channel on a social network account.

- [getSocialProfiles](https://oapis.org/openapi/hootsuite/getSocialProfiles): GET https://platform.hootsuite.com/v1/socialProfiles - Retrieve social profiles
- [getSocialProfile](https://oapis.org/openapi/hootsuite/getSocialProfile): GET https://platform.hootsuite.com/v1/socialProfiles/{socialProfileId} - Retrieve social profile
- [getSocialProfileTeams](https://oapis.org/openapi/hootsuite/getSocialProfileTeams): GET https://platform.hootsuite.com/v1/socialProfiles/{socialProfileId}/teams - Retrieve social profile's teams

## Teams

- [createTeam](https://oapis.org/openapi/hootsuite/createTeam): POST https://platform.hootsuite.com/v1/organizations/{organizationId}/teams - Create team
- [addMemberToTeam](https://oapis.org/openapi/hootsuite/addMemberToTeam): POST https://platform.hootsuite.com/v1/organizations/{organizationId}/teams/{teamId}/members/{memberId} - Add member to team
- [getTeamMembers](https://oapis.org/openapi/hootsuite/getTeamMembers): GET https://platform.hootsuite.com/v1/organizations/{organizationId}/teams/{teamId}/members - Retrieve team members
- [retrieveOrganizationMembersTeamPermissions](https://oapis.org/openapi/hootsuite/retrieveOrganizationMembersTeamPermissions): GET https://platform.hootsuite.com/v1/organizations/{organizationId}/teams/{teamId}/members/{memberId}/permissions - Retrieve team member's permissions
- [retrieveOrganizationTeamsSocialProfiles](https://oapis.org/openapi/hootsuite/retrieveOrganizationTeamsSocialProfiles): GET https://platform.hootsuite.com/v1/organizations/{organizationId}/teams/{teamId}/socialProfiles - Retrieve org team’s social profiles
- [getTeam](https://oapis.org/openapi/hootsuite/getTeam): GET https://platform.hootsuite.com/v1/teams/{teamId} - Retrieve team