Skip to content
User Management
/
Show a single program user by ID

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

List SCIM schemas

Request

Returns a list of the schemas in use by this SCIM API. Implements SCIM 2.0 Specification.

Security
oauth2_as_a_server or oauth2_as_a_user
curl -i -X GET \
  https://developers.firstup.io/scim/v2/Schemas \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/scim+json
schemasArray of strings
Example: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"]
totalResultsinteger
Example: 5
itemsPerPageinteger
Example: 10
startIndexinteger
Example: 1
ResourcesArray of objects
Example: [{"id":"urn:ietf:params:scim:schemas:core:2.0:User","name":"SCIMCoreUser","description":"SCIM Core User","attributes":["Array"]},{"id":"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User","name":"EnterpriseUser","description":"Enterprise User","attributes":["Array"]},{"id":"urn:SocialChorus:1.0:User","name":"SocialChorusUserExtension","description":"Social Chorus User Extension","attributes":["Array"]}]
Response
application/scim+json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 5,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    { … },
    { … },
    { … }
  ]
}

Detail a SCIM schema

Request

Returns the specified schema used by this SCIM API. Implements SCIM 2.0 specification.

Security
oauth2_as_a_server or oauth2_as_a_user
Path
schema_idstringrequired

The Schema ID.

curl -i -X GET \
  'https://developers.firstup.io/scim/v2/Schemas/{schema_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/scim+json
object
Response
application/scim+json
"{\n  \"id\": \"urn:SocialChorus:1.0:User\",\n  \"name\": \"SocialChorusUserExtension\",\n  \"description\": \"Social Chorus User Extension\",\n  \"attributes\": [\n    {\n      \"caseExact\": false,\n      \"description\": \"The user's business unit.\",\n      \"multiValued\": false,\n      \"mutability\": \"readWrite\",\n      \"name\": \"businessUnit\",\n      \"required\": false,\n      \"returned\": \"default\",\n      \"type\": \"string\",\n      \"uniqueness\": \"none\"\n    },\n    {\n      \"caseExact\": false,\n      \"description\": \"The user's gender.\",\n      \"multiValued\": false,\n      \"mutability\": \"readWrite\",\n      \"name\": \"gender\",\n      \"required\": false,\n      \"returned\": \"default\",\n      \"type\": \"string\",\n      \"uniqueness\": \"none\"\n    },\n    {\n      \"caseExact\": false,\n      \"description\": \"The user's manager's name.\",\n      \"multiValued\": false,\n      \"mutability\": \"readWrite\",\n      \"name\": \"managerName\",\n      \"required\": false,\n      \"returned\": \"default\",\n      \"type\": \"string\",\n      \"uniqueness\": \"none\"\n    },\n    {\n      \"caseExact\": false,\n      \"description\": \"The user's work location.\",\n      \"multiValued\": false,\n      \"mutability\": \"readWrite\",\n      \"name\": \"workLocation\",\n      \"required\": false,\n      \"returned\": \"default\",\n      \"type\": \"string\",\n      \"uniqueness\": \"none\"\n    },\n    {\n      \"caseExact\": false,\n      \"description\": \"The user's birth date.\",\n      \"multiValued\": false,\n      \"mutability\": \"readWrite\",\n      \"name\": \"birthDate\",\n      \"required\": false,\n      \"returned\": \"default\",\n      \"type\": \"string\",\n      \"uniqueness\": \"none\"\n    },\n    {\n      \"caseExact\": false,\n      \"description\": \"The user's start of employment date.\",\n      \"multiValued\": false,\n      \"mutability\": \"readWrite\",\n      \"name\": \"hireDate\",\n      \"required\": false,\n      \"returned\": \"default\",\n      \"type\": \"string\",\n      \"uniqueness\": \"none\"\n    },\n    {\n      \"caseExact\": false,\n      \"description\": \"The user's promotion date.\",\n      \"multiValued\": false,\n      \"mutability\": \"readWrite\",\n      \"name\": \"promotionDate\",\n      \"required\": false,\n      \"returned\": \"default\",\n      \"type\": \"string\",\n      \"uniqueness\": \"none\"\n    },\n    {\n      \"caseExact\": false,\n      \"description\": \"The requisition approval date.\",\n      \"multiValued\": false,\n      \"mutability\": \"readWrite\",\n      \"name\": \"requisitionApprovalDate\",\n      \"required\": false,\n      \"returned\": \"default\",\n      \"type\": \"string\",\n      \"uniqueness\": \"none\"\n    },\n    {\n      \"caseExact\": false,\n      \"description\": \"An array of objects including a name and value. These are stored as an arbitrary additional list of attributes associated to the user and can be used to create Groups and audiences in the Firstup platform. Currently, Custom Attributes can only be string values.\",\n      \"multiValued\": true,\n      \"mutability\": \"readWrite\",\n      \"name\": \"customAttributes\",\n      \"required\": false,\n      \"returned\": \"default\",\n      \"type\": \"complex\",\n      \"uniqueness\": \"none\",\n      \"subAttributes\": [Array]\n    }\n  ]\n}\n"

Provides SCIM Schema Provider Configuration

Request

Returns the Schema Provider configuration as per SCIM 2.0 Specification. Additional references:

Security
oauth2_as_a_server or oauth2_as_a_user
curl -i -X GET \
  https://developers.firstup.io/scim/v2/ServiceProviderConfig \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/scim+json
object
Response
application/scim+json
"{\n  \"schemas\": [ \"urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig\" ],\n  \"documentationUri\": \"https://partner.socialchorus.com/endpoints\",\n  \"patch\": { supported: true },\n  \"bulk\": { supported: false },\n  \"filter\": { supported: true },\n  \"changePassword\": { supported: false },\n  \"sort\": { supported: true },\n  \"etag\": { supported: false },\n  \"authenticationSchemas\": [\n    {\n      \"name\": \"OAuth Bearer Token\",\n      \"description\": \"Authentication scheme using the OAuth Bearer Token Standard\",\n      \"specUri\": \"https://www.rfc-editor.org/info/rfc6750\",\n      \"documentationUri\": \"https://partner.socialchorus.com/authorization\",\n      \"type\": \"oauthbearertoken\",\n      \"primary\": true\n    }\n  ],\n  \"meta\": {\n    \"location\": \"undefined/scim/v2/ServiceProviderConfig\",\n    \"resourceType\": \"ServiceProviderConfig\",\n    \"created\": \"2020-10-19T00:00:00Z\",\n    \"lastModified\": \"2020-10-19T00:00:00Z\",\n    \"version\": \"v1.22.1\"\n  }\n}\n"

Provides SCIM Resource Types

Request

Returns available Resource Types configuration as per SCIM 2.0 Specification. Additional references:

Security
oauth2_as_a_server or oauth2_as_a_user
curl -i -X GET \
  https://developers.firstup.io/scim/v2/ResourceTypes \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/scim+json
object
Response
application/scim+json
"{\n  \"totalResults\": 1,\n  \"itemsPerPage\": 1,\n  \"startIndex\": 1,\n  \"schemas\": [ \"urn:ietf:params:scim:api:messages:2.0:ListResponse\" ],\n  \"Resources\": [\n    {\n      \"schemas\": [Array],\n      \"id\": \"User\",\n      \"name\": \"User\",\n      \"endpoint\": \"/scim/v2/Users\",\n      \"description\": \"User Account\",\n      \"schema\": \"urn:ietf:params:scim:schemas:core:2.0:User\",\n      \"schemaExtensions\": [Array],\n      \"meta\": [Object]\n    }\n  ]\n}\n"

Detail a SCIM Resource Type

Request

Returns the requested Resource Type SCIM 2.0 Specification. Additional references:

Security
oauth2_as_a_server or oauth2_as_a_user
Path
resource_idstringrequired

The Resource ID.

curl -i -X GET \
  'https://developers.firstup.io/scim/v2/ResourceTypes/{resource_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/scim+json
object
Response
application/scim+json
"{\n  \"schemas\": [ \"urn:ietf:params:scim:schemas:core:2.0:ResourceType\" ],\n  \"id\": \"User\",\n  \"name\": \"User\",\n  \"endpoint\": \"/scim/v2/Users\",\n  \"description\": \"User Account\",\n  \"schema\": \"urn:ietf:params:scim:schemas:core:2.0:User\",\n  \"schemaExtensions\": [\n    {\n      \"schema\": \"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User\",\n      \"required\": true\n    },\n    {\n      \"schema\": \"urn:SocialChorus:1.0:User\",\n      \"required\": true\n    }\n  ],\n  \"meta\": {\n    \"location\": \"undefined/v2/ResourceTypes/User\",\n    \"resourceType\": \"ResourceType\"\n  }\n}\n"

List users in the program

Request

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.

Security
oauth2_as_a_server or oauth2_as_a_user
Query
filterstring

Supports a SCIM filter expression allowing for filtering the results based on specific criteria, such as userName or role.

Supported operator: eq

Supported Fields:

  • userName: internally maps to federated_identifier.
  • role: either new or legacy roles depending on program configuration.

Examples:

  • userName eq "user123" (URL encoded: ?filter=userName%20eq%20%22user123%22)
  • role eq "publisher" (URL encoded: ?filter=role%20eq%20%22publisher%22)
startIndexinteger

SCIM pagination parameter 1-based offset of the first query result

countinteger

SCIM pagination parameter Total number of results returned

curl -i -X GET \
  'https://developers.firstup.io/scim/v2/Users?filter=string&startIndex=0&count=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/scim+json
schemasArray of strings
Example: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"]
totalResultsinteger
Example: 5
itemsPerPageinteger
Example: 10
startIndexinteger
Example: 1
ResourcesArray of objects(Scim.User.Resource)
Response
application/scim+json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 5,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    { … }
  ]
}

Create a user in the program

Request

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.

Security
oauth2_as_a_server or oauth2_as_a_user
Bodyapplication/json
schemasArray of strings
Items Enum"urn:ietf:params:scim:schemas:core:2.0:User""urn:ietf:params:scim:schemas:extension:enterprise:2.0:User""urn:SocialChorus:1.0:User"
Example: ["urn:ietf:params:scim:schemas:core:2.0:User"]
userNamestring(Scim.User.Core.userName)required

userName uniquely identifies a user in the scope of your organization. It can be updated by the client, but must remain unique.

In Firstup Studio it is referred to as federated_identifier.

Example: "janeDoe123"
nameobject(Scim.User.Core.name)

An object containing multiple parts that make up a user's name.

displayNamestring or null(Scim.User.Core.displayName)
Please refrain from using this attribute without prior consultation with our support staff.

This attribute serves a distinct purpose within the Firstup system, requires a specific format and inappropriate use may introduce unintended side effects.

externalId(string or null) or (integer or null)(Scim.User.Core.externalId)

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

Example: "ext_123489"
One of:

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

string or null

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

nickNamestring or null(Scim.User.Core.nickName)

The casual way to address the user in real life.

Example: "Jane"
activeboolean or string(Scim.User.Core.active)

Whether or not the user is currently marked "active" in the program.

Example: true
One of:

Whether or not the user is currently marked "active" in the program.

boolean

Whether or not the user is currently marked "active" in the program.

rolesScim.User.Core.roleString (string) or (Array of Scim.User.Core.rolesObjectArray (Scim.User.Core.roleString (string) or Scim.User.Core.roleObject (object)))(Scim.User.Core.roles)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

One of:

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

string(Scim.User.Core.roleString)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

Default "member"
Enum"administrator""program_manager""analyst""publisher""channel_contributor""member"
phoneNumbersArray of objects(Scim.User.Core.phoneNumbers.create)

A list of the user's phone numbers.

If a user has no phone numbers this will be an empty list.

Note: The SCIM spec allows an arbitrary number of phone numbers with arbitrary types, but Firstup will only save numbers of types "main" and "mobile", and only a single number for each type.

It is not an error to include other types or additional numbers, but they will be ignored without an error message.

emailsArray of objects(Scim.User.Core.emails)

A list of the user's emails. If a user has no emails this will be an empty list.

addressesArray of objects(Scim.User.Core.addresses)

The user's addresses in the program. A Firstup user has only one address. The user's address will be set to either:

  • The first address, or... * The first address marked primary. Sending anything other than an array (which may be empty) is an error.
titlestring(Scim.User.Core.title)

A string containing the user's job title.

Example: "Vice President"
photosArray of objects(Scim.User.Core.photos.incoming)

The user's photo (avatar).

  • Firstup users have a single avatar photo.
  • The single photo must be contained within an array.
  • Sending multiple photos is ok but only the first photo is used.
  • Only the first photo is validated for correctness.
preferredLanguagestring(Scim.User.Core.preferredLanguage)

A string containing the user's preferred language.

Example: "en-US"
userTypestring(Scim.User.Core.userType)

The user's employee type

Example: "Associate"
localestring(Scim.User.Core.locale)

The user's locale.

Example: "en-US"
timezonestring(Scim.User.Core.timezone)

The user's timezone.

Example: "US/Chicago"
urn:SocialChorus:1.0:Userobject(Scim.User.SocialChorusExtension)
urn:ietf:params:scim:schemas:extension:enterprise:2.0:Userobject(Scim.User.EnterpriseExtension)
curl -i -X POST \
  https://developers.firstup.io/scim/v2/Users \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "janeDoe123",
    "name": {
      "givenName": "Jane",
      "familyName": "Doe"
    },
    "displayName": "string",
    "externalId": "ext_123489",
    "nickName": "Jane",
    "active": true,
    "roles": "publisher",
    "phoneNumbers": [
      {
        "value": "555-1212",
        "type": "mobile",
        "primary": true
      }
    ],
    "emails": [
      {
        "value": "janedoe@email.com",
        "primary": true,
        "type": "work"
      }
    ],
    "addresses": [
      {
        "streetAddress": "123 Mission St",
        "locality": "San Francisco",
        "region": "CA",
        "postalCode": "94105",
        "country": "US",
        "primary": false,
        "formatted": "123 Mission St, San Francisco, CA, 94105",
        "type": "work"
      }
    ],
    "title": "Vice President",
    "photos": [
      {
        "type": "photo",
        "value": "http://an.image/url"
      }
    ],
    "preferredLanguage": "en-US",
    "userType": "Associate",
    "locale": "en-US",
    "timezone": "US/Chicago",
    "urn:SocialChorus:1.0:User": {
      "businessUnit": "Accounts Receivable",
      "gender": "Female",
      "managerName": "Jimmy Dean",
      "workLocation": "Kabukicho",
      "birthDate": "2000-01-01T00:00:00.000Z",
      "hireDate": "2000-01-01T00:00:00.000Z",
      "promotionDate": "2000-01-01T00:00:00.000Z",
      "requisitionApprovalDate": "2000-01-01T00:00:00.000Z",
      "lastAccessedAt": "2000-01-01T00:00:00.000Z",
      "customAttributes": [
        {
          "name": "favorite_food",
          "value": "pizza"
        },
        {
          "name": "favorite_sport",
          "value": "soccer"
        },
        {
          "name": "hair_color",
          "value": "brown"
        }
      ]
    },
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
      "employeeNumber": "abc123",
      "organization": "Firstup",
      "department": "HR",
      "costCenter": "NY",
      "division": "THCI"
    }
  }'

Responses

User created

Bodyapplication/scim+json
metaobject
idstring(Scim.User.Core.id)

An immutable string identifier for the user. This value will never change once a user is created.

Example: "8675309"
userNamestring(Scim.User.Core.userName)

userName uniquely identifies a user in the scope of your organization. It can be updated by the client, but must remain unique.

In Firstup Studio it is referred to as federated_identifier.

Example: "janeDoe123"
programMembershipIdstring(Scim.User.Core.programMembershipId)

An immutable string identifier for the user's program membership.

Example: "262574"
externalId(string or null) or (integer or null)(Scim.User.Core.externalId)

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

Example: "ext_123489"
One of:

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

string or null

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

nameobject(Scim.User.Core.name)

An object containing multiple parts that make up a user's name.

displayNamestring or null(Scim.User.Core.displayName)
Please refrain from using this attribute without prior consultation with our support staff.

This attribute serves a distinct purpose within the Firstup system, requires a specific format and inappropriate use may introduce unintended side effects.

nickNamestring or null(Scim.User.Core.nickName)

The casual way to address the user in real life.

Example: "Jane"
rolesScim.User.Core.roleString (string) or (Array of Scim.User.Core.rolesObjectArray (Scim.User.Core.roleString (string) or Scim.User.Core.roleObject (object)))(Scim.User.Core.roles)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

One of:

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

string(Scim.User.Core.roleString)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

Default "member"
Enum"administrator""program_manager""analyst""publisher""channel_contributor""member"
emailsArray of objects(Scim.User.Core.emails)

A list of the user's emails. If a user has no emails this will be an empty list.

photosArray of objects(Scim.User.Core.photos)

A list containing at most a single element, the user's avatar photo URL. If a user has no avatar photo URL this will be an empty list.

phoneNumbersArray of objects(Scim.User.Core.phoneNumbers)

A list of the user's phone numbers.

If a user has no phone numbers this will be an empty list.

Firstup only saves and returns phone numbers with a type of main and mobile.

addressesArray of objects(Scim.User.Core.addresses)

The user's addresses in the program. A Firstup user has only one address. The user's address will be set to either:

  • The first address, or... * The first address marked primary. Sending anything other than an array (which may be empty) is an error.
titlestring(Scim.User.Core.title)

A string containing the user's job title.

Example: "Vice President"
userTypestring(Scim.User.Core.userType)

The user's employee type

Example: "Associate"
localestring(Scim.User.Core.locale)

The user's locale.

Example: "en-US"
timezonestring(Scim.User.Core.timezone)

The user's timezone.

Example: "US/Chicago"
preferredLanguagestring(Scim.User.Core.preferredLanguage)

A string containing the user's preferred language.

Example: "en-US"
activeboolean or string(Scim.User.Core.active)

Whether or not the user is currently marked "active" in the program.

Example: true
One of:

Whether or not the user is currently marked "active" in the program.

boolean

Whether or not the user is currently marked "active" in the program.

urn:SocialChorus:1.0:Userobject(Scim.User.SocialChorusExtension)
urn:ietf:params:scim:schemas:extension:enterprise:2.0:Userobject(Scim.User.EnterpriseExtension)
schemasArray of strings
Example: ["urn:ietf:params:scim:schemas:core:2.0:User"]
Response
application/scim+json
{
  "meta": {
    "resourceType": "User"
  },
  "id": "8675309",
  "userName": "janeDoe123",
  "programMembershipId": "262574",
  "externalId": "ext_123489",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "string",
  "nickName": "Jane",
  "roles": "publisher",
  "emails": [
    { … }
  ],
  "photos": [
    { … }
  ],
  "phoneNumbers": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "title": "Vice President",
  "userType": "Associate",
  "locale": "en-US",
  "timezone": "US/Chicago",
  "preferredLanguage": "en-US",
  "active": true,
  "urn:SocialChorus:1.0:User": {
    "businessUnit": "Accounts Receivable",
    "gender": "Female",
    "managerName": "Jimmy Dean",
    "workLocation": "Kabukicho",
    "birthDate": "2000-01-01T00:00:00.000Z",
    "hireDate": "2000-01-01T00:00:00.000Z",
    "promotionDate": "2000-01-01T00:00:00.000Z",
    "requisitionApprovalDate": "2000-01-01T00:00:00.000Z",
    "lastAccessedAt": "2000-01-01T00:00:00.000Z",
    "customAttributes": [ … ]
  },
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "abc123",
    "organization": "Firstup",
    "department": "HR",
    "costCenter": "NY",
    "division": "THCI"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ]
}

Show a single program user by ID

Request

Returns a User record for specified user in the program.

Security
oauth2_as_a_server or oauth2_as_a_user
Path
user_idstringrequired

Identifier of the user to look up. It could be used either the user's id, federated identifier, an email address, or external Id. The look up will be done in the above mentioned order.

curl -i -X GET \
  'https://developers.firstup.io/scim/v2/Users/{user_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/scim+json
metaobject
idstring(Scim.User.Core.id)

An immutable string identifier for the user. This value will never change once a user is created.

Example: "8675309"
userNamestring(Scim.User.Core.userName)

userName uniquely identifies a user in the scope of your organization. It can be updated by the client, but must remain unique.

In Firstup Studio it is referred to as federated_identifier.

Example: "janeDoe123"
programMembershipIdstring(Scim.User.Core.programMembershipId)

An immutable string identifier for the user's program membership.

Example: "262574"
externalId(string or null) or (integer or null)(Scim.User.Core.externalId)

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

Example: "ext_123489"
One of:

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

string or null

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

nameobject(Scim.User.Core.name)

An object containing multiple parts that make up a user's name.

displayNamestring or null(Scim.User.Core.displayName)
Please refrain from using this attribute without prior consultation with our support staff.

This attribute serves a distinct purpose within the Firstup system, requires a specific format and inappropriate use may introduce unintended side effects.

nickNamestring or null(Scim.User.Core.nickName)

The casual way to address the user in real life.

Example: "Jane"
rolesScim.User.Core.roleString (string) or (Array of Scim.User.Core.rolesObjectArray (Scim.User.Core.roleString (string) or Scim.User.Core.roleObject (object)))(Scim.User.Core.roles)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

One of:

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

string(Scim.User.Core.roleString)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

Default "member"
Enum"administrator""program_manager""analyst""publisher""channel_contributor""member"
emailsArray of objects(Scim.User.Core.emails)

A list of the user's emails. If a user has no emails this will be an empty list.

photosArray of objects(Scim.User.Core.photos)

A list containing at most a single element, the user's avatar photo URL. If a user has no avatar photo URL this will be an empty list.

phoneNumbersArray of objects(Scim.User.Core.phoneNumbers)

A list of the user's phone numbers.

If a user has no phone numbers this will be an empty list.

Firstup only saves and returns phone numbers with a type of main and mobile.

addressesArray of objects(Scim.User.Core.addresses)

The user's addresses in the program. A Firstup user has only one address. The user's address will be set to either:

  • The first address, or... * The first address marked primary. Sending anything other than an array (which may be empty) is an error.
titlestring(Scim.User.Core.title)

A string containing the user's job title.

Example: "Vice President"
userTypestring(Scim.User.Core.userType)

The user's employee type

Example: "Associate"
localestring(Scim.User.Core.locale)

The user's locale.

Example: "en-US"
timezonestring(Scim.User.Core.timezone)

The user's timezone.

Example: "US/Chicago"
preferredLanguagestring(Scim.User.Core.preferredLanguage)

A string containing the user's preferred language.

Example: "en-US"
activeboolean or string(Scim.User.Core.active)

Whether or not the user is currently marked "active" in the program.

Example: true
One of:

Whether or not the user is currently marked "active" in the program.

boolean

Whether or not the user is currently marked "active" in the program.

urn:SocialChorus:1.0:Userobject(Scim.User.SocialChorusExtension)
urn:ietf:params:scim:schemas:extension:enterprise:2.0:Userobject(Scim.User.EnterpriseExtension)
schemasArray of strings
Example: ["urn:ietf:params:scim:schemas:core:2.0:User"]
Response
application/scim+json
{
  "meta": {
    "resourceType": "User"
  },
  "id": "8675309",
  "userName": "janeDoe123",
  "programMembershipId": "262574",
  "externalId": "ext_123489",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "string",
  "nickName": "Jane",
  "roles": "publisher",
  "emails": [
    { … }
  ],
  "photos": [
    { … }
  ],
  "phoneNumbers": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "title": "Vice President",
  "userType": "Associate",
  "locale": "en-US",
  "timezone": "US/Chicago",
  "preferredLanguage": "en-US",
  "active": true,
  "urn:SocialChorus:1.0:User": {
    "businessUnit": "Accounts Receivable",
    "gender": "Female",
    "managerName": "Jimmy Dean",
    "workLocation": "Kabukicho",
    "birthDate": "2000-01-01T00:00:00.000Z",
    "hireDate": "2000-01-01T00:00:00.000Z",
    "promotionDate": "2000-01-01T00:00:00.000Z",
    "requisitionApprovalDate": "2000-01-01T00:00:00.000Z",
    "lastAccessedAt": "2000-01-01T00:00:00.000Z",
    "customAttributes": [ … ]
  },
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "abc123",
    "organization": "Firstup",
    "department": "HR",
    "costCenter": "NY",
    "division": "THCI"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ]
}

Replace a user in the program

Request

To update or replace user information, ensure that your request includes a comprehensive set of user attributes. ⚠ Utilize PUT endpoints carefully. Modified data models caused by new features or user-defined fields may lead to data loss. For a seamless process, consider the following:

  1. GET the user record using 🔗 /scim/v2/Users/{user_id} 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.
Security
oauth2_as_a_server or oauth2_as_a_user
Path
user_idstringrequired

ID of the user to update

Bodyapplication/jsonrequired
userNamestring(Scim.User.Core.userName)

userName uniquely identifies a user in the scope of your organization. It can be updated by the client, but must remain unique.

In Firstup Studio it is referred to as federated_identifier.

Example: "janeDoe123"
activeboolean

Whether the user is active or blocked in the program.

Example: true
nameobject(Scim.User.Core.name)

An object containing multiple parts that make up a user's name.

displayNamestring or null(Scim.User.Core.displayName)
Please refrain from using this attribute without prior consultation with our support staff.

This attribute serves a distinct purpose within the Firstup system, requires a specific format and inappropriate use may introduce unintended side effects.

nickNamestring or null(Scim.User.Core.nickName)

The casual way to address the user in real life.

Example: "Jane"
rolesScim.User.Core.roleString (string) or (Array of Scim.User.Core.rolesObjectArray (Scim.User.Core.roleString (string) or Scim.User.Core.roleObject (object)))(Scim.User.Core.roles)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

One of:

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

string(Scim.User.Core.roleString)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

Default "member"
Enum"administrator""program_manager""analyst""publisher""channel_contributor""member"
emailsArray of objects(Scim.User.Core.emails)

A list of the user's emails. If a user has no emails this will be an empty list.

addressesArray of objects(Scim.User.Core.addresses)

The user's addresses in the program. A Firstup user has only one address. The user's address will be set to either:

  • The first address, or... * The first address marked primary. Sending anything other than an array (which may be empty) is an error.
titlestring(Scim.User.Core.title)

A string containing the user's job title.

Example: "Vice President"
photosArray of objects(Scim.User.Core.photos.incoming)

The user's photo (avatar).

  • Firstup users have a single avatar photo.
  • The single photo must be contained within an array.
  • Sending multiple photos is ok but only the first photo is used.
  • Only the first photo is validated for correctness.
preferredLanguagestring(Scim.User.Core.preferredLanguage)

A string containing the user's preferred language.

Example: "en-US"
userTypestring(Scim.User.Core.userType)

The user's employee type

Example: "Associate"
localestring(Scim.User.Core.locale)

The user's locale.

Example: "en-US"
timezonestring(Scim.User.Core.timezone)

The user's timezone.

Example: "US/Chicago"
urn:SocialChorus:1.0:Userobject(Scim.User.SocialChorusExtension)
urn:ietf:params:scim:schemas:extension:enterprise:2.0:Userobject(Scim.User.EnterpriseExtension)
curl -i -X PUT \
  'https://developers.firstup.io/scim/v2/Users/{user_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "userName": "janeDoe123",
    "active": true,
    "name": {
      "givenName": "Jane",
      "familyName": "Doe"
    },
    "displayName": "string",
    "nickName": "Jane",
    "roles": "publisher",
    "emails": [
      {
        "value": "janedoe@email.com",
        "primary": true,
        "type": "work"
      }
    ],
    "addresses": [
      {
        "streetAddress": "123 Mission St",
        "locality": "San Francisco",
        "region": "CA",
        "postalCode": "94105",
        "country": "US",
        "primary": false,
        "formatted": "123 Mission St, San Francisco, CA, 94105",
        "type": "work"
      }
    ],
    "title": "Vice President",
    "photos": [
      {
        "type": "photo",
        "value": "http://an.image/url"
      }
    ],
    "preferredLanguage": "en-US",
    "userType": "Associate",
    "locale": "en-US",
    "timezone": "US/Chicago",
    "urn:SocialChorus:1.0:User": {
      "businessUnit": "Accounts Receivable",
      "gender": "Female",
      "managerName": "Jimmy Dean",
      "workLocation": "Kabukicho",
      "birthDate": "2000-01-01T00:00:00.000Z",
      "hireDate": "2000-01-01T00:00:00.000Z",
      "promotionDate": "2000-01-01T00:00:00.000Z",
      "requisitionApprovalDate": "2000-01-01T00:00:00.000Z",
      "lastAccessedAt": "2000-01-01T00:00:00.000Z",
      "customAttributes": [
        {
          "name": "favorite_food",
          "value": "pizza"
        },
        {
          "name": "favorite_sport",
          "value": "soccer"
        },
        {
          "name": "hair_color",
          "value": "brown"
        }
      ]
    },
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
      "employeeNumber": "abc123",
      "organization": "Firstup",
      "department": "HR",
      "costCenter": "NY",
      "division": "THCI"
    }
  }'

Responses

Success

Bodyapplication/scim+json
metaobject
idstring(Scim.User.Core.id)

An immutable string identifier for the user. This value will never change once a user is created.

Example: "8675309"
userNamestring(Scim.User.Core.userName)

userName uniquely identifies a user in the scope of your organization. It can be updated by the client, but must remain unique.

In Firstup Studio it is referred to as federated_identifier.

Example: "janeDoe123"
programMembershipIdstring(Scim.User.Core.programMembershipId)

An immutable string identifier for the user's program membership.

Example: "262574"
externalId(string or null) or (integer or null)(Scim.User.Core.externalId)

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

Example: "ext_123489"
One of:

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

string or null

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

nameobject(Scim.User.Core.name)

An object containing multiple parts that make up a user's name.

displayNamestring or null(Scim.User.Core.displayName)
Please refrain from using this attribute without prior consultation with our support staff.

This attribute serves a distinct purpose within the Firstup system, requires a specific format and inappropriate use may introduce unintended side effects.

nickNamestring or null(Scim.User.Core.nickName)

The casual way to address the user in real life.

Example: "Jane"
rolesScim.User.Core.roleString (string) or (Array of Scim.User.Core.rolesObjectArray (Scim.User.Core.roleString (string) or Scim.User.Core.roleObject (object)))(Scim.User.Core.roles)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

One of:

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

string(Scim.User.Core.roleString)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

Default "member"
Enum"administrator""program_manager""analyst""publisher""channel_contributor""member"
emailsArray of objects(Scim.User.Core.emails)

A list of the user's emails. If a user has no emails this will be an empty list.

photosArray of objects(Scim.User.Core.photos)

A list containing at most a single element, the user's avatar photo URL. If a user has no avatar photo URL this will be an empty list.

phoneNumbersArray of objects(Scim.User.Core.phoneNumbers)

A list of the user's phone numbers.

If a user has no phone numbers this will be an empty list.

Firstup only saves and returns phone numbers with a type of main and mobile.

addressesArray of objects(Scim.User.Core.addresses)

The user's addresses in the program. A Firstup user has only one address. The user's address will be set to either:

  • The first address, or... * The first address marked primary. Sending anything other than an array (which may be empty) is an error.
titlestring(Scim.User.Core.title)

A string containing the user's job title.

Example: "Vice President"
userTypestring(Scim.User.Core.userType)

The user's employee type

Example: "Associate"
localestring(Scim.User.Core.locale)

The user's locale.

Example: "en-US"
timezonestring(Scim.User.Core.timezone)

The user's timezone.

Example: "US/Chicago"
preferredLanguagestring(Scim.User.Core.preferredLanguage)

A string containing the user's preferred language.

Example: "en-US"
activeboolean or string(Scim.User.Core.active)

Whether or not the user is currently marked "active" in the program.

Example: true
One of:

Whether or not the user is currently marked "active" in the program.

boolean

Whether or not the user is currently marked "active" in the program.

urn:SocialChorus:1.0:Userobject(Scim.User.SocialChorusExtension)
urn:ietf:params:scim:schemas:extension:enterprise:2.0:Userobject(Scim.User.EnterpriseExtension)
schemasArray of strings
Example: ["urn:ietf:params:scim:schemas:core:2.0:User"]
Response
application/scim+json
{
  "meta": {
    "resourceType": "User"
  },
  "id": "8675309",
  "userName": "janeDoe123",
  "programMembershipId": "262574",
  "externalId": "ext_123489",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "string",
  "nickName": "Jane",
  "roles": "publisher",
  "emails": [
    { … }
  ],
  "photos": [
    { … }
  ],
  "phoneNumbers": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "title": "Vice President",
  "userType": "Associate",
  "locale": "en-US",
  "timezone": "US/Chicago",
  "preferredLanguage": "en-US",
  "active": true,
  "urn:SocialChorus:1.0:User": {
    "businessUnit": "Accounts Receivable",
    "gender": "Female",
    "managerName": "Jimmy Dean",
    "workLocation": "Kabukicho",
    "birthDate": "2000-01-01T00:00:00.000Z",
    "hireDate": "2000-01-01T00:00:00.000Z",
    "promotionDate": "2000-01-01T00:00:00.000Z",
    "requisitionApprovalDate": "2000-01-01T00:00:00.000Z",
    "lastAccessedAt": "2000-01-01T00:00:00.000Z",
    "customAttributes": [ … ]
  },
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "abc123",
    "organization": "Firstup",
    "department": "HR",
    "costCenter": "NY",
    "division": "THCI"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ]
}

Update a user in the program

Request

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.

Security
oauth2_as_a_server or oauth2_as_a_user
Path
user_idstringrequired

Identifier of the user to patch. It could be used either the user's id, federated identifier, an email address, or external Id. The look up will be done in the above mentioned order.

Bodyapplication/jsonrequired
schemasArray of strings
Example: ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]
OperationsArray of objects
Example: [{"op":"replace","path":"active","value":false},{"op":"replace","path":"emails[type eq \"work\"].value","value":"janedoe@email.com"}]
curl -i -X PATCH \
  'https://developers.firstup.io/scim/v2/Users/{user_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
      {
        "op": "replace",
        "path": "active",
        "value": false
      },
      {
        "op": "replace",
        "path": "emails[type eq \"work\"].value",
        "value": "janedoe@email.com"
      }
    ]
  }'

Responses

Success

Bodyapplication/scim+json
metaobject
idstring(Scim.User.Core.id)

An immutable string identifier for the user. This value will never change once a user is created.

Example: "8675309"
userNamestring(Scim.User.Core.userName)

userName uniquely identifies a user in the scope of your organization. It can be updated by the client, but must remain unique.

In Firstup Studio it is referred to as federated_identifier.

Example: "janeDoe123"
programMembershipIdstring(Scim.User.Core.programMembershipId)

An immutable string identifier for the user's program membership.

Example: "262574"
externalId(string or null) or (integer or null)(Scim.User.Core.externalId)

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

Example: "ext_123489"
One of:

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

string or null

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

nameobject(Scim.User.Core.name)

An object containing multiple parts that make up a user's name.

displayNamestring or null(Scim.User.Core.displayName)
Please refrain from using this attribute without prior consultation with our support staff.

This attribute serves a distinct purpose within the Firstup system, requires a specific format and inappropriate use may introduce unintended side effects.

nickNamestring or null(Scim.User.Core.nickName)

The casual way to address the user in real life.

Example: "Jane"
rolesScim.User.Core.roleString (string) or (Array of Scim.User.Core.rolesObjectArray (Scim.User.Core.roleString (string) or Scim.User.Core.roleObject (object)))(Scim.User.Core.roles)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

One of:

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

string(Scim.User.Core.roleString)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

Default "member"
Enum"administrator""program_manager""analyst""publisher""channel_contributor""member"
emailsArray of objects(Scim.User.Core.emails)

A list of the user's emails. If a user has no emails this will be an empty list.

photosArray of objects(Scim.User.Core.photos)

A list containing at most a single element, the user's avatar photo URL. If a user has no avatar photo URL this will be an empty list.

phoneNumbersArray of objects(Scim.User.Core.phoneNumbers)

A list of the user's phone numbers.

If a user has no phone numbers this will be an empty list.

Firstup only saves and returns phone numbers with a type of main and mobile.

addressesArray of objects(Scim.User.Core.addresses)

The user's addresses in the program. A Firstup user has only one address. The user's address will be set to either:

  • The first address, or... * The first address marked primary. Sending anything other than an array (which may be empty) is an error.
titlestring(Scim.User.Core.title)

A string containing the user's job title.

Example: "Vice President"
userTypestring(Scim.User.Core.userType)

The user's employee type

Example: "Associate"
localestring(Scim.User.Core.locale)

The user's locale.

Example: "en-US"
timezonestring(Scim.User.Core.timezone)

The user's timezone.

Example: "US/Chicago"
preferredLanguagestring(Scim.User.Core.preferredLanguage)

A string containing the user's preferred language.

Example: "en-US"
activeboolean or string(Scim.User.Core.active)

Whether or not the user is currently marked "active" in the program.

Example: true
One of:

Whether or not the user is currently marked "active" in the program.

boolean

Whether or not the user is currently marked "active" in the program.

urn:SocialChorus:1.0:Userobject(Scim.User.SocialChorusExtension)
urn:ietf:params:scim:schemas:extension:enterprise:2.0:Userobject(Scim.User.EnterpriseExtension)
schemasArray of strings
Example: ["urn:ietf:params:scim:schemas:core:2.0:User"]
Response
application/scim+json
{
  "meta": {
    "resourceType": "User"
  },
  "id": "8675309",
  "userName": "janeDoe123",
  "programMembershipId": "262574",
  "externalId": "ext_123489",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "string",
  "nickName": "Jane",
  "roles": "publisher",
  "emails": [
    { … }
  ],
  "photos": [
    { … }
  ],
  "phoneNumbers": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "title": "Vice President",
  "userType": "Associate",
  "locale": "en-US",
  "timezone": "US/Chicago",
  "preferredLanguage": "en-US",
  "active": true,
  "urn:SocialChorus:1.0:User": {
    "businessUnit": "Accounts Receivable",
    "gender": "Female",
    "managerName": "Jimmy Dean",
    "workLocation": "Kabukicho",
    "birthDate": "2000-01-01T00:00:00.000Z",
    "hireDate": "2000-01-01T00:00:00.000Z",
    "promotionDate": "2000-01-01T00:00:00.000Z",
    "requisitionApprovalDate": "2000-01-01T00:00:00.000Z",
    "lastAccessedAt": "2000-01-01T00:00:00.000Z",
    "customAttributes": [ … ]
  },
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "abc123",
    "organization": "Firstup",
    "department": "HR",
    "costCenter": "NY",
    "division": "THCI"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ]
}

Completely remove a user from the system

Request

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.

Security
oauth2_as_a_server or oauth2_as_a_user
Path
user_idstringrequired

Identifier of the user to delete. It could be used either the user's id, federated identifier, an email address, or external Id. The look up will be done in the above mentioned order.

curl -i -X DELETE \
  'https://developers.firstup.io/scim/v2/Users/{user_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Show information about the current user

Request

Returns a User record for specified user in the program.


Note: Customers can't use Client Credentials auth for this endpoint.

curl -i -X GET \
  https://developers.firstup.io/scim/v2/Users/me

Responses

Success

Bodyapplication/scim+json
metaobject
idstring(Scim.User.Core.id)

An immutable string identifier for the user. This value will never change once a user is created.

Example: "8675309"
userNamestring(Scim.User.Core.userName)

userName uniquely identifies a user in the scope of your organization. It can be updated by the client, but must remain unique.

In Firstup Studio it is referred to as federated_identifier.

Example: "janeDoe123"
programMembershipIdstring(Scim.User.Core.programMembershipId)

An immutable string identifier for the user's program membership.

Example: "262574"
externalId(string or null) or (integer or null)(Scim.User.Core.externalId)

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

Example: "ext_123489"
One of:

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

string or null

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

nameobject(Scim.User.Core.name)

An object containing multiple parts that make up a user's name.

displayNamestring or null(Scim.User.Core.displayName)
Please refrain from using this attribute without prior consultation with our support staff.

This attribute serves a distinct purpose within the Firstup system, requires a specific format and inappropriate use may introduce unintended side effects.

nickNamestring or null(Scim.User.Core.nickName)

The casual way to address the user in real life.

Example: "Jane"
rolesScim.User.Core.roleString (string) or (Array of Scim.User.Core.rolesObjectArray (Scim.User.Core.roleString (string) or Scim.User.Core.roleObject (object)))(Scim.User.Core.roles)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

One of:

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

string(Scim.User.Core.roleString)

Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.

Discover Available Roles

To explore available roles, make use of the GET request at /scim/v2/roles.

Available Legacy Roles

  • administrator
  • program_manager
  • analyst
  • publisher
  • channel_contributor
  • member

Additional Resources

For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

Backward Compatibility:

  • Support the original single-string legacy role format ["legacy_role"]
  • Legacy roles include "administrator", "program_manager", "analyst", "publisher", "channel_contributor", or "member".
  • GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact support@firstup.io if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

Limitation Notice: Scope

In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.

Issue: Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.

Impact: Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.

Recommendation: To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

Default "member"
Enum"administrator""program_manager""analyst""publisher""channel_contributor""member"
emailsArray of objects(Scim.User.Core.emails)

A list of the user's emails. If a user has no emails this will be an empty list.

photosArray of objects(Scim.User.Core.photos)

A list containing at most a single element, the user's avatar photo URL. If a user has no avatar photo URL this will be an empty list.

phoneNumbersArray of objects(Scim.User.Core.phoneNumbers)

A list of the user's phone numbers.

If a user has no phone numbers this will be an empty list.

Firstup only saves and returns phone numbers with a type of main and mobile.

addressesArray of objects(Scim.User.Core.addresses)

The user's addresses in the program. A Firstup user has only one address. The user's address will be set to either:

  • The first address, or... * The first address marked primary. Sending anything other than an array (which may be empty) is an error.
titlestring(Scim.User.Core.title)

A string containing the user's job title.

Example: "Vice President"
userTypestring(Scim.User.Core.userType)

The user's employee type

Example: "Associate"
localestring(Scim.User.Core.locale)

The user's locale.

Example: "en-US"
timezonestring(Scim.User.Core.timezone)

The user's timezone.

Example: "US/Chicago"
preferredLanguagestring(Scim.User.Core.preferredLanguage)

A string containing the user's preferred language.

Example: "en-US"
activeboolean or string(Scim.User.Core.active)

Whether or not the user is currently marked "active" in the program.

Example: true
One of:

Whether or not the user is currently marked "active" in the program.

boolean

Whether or not the user is currently marked "active" in the program.

urn:SocialChorus:1.0:Userobject(Scim.User.SocialChorusExtension)
urn:ietf:params:scim:schemas:extension:enterprise:2.0:Userobject(Scim.User.EnterpriseExtension)
schemasArray of strings
Example: ["urn:ietf:params:scim:schemas:core:2.0:User"]
Response
application/scim+json
{
  "meta": {
    "resourceType": "User"
  },
  "id": "8675309",
  "userName": "janeDoe123",
  "programMembershipId": "262574",
  "externalId": "ext_123489",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "string",
  "nickName": "Jane",
  "roles": "publisher",
  "emails": [
    { … }
  ],
  "photos": [
    { … }
  ],
  "phoneNumbers": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "title": "Vice President",
  "userType": "Associate",
  "locale": "en-US",
  "timezone": "US/Chicago",
  "preferredLanguage": "en-US",
  "active": true,
  "urn:SocialChorus:1.0:User": {
    "businessUnit": "Accounts Receivable",
    "gender": "Female",
    "managerName": "Jimmy Dean",
    "workLocation": "Kabukicho",
    "birthDate": "2000-01-01T00:00:00.000Z",
    "hireDate": "2000-01-01T00:00:00.000Z",
    "promotionDate": "2000-01-01T00:00:00.000Z",
    "requisitionApprovalDate": "2000-01-01T00:00:00.000Z",
    "lastAccessedAt": "2000-01-01T00:00:00.000Z",
    "customAttributes": [ … ]
  },
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "abc123",
    "organization": "Firstup",
    "department": "HR",
    "costCenter": "NY",
    "division": "THCI"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ]
}

Completely remove a user from the system (Not SCIM compliant)

Request

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.

Security
oauth2_as_a_server or oauth2_as_a_user
Path
user_idstringrequired

ID of the user to forget

curl -i -X POST \
  'https://developers.firstup.io/v2/Users/{user_id}/forget' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

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

Assistant Inbox

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

Operations

User Roles

Operations

Notification Center

Operations