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.

Additional documentation and resources
* User roles and access
* User provisioning
* SCIM user provisioning

Security

oauth2_as_a_server(Required scopes: users.write) or oauth2_as_a_user(Required scopes: users.write)

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 universal_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)

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

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)

Example:true

One of:

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

boolean

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

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.

Extended documentation explaining how user roles and access works within our API can be found here.

Discover Available Roles

GET /scim/v2/roles to explore available 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 GET /scim/v2/users/{user_id} return this field based on a program configuration. Please contact Support if you need to switch the syntax.

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)

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 geographical timezone (IANA format. Note, this is case sensitive).

Example:"America/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://partner.socialchorus.com/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": "America/Chicago",
    "urn:SocialChorus:1.0:User": {
      "businessUnit": "Accounts Receivable",
      "gender": "Female",
      "pronouns": "they/them",
      "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 universal_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)

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

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 (any)(Scim.User.Core.roles)

One of:

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

Extended documentation explaining how user roles and access works within our API can be found here.

Discover Available Roles

GET /scim/v2/roles to explore available 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 GET /scim/v2/users/{user_id} return this field based on a program configuration. Please contact Support if you need to switch the syntax.

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)

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 geographical timezone (IANA format. Note, this is case sensitive).

Example:"America/Chicago"

preferredLanguagestring(Scim.User.Core.preferredLanguage)

A string containing the user's preferred language.

Example:"en-US"

activeboolean or string(Scim.User.Core.active)

Example:true

One of:

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

boolean

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

{
  "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": "America/Chicago",
  "preferredLanguage": "en-US",
  "active": true,
  "urn:SocialChorus:1.0:User": {
    "businessUnit": "Accounts Receivable",
    "gender": "Female",
    "pronouns": "they/them",
    "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"
  ]
}