# Firstup API
What’s new

A quick summary of the latest API changes to this latest version 2026-03-06:

See the full changelog →
API Concepts and Overview

Each API concept can be found in our Docs; we give an overview of each API, the expected behavior and what is possible.

Technical details are found in this reference, but some complex technicalities are further explained in our docs.

Further technical guidance on SCIM patching, pagination and filtering can be found in our docs:

Technical Details From this page, you can download the OpenAPI specification for the Firstup API as a openapi.json or openapi.yaml file. This can be imported into tools such as Postman to generate a collection of test queries or converted into an SDK using Swagger Codegen. {% admonition type="info" %} Alternatively, you can use the try it function in this platform. In addition, select your preferred language for our request and response examples. {% /admonition %}

Authorization

All API endpoints use the JSON content type and require an auth token. See Authentication and Authorization for more details on token management. The token and content type should be explicitly set in the request headers. For example: 

  curl -X GET "https://partner.socialchorus.com/v2/channels" -H "accept: application/json" -H "Authorization: Bearer <ACCESS TOKEN>"
{% admonition type="info" %} This example uses the US1 region server. Check your region's server [here](/authorization/authenticationandauthorization). {% /admonition %}
Main API Sections

Version: 2026-03-06 ## Servers US1 ``` https://partner.socialchorus.com ``` US2 ``` https://partner.us2.onfirstup.com ``` EU ``` https://partner.onfirstup.eu ``` ## Security ### oauth2_as_a_server OAuth2 for Server-to-Server (Client Credentials grant flow) Type: oauth2 ### oauth2_as_a_user OAuth2 for Users (Authorization Code grant flow) Type: oauth2 ## Download OpenAPI description [Firstup API](https://developers.firstup.io/_bundle/endpoints/openapi.yaml) ## Content Publishing

The Content Publishing API provides access to content the same way Program Studio does, enabling the creation and updating of articles, links, videos, and images.

For contextual guidance on content publishing, and for use case examples, refer to our Content Publishing Overview page.

### Create a topic in the program - [POST /v2/channels](https://developers.firstup.io/endpoints/openapi/content-publishing/createchannel.md): Creates new topic in the program. A topic holds campaigns and users, organizing content for user consumption. Resources Knowledge Base article on Topics An overview on Content & Publishing API ### List all topics in the program - [GET /v2/channels](https://developers.firstup.io/endpoints/openapi/content-publishing/listchannels.md): Returns a list of topics and allows for sorting, filtering, and pagination of the records. Response body is an array of records. Resources Knowledge Base article on Topics An overview on Content & Publishing API Pagination Filtering ### Update a topic in the program - [PUT /v2/channels/{channel_id}](https://developers.firstup.io/endpoints/openapi/content-publishing/updatechannel.md): Updates a topic in the program ### List all followers of a topic - [GET /v2/channels/{channel_id}/followers](https://developers.firstup.io/endpoints/openapi/content-publishing/listchannelfollowers.md): Returns a list of all users who follow the topic, and allows for pagination of the records. Response body is an array of records. Resources Knowledge Base article on Topics An overview on Content & Publishing API Pagination ### List pages for a topic - [GET /v2/channels/{channel_id}/pages](https://developers.firstup.io/endpoints/openapi/content-publishing/listchannelpages.md): Returns a list of custom pages associated with a topic. ### Fetch a collection of content - [GET /v2/content](https://developers.firstup.io/endpoints/openapi/content-publishing/listcontent.md): Returns a list of content records and allows for sorting, filtering, and pagination of the records. This list can be used to pass into a topic. Response body is an array of records. Resources Knowledge Base article on Topics An overview on Content & Publishing API Pagination Filtering ### Create a new content post - [POST /v2/content](https://developers.firstup.io/endpoints/openapi/content-publishing/createcontent.md): Create a new content item and select what topics will include the content. {% admonition type="info" %}The new content will be created in the “draft” state. {% /admonition %} This endpoint only creates the post. If applicable, an image may be added later via the appropriate endpoint. If author.user_id is provided, it will be used to determine display_name and avatar_url, overriding any values provided for display_name and avatar_url. Response body data will be the newly created record. Resources Knowledge Base article on Campaigns An overview on Content & Publishing API Pagination Filtering Add an image Publish drafted content ### Fetch the details of a content post - [GET /v2/content/{content_id}](https://developers.firstup.io/endpoints/openapi/content-publishing/detailcontent.md): Read an existing content record. Returns a single record by identifier or by the content UUID. ### Update an existing content post - [PUT /v2/content/{content_id}](https://developers.firstup.io/endpoints/openapi/content-publishing/updatecontent.md): Update an existing content record. Content can be updated in any state, but some states have different validations. Any or all of the content attributes can be provided and only those provided will be updated. {% admonition type="info" %}This endpoint cannot be used to change content type, state, or topics. If author.user_id is provided, it will be used to determine display_name and avatar_url, overriding any values provided for display_name and avatar_url. To change the state (i.e. publish a draft) see Publish an existing content post.{% /admonition %} Response body data will be the updated record. ### Archive an existing content post - [PUT /v2/content/{content_id}/archive](https://developers.firstup.io/endpoints/openapi/content-publishing/archivecontent.md): Archive an existing content post. Transition the content state from any state directly to "archived". Response body contains the latest version of the content record. ### Draft an existing content post - [PUT /v2/content/{content_id}/draft](https://developers.firstup.io/endpoints/openapi/content-publishing/draftcontent.md): Transition the content state of an existing content post to draft. A post can be set to draft from any any current state. If the post was published or archived, it will no longer be. Response body is the updated record. Returns `400 Bad Request` if the content cannot be transitioned to 'draft' due to validation reasons. ### Publish an existing content post - [PUT /v2/content/{content_id}/publish](https://developers.firstup.io/endpoints/openapi/content-publishing/publishcontent.md): Change the state of the content to “published.” If the content is already in the “published” state, this request does nothing. Content in a “scheduled” state remains scheduled. For all other states, the content is published immediately. Publishing content requires that at least one topic be associated to the content, as content must always have at least one topic. Response body is the updated record. This endpoint returns `400 Bad Request` if the content cannot be published. Some attributes have validations that are only applied when moving content to the published state. For example, content cannot be published until its title has been filled in. ### Mark an existing post as ready for review - [PUT /v2/content/{content_id}/review](https://developers.firstup.io/endpoints/openapi/content-publishing/reviewcontent.md): Change the state of the post to "review". The post is immediately removed from feeds. Posts that are already in "review" state will not change. ### List the comments on a content post - [GET /v2/content/{content_id}/comments](https://developers.firstup.io/endpoints/openapi/content-publishing/listcontentcomments.md): List the comments on a content post. Only top-level comments are returned. Comments which are replies to other comments are not currently available through this endpoint. Upon enabling expanded reactions types, the response will include the additional reaction types. When a comment with user mentions is returned, it will be returned with those mentions in the format of either `{ref:user:} or {ref:user::id:}`. You can parse out the user_id and then look up the user and transform the mention metadata to the display_name/name of the referenced user. ### List the replies on comment post - [GET /v2/content/{content_id}/comments/{comment_id}/replies](https://developers.firstup.io/endpoints/openapi/content-publishing/listcontentcommentreplies.md): List the replies on comment post. Upon enabling expanded reactions types, the response will include the additional reaction types. When a comment with user mentions is returned, it will be returned with those mentions in the format of either `{ref:user:} or {ref:user::id:}`. You can parse out the user_id and then look up the user and transform the mention metadata to the display_name/name of the referenced user. ### Add an image to a content post - [PUT /v2/content/{content_id}/images](https://developers.firstup.io/endpoints/openapi/content-publishing/addcontentimage.md): Add a new image to a content record. Response body is the updated content record. {% admonition type="info" %}This API does not resize or rehost images. Images should be appropriately sized and will be served from the provided URL.{% /admonition %} ### Add a video for use in content of type article - [PUT /v2/content/{content_id}/videos](https://developers.firstup.io/endpoints/openapi/content-publishing/addcontentvideo.md): Add a new video to a content record. Response body is the attributes of the video record. Insert the returned embed_html into the body of the article at the location you want the video to appear in the article. ### Remove an image from a content post - [DELETE /v2/content/{content_id}/images/{content_image_id}](https://developers.firstup.io/endpoints/openapi/content-publishing/removecontentimage.md): Remove an image from a content record. Images cannot be removed from published content. Response status for removed content is 204 No Content. ### Fetch content replications - [GET /v2/content/replications](https://developers.firstup.io/endpoints/openapi/content-publishing/listcontentreplications.md): The endpoint allow users to get details of content replication. Source or target filter is required ### Get a download URL for a content video - [GET /v2/videos/{video_id}/download](https://developers.firstup.io/endpoints/openapi/content-publishing/downloadcontentvideo.md): Returns a temporary link to a content video. ### Fetch the unique count of users who can see the content post - [GET /v2/content/{content_id}/reach/unique_user_count](https://developers.firstup.io/endpoints/openapi/content-publishing/contentreachcount.md): Fetch the content reach, the unique user count for audiences, topics, and both. ## Feeds

The Feeds API provides access to lists of content similar to how a user sees them in the Firstup experience application. Feeds are specific to the authenticated user and a user can only see what the platform gives them access to.

At their core, feeds are built using filters to find the exact topics and type of posts your application wishes to expose to its users. One of the basic filters is the channels.id filter, but there are additional filters like content_type and visibility. There are also preset configurations called named feeds, which uses the name query parameter and are convenient wrappers around a set of filters. These include things like "trending" posts, "following", and "myfeed".
The full list of feed names is outlined in the listFeedPosts documentation.

Feeds are paginated, but have no total records as they are an inherently dynamic list of posts.

Actions like liking, bookmarking, and responding to polls can be taken on individual posts in the same way they can be taken on the experience applications.


{% admonition type="info"%} The Feeds API requires authentication as a user. {% /admonition %}

Resources ### Return a user's feed of posts - [GET /v2/feed/posts](https://developers.firstup.io/endpoints/openapi/feeds/listfeedposts.md): Provides a list of posts in the user’s feed. Accepts pagination and filtering parameters. Upon enabling expanded reactions types, the response will include the additional reaction types. Resources Knowledge Base article on Feeds Feeds overview page Pagination Filtering ### Return a user profile's bookmarked posts - [GET /v2/feed/profile/bookmarked](https://developers.firstup.io/endpoints/openapi/feeds/listfeedprofilebookmarked.md) ### Return a user profile's submitted content - [GET /v2/feed/profile/submitted](https://developers.firstup.io/endpoints/openapi/feeds/listfeedprofilesubmitted.md) ### Return channels followed by a user profile - [GET /v2/feed/profile/channels](https://developers.firstup.io/endpoints/openapi/feeds/listfeedprofilechannels.md) ### Return the details of a single post within a feed - [GET /v2/feed/posts/{content_id}](https://developers.firstup.io/endpoints/openapi/feeds/detailfeedpost.md): Provides the data for a single post in a user’s feed. The post must be visible to the user or a 404 Not Found response will be returned. Upon enabling expanded reactions types, the response will include the additional reaction types. ### Return the engagement details of a single post within a feed - [GET /v2/feed/posts/{content_id}/engagement](https://developers.firstup.io/endpoints/openapi/feeds/detailfeedpostengagement.md): Displays the user’s engagements related to a single feed post, including a timestamp for each type of engagement; for example, a liked_at timestamp is present if the user has liked the post and a bookmarked_at is present if the user has bookmarked the post. The post must be visible to the user or a 404 Not Found response will be returned. Upon enabling expanded reactions types, the response will include a reaction_type_id which is associated with a reaction type. ### Like a post in the feed - [PUT /v2/feed/posts/{content_id}/like](https://developers.firstup.io/endpoints/openapi/feeds/likepost.md): Creates a "like" engagement of a specific feed post for a scoped user. The post must be visible to the user or a 404 Not Found response will be returned; for example, this would happen if the content is published to a targeted topic that does not target the user. Upon enabling expanded reactions types, the user can like the post with a specific reaction type by providing a reaction_type_id in the request body. ### Unlike a post in the feed - [PUT /v2/feed/posts/{content_id}/unlike](https://developers.firstup.io/endpoints/openapi/feeds/unlikepost.md): Unlikes a feed post for a scoped user. Unliking effectively removes an existing “like” engagement. The post must be visible to the user or a 404 Not Found response will be returned; for example, this would happen if the content is published to a targeted topic that does not target the user. ### Bookmark a post in the feed - [PUT /v2/feed/posts/{content_id}/bookmark](https://developers.firstup.io/endpoints/openapi/feeds/bookmarkpost.md): Creates a “bookmark” engagement of a specific feed post for a scoped user. The post must be visible to the user or a 404 Not Found response will be returned; for example, this would happen if the content is published to a targeted topic that does not target the user. ### Unbookmark a post in the feed - [PUT /v2/feed/posts/{content_id}/unbookmark](https://developers.firstup.io/endpoints/openapi/feeds/unbookmarkpost.md): Unbookmarks a feed post for a scoped user. Unbookmarking effectively removes an existing “bookmark” engagement. The post must be visible to the user or a 404 Not Found response will be returned; for example, if the content is published to a targeted topic that does not target the user. ### Get the trackable URL for a post in the feed - [GET /v2/feed/posts/{content_id}/share/trackable_url](https://developers.firstup.io/endpoints/openapi/feeds/generatetrackableurl.md): Get the trackable URL for a feed post for a scoped user. The post must be visible to the user or a 400 bas request will be returned. ### Share a post in the feed - [PUT /v2/feed/posts/{content_id}/share](https://developers.firstup.io/endpoints/openapi/feeds/sharepost.md): Indicates that the post has been shared by a scoped user. The post must be visible to the user or a 400 bas request will be returned. `share_url can be retrieved using GET` the trackable URL for a post in the feed. ### View a post in the feed - [PUT /v2/feed/posts/{content_id}/view](https://developers.firstup.io/endpoints/openapi/feeds/viewpost.md): Marks a specific feed post as viewed for a scoped user. Viewing is considered as the user having interacted with the content enough to qualify as at least partial consumption. The post must be visible to the user or a 404 Not Found response will be returned. ### Unview a post in the feed - [PUT /v2/feed/posts/{content_id}/unview](https://developers.firstup.io/endpoints/openapi/feeds/unviewpost.md): Reverses a view operation on a feed post for a scoped user. Unviewing is used in cases where a view was mistakenly recorded. The post must be visible to the user or a 404 Not Found response will be returned. ### List the comments on a content post - [GET /v2/feed/posts/{content_id}/comments](https://developers.firstup.io/endpoints/openapi/feeds/listfeedpostcomments.md): List the comments on a content post. Only top-level comments are returned. Comments which are replies to other comments are not currently available through this endpoint. Upon enabling expanded reactions types, the response will include the additional reaction types. When a comment with user mentions is returned, it will be returned with those mentions in the format of either `{ref:user:} or {ref:user::id:}`. You can parse out the user_id and then look up the user and transform the mention metadata to the display_name/name of the referenced user. ### Comment on a post in the feed - [POST /v2/feed/posts/{content_id}/comments](https://developers.firstup.io/endpoints/openapi/feeds/createfeedpostcomment.md): Creates a new comment record for the content post. You may indicate a mention of a specific user by providing their `user_id in the format of either {ref:user:} or {ref:user::id:}`. ### List the replies to a comment on a content post - [GET /v2/feed/posts/{content_id}/comments/{comment_id}/replies](https://developers.firstup.io/endpoints/openapi/feeds/listfeedpostcommentreplies.md): List the replies to a comment on a content post. Upon enabling expanded reactions types, the response will include the additional reaction types. When a comment with user mentions is returned, it will be returned with those mentions in the format of either `{ref:user:} or {ref:user::id:}`. You can parse out the user_id and then look up the user and transform the mention metadata to the display_name/name of the referenced user. ### Reply to a comment on a post in the feed - [POST /v2/feed/posts/{content_id}/comments/{comment_id}/{post_number}/replies](https://developers.firstup.io/endpoints/openapi/feeds/createfeedpostcommentreply.md): Upon enabling expanded reactions types, the response will include the additional reaction types. When a comment with user mentions is returned, it will be returned with those mentions in the format of either `{ref:user:} or {ref:user::id:}`. You can parse out the user_id and then look up the user and transform the mention metadata to the display_name/name of the referenced user. ### Report a Comment or Reply for a given post in the feed - [PUT /v2/feed/posts/{content_id}/comments/{comment_id}/report](https://developers.firstup.io/endpoints/openapi/feeds/reportfeedpostcomment.md): Creates a Report for a specific comment (or reply) to a post for a scoped user. The comment must be visible to the user or a 404 Not Found response will be returned; for example, this would happen if the comment is published to a post in a targeted topic that does not target the user. ### Query for users that are able to be mentioned. - [GET /v2/feed/users/suggest](https://developers.firstup.io/endpoints/openapi/feeds/suggestuser.md): Query for users that are able to be mentioned. ### Update a comment on a post in the feed - [PUT /v2/feed/posts/{content_id}/comments/{comment_id}](https://developers.firstup.io/endpoints/openapi/feeds/updatefeedpostcomment.md): Update an existing comment record. The body attribute can be provided and only those provided will be updated. Response body data will be the updated record. Upon enabling expanded reactions types, the response will include the additional reaction types. You may indicate a mention of a specific user by providing their `user_id in the format of either {ref:user:} or {ref:user::id:}`. ### Delete a comment or reply on a post in the feed - [DELETE /v2/feed/posts/{content_id}/comments/{comment_id}](https://developers.firstup.io/endpoints/openapi/feeds/deletefeedpostcomment.md): Allows an authenticated user to delete a comment or reply they authored. The comment is soft deleted and will no longer appear in feed views. ### Return the rendered content of a single post within the feed - [GET /v2/feed/posts/{content_id}/rendered](https://developers.firstup.io/endpoints/openapi/feeds/renderfeedpost.md): Provides the rendered content for a single post in a user’s feed. The post must be visible to the user or a 404 Not Found response will be returned. ### Report a post in the feed - [PUT /v2/feed/posts/{content_id}/report](https://developers.firstup.io/endpoints/openapi/feeds/reportfeedpost.md): Creates a Report for a specific feed post for a scoped user. The post must be visible to the user or a 404 Not Found response will be returned; for example, this would happen if the content is published to a targeted topic that does not target the user. ### Acknowledge a post in the feed. - [POST /v2/feed/posts/{content_id}/acknowledge](https://developers.firstup.io/endpoints/openapi/feeds/acknowledgefeedpost.md): Acknowledges a feed post for a scoped user. The post must be visible to the user or a 404 Not Found response will be returned; for example, if the content is published to a targeted channel that does not target the user. ### Returns the details of a single poll. - [GET /v2/feed/polls/{poll_id}](https://developers.firstup.io/endpoints/openapi/feeds/showfeedpoll.md): Provides data for a single poll. ### Respond to a poll. - [POST /v2/feed/polls/{poll_id}](https://developers.firstup.io/endpoints/openapi/feeds/respondfeedpoll.md): Respond to a poll. ### Returns a user's feed of polls. - [GET /v2/feed/polls](https://developers.firstup.io/endpoints/openapi/feeds/listfeedpolls.md): Provides a list of polls in the user's feed. ### Experimental and undocumented video access - [GET /v2/feed/video/{video_id}](https://developers.firstup.io/endpoints/openapi/feeds/showfeedvideo.md): Experimental internal API ### Experimental and undocumented attachment access - [GET /v2/feed/attachments/{uuid}/status](https://developers.firstup.io/endpoints/openapi/feeds/getattachmentstatus.md): Experimental internal API ## User Management The User Management API adheres to the [SCIM 2.0](https://scim.cloud/) protocol unless otherwise stated, and provides management and provisioning of users in a program.

Managing users requires that the acting user have a role of Program Manager or Administrator, and users can only create or update users with a role less than or equal to their own. Resources ### List SCIM schemas - [GET /scim/v2/Schemas](https://developers.firstup.io/endpoints/openapi/user-management/listschemas.md): Returns a list of the schemas in use by this SCIM API. Implements SCIM 2.0 Specification. ### Detail a SCIM schema - [GET /scim/v2/Schemas/{schema_id}](https://developers.firstup.io/endpoints/openapi/user-management/detailschema.md): Returns the specified schema used by this SCIM API. Implements SCIM 2.0 specification. ### Provides SCIM Schema Provider Configuration - [GET /scim/v2/ServiceProviderConfig](https://developers.firstup.io/endpoints/openapi/user-management/detailserviceproviderconfig.md): Returns the Schema Provider configuration as per SCIM 2.0 Specification. Additional references: SCIM 2.0 Spc Section 8.5 SCIM 2.0 Spec Section 8.7.2 ### Provides SCIM Resource Types - [GET /scim/v2/ResourceTypes](https://developers.firstup.io/endpoints/openapi/user-management/listresourcetypes.md): Returns available Resource Types configuration as per SCIM 2.0 Specification. Additional references: SCIM 2.0 Protocol Spec Section 4 SCIM 2.0 Spec Section 8.5 ### Detail a SCIM Resource Type - [GET /scim/v2/ResourceTypes/{resource_id}](https://developers.firstup.io/endpoints/openapi/user-management/detailresourcetype.md): Returns the requested Resource Type SCIM 2.0 Specification. Additional references: SCIM 2.0 Protocol Spec Section 4 SCIM 2.0 Spec Section 8.5 ### List users in the program - [GET /scim/v2/Users](https://developers.firstup.io/endpoints/openapi/user-management/listusers.md): This endpoint allows you to retrieve information about all or some of the users stored in the Firstup application and adheres to the SCIM 2.0 Section: 4.1 standard. 📚 For more in-depth guidance on using the user interface and understanding the application's behavior, you can refer to the user documentation provided here. This documentation will help bridge the gap between the API and the intricacies of Firstup. ### Create a user in the program - [POST /scim/v2/Users](https://developers.firstup.io/endpoints/openapi/user-management/createuser.md): Create and provision a new user. The request should include any properties to be set on the user, and leaving any out will leave those values blank, or will use defaults. New users have a role of "member" by default. New users have an onboarding status of "created" by default. Setting a user's role requires that the acting user have a role the same or less than the role of the user being created. The role property is also formatted as an array to comply with SCIM protocol though it only accepts a single value. Providing more than one value will result in a 400 response. {% admonition type="info" %} Additional documentation and resources User roles and access User provisioning * SCIM user provisioning {% /admonition%} ### Show a single program user by ID - [GET /scim/v2/Users/{user_id}](https://developers.firstup.io/endpoints/openapi/user-management/detailuser.md): Returns a User record for specified user in the program. ### Replace a user in the program - [PUT /scim/v2/Users/{user_id}](https://developers.firstup.io/endpoints/openapi/user-management/replaceuser.md): To update or replace user information, ensure that your request includes a comprehensive set of user attributes. {% admonition type="warning" %}Utilize PUT endpoints carefully. Modified data models caused by new features or user-defined fields may lead to data loss. Refer to our SCIM patching documentation before executing.{% /admonition %} Quick Guidance For a seamless process, consider the following: 1. GET the user record to retrieve all current attributes and objects associated with the user. 2. Modify the values you wish to change within the retrieved user record. 3. Execute the PUT call with the modified user record to ensure no inadvertent data removal from the application. Alternatively, you can opt for a PATCH call to selectively modify specific attributes without affecting others. Keep in mind that when updating a user's role using oath2_as_a_user, the acting user must have a role that's the same as or higher than both the starting and ending roles of the user being updated. {% admonition type="info" %} We advise refering to our SCIM patching documentation before executing. Refer to our error responses documentation for detail on errors.{% /admonition %} ### Update a user in the program - [PATCH /scim/v2/Users/{user_id}](https://developers.firstup.io/endpoints/openapi/user-management/patchuser.md): Update a user in the program with partial changes using SCIM PatchOp. Add, remove, or replace selected fields of the user. Role updates require the acting user's role to be the same or higher role than the user being updated both before and after the role update. {% admonition type="info" %} We advise refering to our SCIM patching documentation before executing. Refer to our error responses documentation for detail on errors.{% /admonition %} ### Completely remove a user from the system - [DELETE /scim/v2/Users/{user_id}](https://developers.firstup.io/endpoints/openapi/user-management/deleteuser.md): Permanently remove a User and their details from all Programs. A non-existent user, or a user that's already been forgotten, will return a 204. ### Show information about the current user - [GET /scim/v2/Users/me](https://developers.firstup.io/endpoints/openapi/user-management/me.md): Returns a User record for specified user in the program. {% admonition type="info"%} This endpoint requires authentication as a user.{% /admonition %} ### Completely remove a user from the system (Not SCIM compliant) - [POST /v2/Users/{user_id}/forget](https://developers.firstup.io/endpoints/openapi/user-management/forgetuser.md): Permanently remove a User and their details from all Programs. A non-existent user, or a user that's already been forgotten, will return a 202. ## User Groups The Group Management API adheres to the [SCIM 2.0](https://scim.cloud/) protocol ***unless otherwise stated***, and provides management and provisioning of Groups and its members (Users) within a Program. Managing Groups requires that the acting User have a role of Program Manager or Administrator, and Group read and/or write access. {% admonition type="info" %}User groups are SCIM groups only. Currently, this API does not support creating audiences .{% /admonition %} ### Returns a list of Groups - [GET /scim/v2/Groups](https://developers.firstup.io/endpoints/openapi/user-groups/listgroups.md): Returns a list of all accessible Groups in the acting User's Program. ### Creates a Group - [POST /scim/v2/Groups](https://developers.firstup.io/endpoints/openapi/user-groups/creategroup.md): Creates and provisions a new Group of Users. The request should include any properties to be set on the Group. Any property not provided would leave the value blank or use defaults. The list of members could be empty or not present. Members are referenced with the identifierField, by either: - email - id - userName (the default if no identifierField is included) This operation is asynchronous, the response will not include the list of members. A JobId will be in the response's meta, to be able to get a JobReport (see the ad hoc endpoint below). Indexing a Group's Users can take some time. ### Returns the details of the given Group, including its members - [GET /scim/v2/Groups/{group_id}](https://developers.firstup.io/endpoints/openapi/user-groups/detailgroup.md): Returns the group specified by the group_id. Groups are defined by the SCIM specification. ### Updates a Group - [PATCH /scim/v2/Groups/{group_id}](https://developers.firstup.io/endpoints/openapi/user-groups/patchgroup.md): Update an audience in the Program with partial changes using SCIM PatchOp. Add or remove selected fields of the audience. The list of members in the Group is referenced using the identifierField, by either: - email - id - userName (the default if no identifierField is included) All operations are supported: add, remove, and replace. {% admonition type="info" %}A replace replaces all the members of the Group by the value sent (a full replace).{% /admonition %} This operation is asynchronous, the response will not include the list of members. A JobId will be in the response's meta, to be able to get a JobReport (see GET /v2/Groups/JobReport/{jobId}. {% admonition type="info" %} We advise refering to our SCIM patching documentation before executing. Refer to our error responses documentation for detail on errors.{% /admonition %} ### Deletes a Group - [DELETE /scim/v2/Groups/{group_id}](https://developers.firstup.io/endpoints/openapi/user-groups/deletegroup.md): Delete an audience in the Program ### Updates a Group - [PUT /scim/v2/Groups/{group_id}](https://developers.firstup.io/endpoints/openapi/user-groups/updategroup.md): Updates and provisions an existing Group of Users. The request should include any properties to be set on the Group. Any property not provided would leave the value blank or use defaults. The list of members could be empty or not present. Members are referenced with the identifierField, by either: - email - id - userName (the default if no identifierField is included) This operation is asynchronous, the response will not include the list of members. A JobId will be in the response's meta, to be able to get a JobReport ( GET /v2/Groups/JobReport/{jobId}). Indexing a Group's Users can take some time. ### Returns details on asynchronous jobs to modify a Group's members - [GET /v2/Groups/JobReport/{jobId}](https://developers.firstup.io/endpoints/openapi/user-groups/groupasyncjobreport.md): The calls to the POST, PUT or PATCH Groups Managements endpoints trigger a series of asynchronous jobs to create or update the list of the Group's members. As these tasks are asynchronous, those API calls do not respond with the final list of the Group's members, but an unique Job identifier to inquire about the task. This endpoint takes the jobId identifier, and returns details about the asynchronous job's execution. The job could have already finished or still be running, and the response could include details on the number of members added, removed, processed, and error conditions (if any). ## Webhooks

The Webhooks API provides a mechanism for subscribing to events that occur within the Firstup platform to receive http payloads when those events occur. Use webhook subscriptions to trigger actions on your own application.

Webhook events are sent by the Firstup platform as POST requests to your webhook url. Each event contains a payload specific to that event. More information about the webhooks system, including a list of events that can be subscribed to, is available on the Webhooks page

### Fetch the program's configured webhook subscriptions - [GET /v2/webhooks/subscriptions](https://developers.firstup.io/endpoints/openapi/webhooks/listwebhooksubscriptions.md): Fetchs multiple subscription records at a time, and can be paginated using cursor pagination. ### Create a new webhook subscription - [POST /v2/webhooks/subscriptions](https://developers.firstup.io/endpoints/openapi/webhooks/createwebhooksubscription.md): Subscriptions are configurations that define what events you want to receive webhooks for. A url and at least one event are required for a subscription. If your server requires authorization, the authorization_header property allows you to specify what value to send in the "Authorization" http header of every delivery to your url. More information about creating webhook subscriptions is available on the Creating Webhook Subscriptions page, and the list of available events is available on the Event List page. The access token used when creating a subscription must have the webhooks.write auth scope. ### Update an existing webhook subscription - [PUT /v2/webhooks/subscriptions/{subscription_id}](https://developers.firstup.io/endpoints/openapi/webhooks/updatewebhooksubscription.md): After creation, subscriptions can be updated to change what events are subscribed to, what url to send the payloads to, and other settings such as whether the subscription is active. Any values that can be set on the subscription when creating it can be updated. The update method is a patch operation, so only properties you send in the request will be updated on the record. The events property, however, does not support partial updates as an array. The access token used when updating a subscription must have the webhooks.write auth scope. ### Delete a webhook subscription permanently - [DELETE /v2/webhooks/subscriptions/{subscription_id}](https://developers.firstup.io/endpoints/openapi/webhooks/deletewebhooksubscription.md): Deactivate a webhook subscription and remove the record permanently. {% admonition type="warning" %}Warning: you cannot undo this action.{% /admonition %} ### Fetch a single webhook subscription record - [GET /v2/webhooks/subscriptions/{subscription_id}](https://developers.firstup.io/endpoints/openapi/webhooks/detailwebhooksubscription.md) ### Test a webhook subscription by pinging it with a sample payload - [POST /v2/webhooks/subscriptions/{subscription_id}/ping](https://developers.firstup.io/endpoints/openapi/webhooks/pingwebhooksubscription.md): More information about testing webhook subscriptions is available on the Testing Webhook Subscriptions page. ## Assistant Inbox {% admonition type="info" %}This API is deprecated and has been replaced by the Notification Center API.{% /admonition %} ### Fetch the program user's inbox (deprecated) - [GET /v2/assistant/inbox_items](https://developers.firstup.io/endpoints/openapi/assistant-inbox/listinboxitems.md): Fetches multiple inbox item records at a time. ### Fetch the program user's Todos. (deprecated) - [GET /v2/assistant/todos](https://developers.firstup.io/endpoints/openapi/assistant-inbox/listassistanttodos.md): Fetches multiple Todo records at a time. ### Fetch the program user's notifications. (deprecated) - [GET /v2/assistant/notifications](https://developers.firstup.io/endpoints/openapi/assistant-inbox/listnotifications.md): Fetches multiple inbox notification records at a time. ### Acknowledge the program user's notification. (deprecated) - [PUT /v2/assistant/notifications/{notification_id}/acknowledge](https://developers.firstup.io/endpoints/openapi/assistant-inbox/acknowledgenotification.md): Mark the program user's notification acknowledged. ### Acknowledge all program user's notifications. (deprecated) - [PUT /v2/assistant/notifications/acknowledge_all](https://developers.firstup.io/endpoints/openapi/assistant-inbox/acknowledgeallnotifications.md): Mark all program user's notifications acknowledged. ### Fetch the program user's notifications count. (deprecated) - [GET /v2/assistant/inbox_items/total_count](https://developers.firstup.io/endpoints/openapi/assistant-inbox/getinboxitemstotalcount.md): Fetches the count of notifications for the user. ## Notification Center

The Notification Center API provides programmatic access to the notifications surfaced in the Firstup application. It enables developers to query and track notifications, including their status, delivery channel, and engagement events, ensuring alignment with what employees see in their Notification Center hub. Notifications reflect activity such as campaigns, journeys, and post interactions, and respect user preferences and notification settings.

{% admonition type="info"%} * The Notification Center API requires authentication as a user. * The Notification Center replaces the Assistant Inbox {% /admonition %} ### Fetch the program user's notifications. - [GET /v2/notification_center/notifications](https://developers.firstup.io/endpoints/openapi/notification-center/listnotifications.md): Fetches multiple inbox notification records at a time. ### Acknowledge the program user's notification. - [PUT /v2/notification_center/notifications/{notification_id}/read](https://developers.firstup.io/endpoints/openapi/notification-center/readnotification.md): Mark the program user's notification read. ### Fetch the program user's notifications count. - [GET /v2/notification_center/total_count](https://developers.firstup.io/endpoints/openapi/notification-center/getnotificationstotalcount.md): Fetches the count of notifications for the user. ## User Roles

The User Roles API enables you to retrieve the set of roles that are available to the authenticated acting user within their program. Roles represent permission levels and access scopes for users across the Firstup platform. For example granting access to Creator Studio, content publishing tools, or member experience features.


Resources ### Return a list of roles - [GET /scim/v2/Roles](https://developers.firstup.io/endpoints/openapi/user-roles/listroles.md): Returns a list of all accessible roles in the actor's program. Only primary roles are currently available. ## User Shortcuts

The User Shortcuts API provides programmatic access to a personalized set of shortcuts that surface key resources directly on a user’s homepage, similarly to how they appear in Firstup's employee experience. Shortcuts give users quick entry points to frequently used tools, links, and integrations.

{% admonition type="info"%} The User Shortcuts API requires authentication as a user. {% /admonition %} ### Fetch the program user's shortcuts. - [GET /v2/shortcuts](https://developers.firstup.io/endpoints/openapi/user-shortcuts/listshortcuts.md): Fetch the program user's shortcuts. ## Feed Channel Posts ### Return a user's feed of posts for channels - [GET /v2/feed/channels/posts](https://developers.firstup.io/endpoints/openapi/feed-channel-posts/listfeedchannelposts.md): Provides a list of posts in the user’s channels feeds. Accepts pagination and filtering parameters. Upon enabling expanded reactions types, the response will include the additional reaction types. Resources Knowledge Base article on Feed Channels Feed Channels overview page Pagination Filtering ## Data Exports ### Get the latest export file for a given type. - [GET /v2/data_exports/type/{type_name}/latest](https://developers.firstup.io/endpoints/openapi/data-exports/latestexport.md): Returns metadata and a presigned download URL for the most recent export file of the specified type within the caller's program. Valid type names: users, campaigns, activities. ### List all available export files for a given type. - [GET /v2/data_exports/type/{type_name}](https://developers.firstup.io/endpoints/openapi/data-exports/listexports.md): Returns a list of all export files for the specified type within the caller's program. Each file entry includes an opaque file ID that can be used with the show endpoint to obtain a presigned download URL. Valid type names: users, campaigns, activities. ### Get metadata and download URL for a specific export file. - [GET /v2/data_exports/type/{type_name}/files/{file_id}](https://developers.firstup.io/endpoints/openapi/data-exports/showexport.md): Returns metadata and a presigned download URL for a specific export file identified by its file ID. The file ID is obtained from the list exports endpoint.