# Create a user in the program

Create and provision a new user. The request should include any properties to be set on the user, and leaving any out will leave those values blank, or will use defaults.  New users have a role of "member" by default. New users have an onboarding status of "created" by default.  Setting a user's role requires that the acting user have a role the same or less than the role of the user being created. The role property is also formatted as an array to comply with SCIM protocol though it only accepts a single value. Providing more than one value will result in a 400 response. {% admonition type="info" %} Additional documentation and resources    User roles and access    User provisioning  *  SCIM user provisioning  {% /admonition%}

Endpoint: POST /scim/v2/Users
Version: 2026-04-10
Security: oauth2_as_a_server, oauth2_as_a_user

## Request fields (application/json):

  - `schemas` (array)
    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"

  - `userName` (string, 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"

  - `name` (object)
    An object containing multiple parts that make up a user's name.

  - `name.givenName` (string, required)
    User's first name
    Example: "Jane"

  - `name.familyName` (string, required)
    User's last name
    Example: "Doe"

  - `displayName` (string,null)
    {% admonition type="warning" %} Please refrain from using this attribute without prior consultation with our support staff.{% /admonition %}

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

  - `externalId` (any)
    ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.
    Example: "ext_123489"

  - `nickName` (string,null)
    The casual way to address the user in real life.
    Example: "Jane"

  - `active` (any)
    Whether or not the user is currently marked "active" in the program.
    Example: true

  - `roles` (any)
    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.

{% admonition type="info" %}Extended documentation explaining how user roles and access works within our API can be found  here. {% /admonition %}

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:

- [Roles-Standard](https://support.firstup.io/hc/en-us/articles/6278321908503)
- [Roles-Custom](https://support.firstup.io/hc/en-us/articles/6744088254359)
- [Scopes or Restrictions](https://support.firstup.io/hc/en-us/articles/6278321908503#h_01HBV399TW5WN1ZZABQF845H4E)
- [Legacy Roles](https://howto.socialchorus.com/hc/en-us/articles/115006356588#h_23542235341518566935216)

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](https://support.firstup.io/hc/en-us) if you need to switch the syntax.

{% admonition type="info" %}Firstup users have a single role and legacy_role but can have multiple scopes applied.{% /admonition %}

---

> ### 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.

---

  - `phoneNumbers` (array)
    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.

  - `phoneNumbers.value` (string)
    A phone number
    Example: "555-1212"

  - `phoneNumbers.type` (string)
    The type of phone number. Only "main" and "mobile" are saved or returned by Firstup. {% admonition type="warning" %}DO NOT use work as the phone number type because it will be ignored. It's listed for third-party compatibility only.{% /admonition %}
    Enum: "main", "mobile", "work"

  - `phoneNumbers.primary` (boolean)
    This optional attribute is for compatibility purposes only and is ignored by Firstup.
    Example: true

  - `emails` (array)
    A list of the user's emails.
If a user has no emails this will be an empty list.

  - `emails.value` (string)
    A valid email address
    Example: "janedoe@email.com"

  - `emails.primary` (boolean)
    Indicates if the value is the user's primary email address
    Example: true

  - `emails.type` (string,null)
    An email type. Should be one of "work", "home", "other" or null
    Enum: "work", "home", "other", null

  - `addresses` (array)
    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.

  - `addresses.streetAddress` (string,null)
    A street address, e.g., house number and street name.
    Example: "123 Mission St"

  - `addresses.locality` (string,null)
    Address's locality, e.g, in the US, the city.
    Example: "San Francisco"

  - `addresses.region` (string,null)
    Address's region, e.g., in the US, the state.
    Example: "CA"

  - `addresses.postalCode` (string,null)
    Address's postal code, e.g., in the US, the zip code.
    Example: "94105"

  - `addresses.country` (string,null)
    Address's country.
    Example: "US"

  - `addresses.primary` (boolean)
    Is address primary

  - `addresses.formatted` (string,null)
    Complete address as formatted string.
    Example: "123 Mission St, San Francisco, CA, 94105"

  - `addresses.type` (string,null)
    Address type. This field is ignored by Firstup.
    Example: "work"

  - `title` (string)
    A string containing the user's job title.
    Example: "Vice President"

  - `photos` (array)
    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.

  - `photos.type` (string)
    The type of photo.

Only "photo" is supported—any other value is an error.
    Example: "photo"

  - `photos.value` (string)
    The URI of the photo (avatar).

URIs may be HTTP, HTTPS, or DATA. DATA URIs must contain a complete data URI including the MIME type, encoding, and data, e.g., data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...

All photos are downloaded by Firstup and self-hosted: the resulting photo URL will not be the same as the incoming URI.
    Example: "http://an.image/url"

  - `preferredLanguage` (string)
    A string containing the user's preferred language.
    Example: "en-US"

  - `userType` (string)
    The user's employee type
    Example: "Associate"

  - `locale` (string)
    The user's locale.
    Example: "en-US"

  - `timezone` (string)
    The user's geographical timezone (IANA format. Note, this is case sensitive).
    Example: "America/Chicago"

  - `urn:SocialChorus:1.0:User` (object)

  - `urn:SocialChorus:1.0:User.businessUnit` (string,null)
    The user's business unit.
    Example: "Accounts Receivable"

  - `urn:SocialChorus:1.0:User.gender` (string,null)
    The user's gender.
    Example: "Female"

  - `urn:SocialChorus:1.0:User.pronouns` (string,null)
    The user's pronouns.
    Example: "they/them"

  - `urn:SocialChorus:1.0:User.managerName` (string,null)
    The user's manager's name.
    Example: "Jimmy Dean"

  - `urn:SocialChorus:1.0:User.workLocation` (string,null)
    The user's work location.
    Example: "Kabukicho"

  - `urn:SocialChorus:1.0:User.birthDate` (string,null)
    The user's birth date.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.hireDate` (string,null)
    The user's start of employment date.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.promotionDate` (string,null)
    The user's promotion date.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.requisitionApprovalDate` (string,null)
    The Requisition Approval date.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.lastAccessedAt` (string,null)
    Please contact your Firstup representative for more information.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.customAttributes` (array)
    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.
    Example: [{"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` (object)

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.employeeNumber` (string,null)
    An employee id or identifier used in external systems.
    Example: "abc123"

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.organization` (string,null)
    The employee organization name
    Example: "Firstup"

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.department` (string,null)
    The employee's department name
    Example: "HR"

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.costCenter` (string,null)
    The user's cost center
    Example: "NY"

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.division` (string,null)
    The user's division
    Example: "THCI"

## Response 201 fields (application/scim+json):

  - `meta` (object)

  - `meta.resourceType` (string)
    Example: "User"

  - `id` (string)
    An immutable string identifier for the user. This value will never change once a user is created.
    Example: "8675309"

  - `userName` (string)
    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"

  - `programMembershipId` (string)
    An immutable string identifier for the user's program membership.
    Example: "262574"

  - `externalId` (any)
    ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.
    Example: "ext_123489"

  - `name` (object)
    An object containing multiple parts that make up a user's name.

  - `displayName` (string,null)
    {% admonition type="warning" %} Please refrain from using this attribute without prior consultation with our support staff.{% /admonition %}

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

  - `nickName` (string,null)
    The casual way to address the user in real life.
    Example: "Jane"

  - `roles` (any)
    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.

{% admonition type="info" %}Extended documentation explaining how user roles and access works within our API can be found  here. {% /admonition %}

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:

- [Roles-Standard](https://support.firstup.io/hc/en-us/articles/6278321908503)
- [Roles-Custom](https://support.firstup.io/hc/en-us/articles/6744088254359)
- [Scopes or Restrictions](https://support.firstup.io/hc/en-us/articles/6278321908503#h_01HBV399TW5WN1ZZABQF845H4E)
- [Legacy Roles](https://howto.socialchorus.com/hc/en-us/articles/115006356588#h_23542235341518566935216)

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](https://support.firstup.io/hc/en-us) if you need to switch the syntax.

{% admonition type="info" %}Firstup users have a single role and legacy_role but can have multiple scopes applied.{% /admonition %}

---

> ### 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.

---

  - `emails` (array)
    A list of the user's emails.
If a user has no emails this will be an empty list.

  - `photos` (array)
    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.

  - `photos.value` (string)
    Direct link to photo image resource
    Example: "http://some.url/photo.png"

  - `photos.type` (string)
    The type of photo; only "photo" is supported.
    Enum: "photo"

  - `phoneNumbers` (array)
    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.

  - `addresses` (array)
    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.

  - `title` (string)
    A string containing the user's job title.
    Example: "Vice President"

  - `userType` (string)
    The user's employee type
    Example: "Associate"

  - `locale` (string)
    The user's locale.
    Example: "en-US"

  - `timezone` (string)
    The user's geographical timezone (IANA format. Note, this is case sensitive).
    Example: "America/Chicago"

  - `preferredLanguage` (string)
    A string containing the user's preferred language.
    Example: "en-US"

  - `active` (any)
    Whether or not the user is currently marked "active" in the program.
    Example: true

  - `urn:SocialChorus:1.0:User` (object)

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` (object)

  - `schemas` (array)
    Example: ["urn:ietf:params:scim:schemas:core:2.0:User"]

## Response 400 fields (*/*):

  - `schemas` (array)
    Example: ["urn:ietf:params:scim:api:messages:2.0:Error"]

  - `detail` (string)
    Example: "Reason for bad request"

  - `status` (integer)
    Example: 400

## Response 401 fields (*/*):

  - `schemas` (array)
    Example: ["urn:ietf:params:scim:api:messages:2.0:Error"]

  - `detail` (string)
    Example: "Authentication failure"

  - `status` (integer)
    Example: 401

## Response 403 fields (*/*):

  - `schemas` (array)
    Example: ["urn:ietf:params:scim:api:messages:2.0:Error"]

  - `detail` (string)
    Example: "Operation is not permitted"

  - `status` (integer)
    Example: 403

## Response 422 fields (*/*):

  - `schemas` (array)
    Example: ["urn:ietf:params:scim:api:messages:2.0:Error"]

  - `detail` (array)

  - `detail.instancePath` (string)

  - `detail.schemaPath` (string)

  - `detail.keyword` (string)

  - `detail.params` (object)

  - `detail.message` (string)

  - `status` (integer)
    Example: 422