Skip to content

Firstup API (v2)

Beta Notice: This portal is currently in beta. Some functionality, like Try it is temporarily disabled.


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. This can be imported into tools such as Postman to generate a collection of test queries or converted into an SDK using Swagger Codegen. Alternatively, you can use the try me function in this platform.

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>"
Main API Sections

Firstup Developer Portal
Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL

https://support.firstup.io/hc/en-us

Terms of Service

Languages
Servers

https://developers.firstup.io/

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.

  • Security: Users with a “publisher” or higher role can work with content in this admin-like function. A 403 code is returned for content-related requests to users without a “publisher” or higher role. Permissions are not granular; any authenticated user may read, update, or take action on any existing content. See user roles and access for more guidance.

  • States: Content is initially created in the “draft” state. It becomes fully visible in feeds when it has passed the “review” state (meaning that it requires review) and is in the “published” state. Content can also pass through “archived” (similar to deleted), “scheduled” (content to be published in the future automatically), “processing” (refers to media that is still being processed or uploaded; like content in the “draft” state, this content does not become “published” until processing has completed), and “processing error” (media or similar objects that fail during the processing phase; this content cannot be transitioned to another state) states.

  • Sources: Content sources include “submitted” (by users); “Pinterest,”“RSS,”“Facebook,”“Twitter,” and “Instagram” (for content harvested from external sources); “SocialChorus CPCM” (for content that is republished between programs); “studio” (for admin-created content); and “OAuth Client” (for content published via the Partner API or other OAuth client).

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

Operations

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.

For contexctual guidance on feeds, and for use examples, refer to our feeds overview page.

Operations

User Management

The User Management API adheres to the SCIM 2.0 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.

For further guidance on User Management, refer to:

Operations

User Groups

The Group Management API adheres to the SCIM 2.0 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.

Note: User groups are SCIM groups only. Currently this API does not support creating audiences.

Operations

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.

Operations

Fetch the program's configured webhook subscriptions

Request

Fetchs multiple subscription records at a time, and can be paginated using cursor pagination.

Security
oauth2_as_a_user or oauth2_as_a_server
Query
page.sizeinteger(int64)

Return page.size number of records starting at size*number. Default is 1, resulting in the first page being retrieved

page.numberinteger(int64)

Using classical pagination, the page number to return. Default is 1

curl -i -X GET \
  'https://developers.firstup.io/v2/webhooks/subscriptions?page.size=0&page.number=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json
dataArray of objects(Webhooks.Subscription.Resource)required
data[].​idstring(Webhooks.Subscription.id)

Unique identifier for this subscription.

Example: "abc123"
data[].​urlstring(url)(Webhooks.Subscription.url)

The url that will be called when delivering events for this subscription.

Example: "https://example.com/webhook"
data[].​authorization_headerstring(Webhooks.Subscription.authorization_header)

A value will be sent in every delivery as the 'Authorization' header value in the POST request.

Example: "Bearer abc123-some-token"
data[].​activeboolean(Webhooks.Subscription.active)

Whether the subscription is "turned on". Inactive subscriptions will not send deliveries to the subscription url except for ping deliveries.

Example: true
data[].​eventsArray of objects(Webhooks.Subscription.Event)
data[].​created_atstring(date-time)
Example: "2000-01-01T00:00:00Z"
data[].​updated_atstring(date-time)
Example: "2000-01-01T00:00:00Z"
metaobject
Response
application/json
{
  "data": [
    { … }
  ],
  "meta": {
    "pagination": { … }
  }
}

Create a new webhook subscription

Request

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.writeauth scope.

Security
oauth2_as_a_user or oauth2_as_a_server
Bodyapplication/json

Attributes of the webhook subscription to create.

urlstring(url)(Webhooks.Subscription.url)

The url that will be called when delivering events for this subscription.

Example: "https://example.com/webhook"
authorization_headerstring(Webhooks.Subscription.authorization_header)

A value will be sent in every delivery as the 'Authorization' header value in the POST request.

Example: "Bearer abc123-some-token"
activeboolean(Webhooks.Subscription.active)

Whether the subscription is "turned on". Inactive subscriptions will not send deliveries to the subscription url except for ping deliveries.

Example: true
eventsArray of objects(Webhooks.Subscription.Event)
curl -i -X POST \
  https://developers.firstup.io/v2/webhooks/subscriptions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/webhook",
    "authorization_header": "Bearer abc123-some-token",
    "active": true,
    "events": [
      {
        "name": "content_published",
        "version": "1"
      }
    ]
  }'

Responses

Success

Bodyapplication/json
dataobject(Webhooks.Subscription.Resource)required
data.​idstring(Webhooks.Subscription.id)

Unique identifier for this subscription.

Example: "abc123"
data.​urlstring(url)(Webhooks.Subscription.url)

The url that will be called when delivering events for this subscription.

Example: "https://example.com/webhook"
data.​authorization_headerstring(Webhooks.Subscription.authorization_header)

A value will be sent in every delivery as the 'Authorization' header value in the POST request.

Example: "Bearer abc123-some-token"
data.​activeboolean(Webhooks.Subscription.active)

Whether the subscription is "turned on". Inactive subscriptions will not send deliveries to the subscription url except for ping deliveries.

Example: true
data.​eventsArray of objects(Webhooks.Subscription.Event)
data.​created_atstring(date-time)
Example: "2000-01-01T00:00:00Z"
data.​updated_atstring(date-time)
Example: "2000-01-01T00:00:00Z"
Response
application/json
{
  "data": {
    "id": "abc123",
    "url": "https://example.com/webhook",
    "authorization_header": "Bearer abc123-some-token",
    "active": true,
    "events": [ … ],
    "created_at": "2000-01-01T00:00:00Z",
    "updated_at": "2000-01-01T00:00:00Z"
  }
}

Update an existing webhook subscription

Request

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.writeauth scope.

Security
oauth2_as_a_user or oauth2_as_a_server
Path
subscription_idstringrequired

Id of the subscription to update

Bodyapplication/json

Attributes of the webhook subscription to update.

urlstring(url)(Webhooks.Subscription.url)

The url that will be called when delivering events for this subscription.

Example: "https://example.com/webhook"
authorization_headerstring(Webhooks.Subscription.authorization_header)

A value will be sent in every delivery as the 'Authorization' header value in the POST request.

Example: "Bearer abc123-some-token"
activeboolean(Webhooks.Subscription.active)

Whether the subscription is "turned on". Inactive subscriptions will not send deliveries to the subscription url except for ping deliveries.

Example: true
eventsArray of objects(Webhooks.Subscription.Event)
curl -i -X PUT \
  'https://developers.firstup.io/v2/webhooks/subscriptions/{subscription_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/webhook",
    "authorization_header": "Bearer abc123-some-token",
    "active": true,
    "events": [
      {
        "name": "content_published",
        "version": "1"
      }
    ]
  }'

Responses

Success

Bodyapplication/json
dataobject(Webhooks.Subscription.Resource)required
data.​idstring(Webhooks.Subscription.id)

Unique identifier for this subscription.

Example: "abc123"
data.​urlstring(url)(Webhooks.Subscription.url)

The url that will be called when delivering events for this subscription.

Example: "https://example.com/webhook"
data.​authorization_headerstring(Webhooks.Subscription.authorization_header)

A value will be sent in every delivery as the 'Authorization' header value in the POST request.

Example: "Bearer abc123-some-token"
data.​activeboolean(Webhooks.Subscription.active)

Whether the subscription is "turned on". Inactive subscriptions will not send deliveries to the subscription url except for ping deliveries.

Example: true
data.​eventsArray of objects(Webhooks.Subscription.Event)
data.​created_atstring(date-time)
Example: "2000-01-01T00:00:00Z"
data.​updated_atstring(date-time)
Example: "2000-01-01T00:00:00Z"
Response
application/json
{
  "data": {
    "id": "abc123",
    "url": "https://example.com/webhook",
    "authorization_header": "Bearer abc123-some-token",
    "active": true,
    "events": [ … ],
    "created_at": "2000-01-01T00:00:00Z",
    "updated_at": "2000-01-01T00:00:00Z"
  }
}

Delete a webhook subscription permanently

Request

Deactivate a webhook subscription and remove the record permanently. Warning: you cannot undo this action.

Security
oauth2_as_a_server or oauth2_as_a_user
Path
subscription_idintegerrequired

Id of the subscription to delete

curl -i -X DELETE \
  'https://developers.firstup.io/v2/webhooks/subscriptions/{subscription_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Response
No content

Fetch a single webhook subscription record

Request

Security
oauth2_as_a_user or oauth2_as_a_server
Path
subscription_idintegerrequired

Id of the subscription to detail

curl -i -X GET \
  'https://developers.firstup.io/v2/webhooks/subscriptions/{subscription_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json
dataobject(Webhooks.Subscription.Resource)required
data.​idstring(Webhooks.Subscription.id)

Unique identifier for this subscription.

Example: "abc123"
data.​urlstring(url)(Webhooks.Subscription.url)

The url that will be called when delivering events for this subscription.

Example: "https://example.com/webhook"
data.​authorization_headerstring(Webhooks.Subscription.authorization_header)

A value will be sent in every delivery as the 'Authorization' header value in the POST request.

Example: "Bearer abc123-some-token"
data.​activeboolean(Webhooks.Subscription.active)

Whether the subscription is "turned on". Inactive subscriptions will not send deliveries to the subscription url except for ping deliveries.

Example: true
data.​eventsArray of objects(Webhooks.Subscription.Event)
data.​created_atstring(date-time)
Example: "2000-01-01T00:00:00Z"
data.​updated_atstring(date-time)
Example: "2000-01-01T00:00:00Z"
Response
application/json
{
  "data": {
    "id": "abc123",
    "url": "https://example.com/webhook",
    "authorization_header": "Bearer abc123-some-token",
    "active": true,
    "events": [ … ],
    "created_at": "2000-01-01T00:00:00Z",
    "updated_at": "2000-01-01T00:00:00Z"
  }
}

Test a webhook subscription by pinging it with a sample payload

Request

More information about testing webhook subscriptions is available on the Testing Webhook Subscriptions page.

Security
oauth2_as_a_server or oauth2_as_a_user
Path
subscription_idintegerrequired

Id of the subscription to ping

curl -i -X POST \
  'https://developers.firstup.io/v2/webhooks/subscriptions/{subscription_id}/ping' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json
dataobject(Webhooks.Subscription.Ping)
Response
application/json
{
  "data": {
    "delivery": { … },
    "subscription": { … }
  }
}

Assistant Inbox

Note: This API is getting deprecated and is replaced by the Notification Center.

Operations

User Roles

Operations

Notification Center

Operations