# Create a user

Creates a user. Must include the userName attribute and an email address. User will be created as an SSO user by default and a federated ID must be provided for the user.

Endpoint: POST /scim/v2/Users
Version: 2026-02-20
Security: bearerAuth

## Header parameters:

  - `Idempotency-Key` (string)
    Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types. 

With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.

  - `Accept-Encoding` (string)
    Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response. 

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

  - `Content-Encoding` (string)
    Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

  - `Zuora-Track-Id` (string)
    A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

  - `Zuora-Entity-Ids` (string)
    An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header.

## Request fields (application/json):

  - `schemas` (array, required)
    List of schema URNs defining the structure of the user resource.

  - `name` (object, required)
    Name details of the user.

  - `name.givenName` (string)
    User's first name.

  - `name.familyName` (string)
    User's last name.

  - `name.formatted` (string)
    Formatted full name.

  - `active` (boolean, required)
    Indicates whether the user is active.

  - `emails` (array, required)
    List of email addresses associated with the user.

  - `emails.value` (string)
    Email address.

  - `emails.type` (string)
    Type of email (e.g., work, personal).

  - `emails.primary` (boolean)
    Indicates if this is the primary email.

  - `roles` (array, required)
    Roles assigned to the user.

  - `roles.value` (string)
    Role value (e.g., ADMIN).

  - `externalId` (string, required)
    External identifier for the user.

  - `userName` (string, required)
    Unique username for the user.

  - `preferredLanguage` (string, required)
    User's preferred language.

  - `locale` (string, required)
    User's locale.

  - `urn:zuora:scim:schemas:1.0:UserExtension` (object, required)
    Custom extension schema with additional attributes for the user.

  - `urn:zuora:scim:schemas:1.0:UserExtension.schemas` (array)
    List of URNs for the extension schemas.

  - `urn:zuora:scim:schemas:1.0:UserExtension.organizationId` (string)
    Identifier for the associated organization.

## Response 200 fields (application/json):

  - `schemas` (array)

  - `id` (string)
    Unique identifier for the user.

  - `externalId` (string)
    External identifier for the user.

  - `meta` (object)

  - `meta.created` (string)
    Timestamp of when the user was created.

  - `meta.resourceType` (string)
    Type of the resource (e.g., User).

  - `meta.location` (string)
    URL of the user resource.

  - `userName` (string)
    Unique username for the user.

  - `name` (object)

  - `name.formatted` (string)
    Formatted full name.

  - `name.familyName` (string)
    User's last name.

  - `name.givenName` (string)
    User's first name.

  - `displayName` (string)
    Display name of the user.

  - `preferredLanguage` (string)
    User's preferred language.

  - `locale` (string)
    User's locale.

  - `active` (boolean)
    Indicates whether the user is active.

  - `emails` (array)

  - `emails.value` (string)
    Email address.

  - `emails.display` (string)
    Display version of the email.

  - `emails.type` (string)
    Type of email (e.g., work, personal).

  - `emails.primary` (boolean)
    Indicates if this is the primary email.

  - `roles` (array)

  - `roles.value` (string)
    Role value (e.g., ADMIN).

  - `roles.display` (string)
    Display version of the role.

  - `urn:zuora:scim:schemas:1.0:UserExtension` (object)

  - `urn:zuora:scim:schemas:1.0:UserExtension.organizationId` (string)
    Identifier for the associated organization.

  - `urn:zuora:scim:schemas:1.0:UserExtension.status` (string)
    Current status of the user.

  - `urn:zuora:scim:schemas:1.0:UserExtension.ssoEnabled` (boolean)
    Indicates if SSO is enabled for the user.

  - `urn:zuora:scim:schemas:1.0:UserExtension.region` (string)
    Region associated with the user.

## Response 201 fields (application/json):

  - `schemas` (array)
    A list of schema URNs that apply to the user resource. This typically includes SCIM schema definitions and any custom schemas used.
    Example: ["urn:zuora:scim:schemas:1.0:UserExtension","urn:ietf:params:scim:schemas:core:2.0:User"]

  - `id` (string)
    A unique identifier for the user resource. Assigned by the server upon creation.
    Example: "eb48a32d-2fe6-48d1-8a18-797919f3810a"

  - `meta` (object)
    Example: {"created":"2023-07-13T06:15:25.836Z","resourceType":"User","location":"http://localhost:9900/scim/v2/Users/eb48a32d-2fe6-48d1-8a18-797919f3810a"}

  - `meta.created` (string)
    The timestamp when the user resource was created. Provides information about the creation time of the resource.
    Example: "2023-07-13T06:15:25.836Z"

  - `meta.resourceType` (string)
    The type of resource, in this case, it will be 'User'. Helps identify the type of the resource.
    Example: "User"

  - `meta.location` (string)
    The URL to access the newly created user resource. Provides the URI of the user resource for future references or operations.
    Example: "http://localhost:9900/scim/v2/Users/eb48a32d-2fe6-48d1-8a18-797919f3810a"

  - `userName` (string)
    The username for the user. Typically used for login and unique identification of the user within the system.
    Example: "Amy+555"

  - `name` (object)
    Example: {"formatted":"Amy Lawrence","familyName":"Lawrence","givenName":"Amy"}

  - `name.formatted` (string)
    The full name of the user as a single formatted string. Useful for display purposes.
    Example: "Amy Lawrence"

  - `name.familyName` (string)
    The family name (surname) of the user. Used for sorting and identifying users.
    Example: "Lawrence"

  - `name.givenName` (string)
    The given name (first name) of the user. Helps in personalizing interactions and communications.
    Example: "Amy"

  - `displayName` (string)
    A display name for the user, typically used in user interfaces or directories. It may combine various name attributes for better presentation.
    Example: "Amy Lawrence"

  - `preferredLanguage` (string)
    The preferred language of the user for communication. This helps in providing content in the user's chosen language.
    Example: "en"

  - `locale` (string)
    The locale or region of the user, often used to format dates, times, and numbers according to regional preferences.
    Example: "en-US"

  - `active` (boolean)
    Indicates whether the user account is active. If false, the user is considered inactive or disabled.
    Example: true

  - `emails` (array)
    Example: [{"value":"asmurugesan+555@zuora.com","display":"asmurugesan+555@zuora.com","type":"work","primary":true}]

  - `emails.value` (string)
    The email address of the user. Used for communication and login purposes.

  - `emails.display` (string)
    A human-readable email address, often the same as value, but can be formatted differently.

  - `emails.type` (string)
    The type of email address (e.g., work, home). Helps categorize different types of email addresses.

  - `emails.primary` (boolean)
    Indicates whether this email address is the primary one for the user. Useful for identifying the main contact address.

  - `groups` (array)
    Example: [{"value":"7f5c248e-44e8-48d3-bacc-b5bd1253c2e4","display":""}]

  - `groups.value` (string)
    The unique identifier of a group to which the user belongs. Useful for group-based permissions and organization.

  - `groups.display` (string)
    The display name of the group. Provides a human-readable name for the group.

  - `roles` (array)
    Example: [{"value":"USER","display":"USER"}]

  - `roles.value` (string)
    The role assigned to the user. Represents the user's role within the system (e.g., admin, user).

  - `roles.display` (string)
    The display name of the role. Provides a human-readable label for the user's role.

  - `urn:zuora:scim:schemas:1.0:UserExtension` (object)
    Example: {"schemas":["urn:zuora:scim:schemas:1.0:UserExtension"],"organizationId":"rc141dc2-901e-4813-a25d-ef480cff1e26","status":"ACTIVE","ssoEnabled":false,"region":"EU"}

  - `urn:zuora:scim:schemas:1.0:UserExtension.schemas` (array)
    A list of schema URNs specific to the user extension. Defines additional properties or custom attributes for the user resource.
    Example: ["urn:zuora:scim:schemas:1.0:UserExtension"]

  - `urn:zuora:scim:schemas:1.0:UserExtension.organizationId` (string)
    The unique identifier for the organization to which the user belongs. Useful for organizational management and reporting.
    Example: "rc141dc2-901e-4813-a25d-ef480cff1e26"

  - `urn:zuora:scim:schemas:1.0:UserExtension.status` (string)
    The current status of the user account (e.g., ACTIVE, PENDING_ACTIVATION). Helps in tracking the user’s state.
    Example: "ACTIVE"

  - `urn:zuora:scim:schemas:1.0:UserExtension.ssoEnabled` (boolean)
    Indicates whether Single Sign-On (SSO) is enabled for the user. Useful for authentication and access management.

  - `urn:zuora:scim:schemas:1.0:UserExtension.region` (string)
    The geographical region of the user. Helps in regional data management and compliance.
    Example: "EU"

## Response 401 fields (application/json):

  - `success` (boolean)
    Indicates whether the request was successful. For a 401 error, this will always be false.

  - `reasons` (array)
    Example: [{"message":"Unauthorized","code":"90000011"}]

  - `reasons.message` (string)
    A message describing the reason for the unauthorized error. Provides more context about the failure.
    Example: "Unauthorized"

  - `reasons.code` (string)
    An application-specific error code that provides additional details about the unauthorized error.
    Example: "90000011"

## Response 403 fields (application/json):

  - `timestamp` (string)
    The timestamp when the error occurred. Useful for debugging and tracking when the error happened.
    Example: "2023-07-28T10:47:07.931+00:00"

  - `status` (integer)
    The HTTP status code representing the error. For forbidden errors, this will always be 403.
    Example: 403

  - `error` (string)
    A brief description of the error type. In this case, it indicates a 'Forbidden' error.
    Example: "Forbidden"

  - `message` (string)
    A message providing more details about the specific error that occurred. Describes why access was denied.
    Example: "Admin access denied"

  - `path` (string)
    The URI path of the resource that caused the error. Helps in identifying which resource or endpoint triggered the error.
    Example: "/scim/v2/Users"

## Response 404 fields (application/json):

  - `schemas` (array)
    A list of schema URNs that are relevant to the error response. Usually includes a standard error schema.
    Example: ["urn:ietf:params:scim:api:messages:2.0:Error"]

  - `status` (string)
    The HTTP status code representing the error. For not found errors, this will always be '404'.
    Example: "404"

  - `detail` (string)
    A message providing details about the resource that was not found. Helps in understanding what was missing or incorrectly requested.
    Example: "Resource not found"