Skip to main content

User APIs

The user APIs allow you to manage users in your Omni instance. These APIs follow the SCIM 2.0 standard.

Create a user​

Creates a user.

POST /scim/v2/users
curl 'https://myorg.omniapp.co/api/scim/v2/users' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer TOKEN' \
--data '{
    "displayName": "Blobby",
    "userName": "iamagoodblob@myorg.co",
    "urn:omni:params:1.0:UserAttribute": {
        "good_blob": "yes"
    }
}'

Parameters​

NameTypeRequiredDescription
displayNamestring✓The user's display name. For example, Blobby
userNamestring✓The user's email address.
urn:omni:params:1.0:UserAttributeobjectAn object defining the user's user attributes. Attributes are represented as key/value pairs, where the keys map to the IDs of user attributes (the Reference column in the User attributes page) defined in Omni.

Returns​

Returns a user object and user attributes, if provided.

201 Created
 {
    "active": true,
    "displayName": "Blobby",
    "emails": [
        {
            "primary": true,
            "value": "iamagoodblob@myorg.co"
        }
    ],
    "groups": [],
    "id": "9e8719d9-276a-4964-9395-a493189a247c",
    "meta": {
        "created": "2024-12-03T23:13:14.109Z",
        "lastModified": "2024-12-03T23:13:14.109Z",
        "resourceType": "User"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "iamagoodblob@myorg.co",
    "urn:omni:params:1.0:UserAttribute": {
        "good_blob": "yes"
    }
}

Update a user​

Updates the specified user by setting the values of the parameters provided and leaving all other properties of the user unchanged.

PUT /scim/v2/users/:id
curl 'https://myorg.omniapp.co/api/scim/v2/users/9e8719d9-276a-4964-9395-a493189a247c' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer TOKEN' \
--data '{
    "urn:omni:params:1.0:UserAttribute": {
        "good_blob": "sometimes"
    }

Parameters​

NameTypeRequiredDescription
idURL parameter✓The ID of the user to be updated.
displayNamestringThe user's display name. For example, Blobby
userNamestringThe user's email address. It must match the user's existing email address and cannot be changed.
urn:omni:params:1.0:UserAttributeobjectAn object defining the user's user attributes. Attributes are represented as key/value pairs, where the keys map to the IDs of user attributes (the Reference column in the User attributes page) defined in Omni.

Returns​

Returns the updated user object associated with the provided user ID.

200 OK
{
    "active": true,
    "displayName": "Blobby",
    "emails": [
        {
            "primary": true,
            "value": "iamagoodblob@myorg.co"
        }
    ],
    "groups": [],
    "id": "9e8719d9-276a-4964-9395-a493189a247c",
    "meta": {
        "created": "2024-12-03T23:13:14.109Z",
        "lastModified": "2024-12-03T23:13:14.109Z",
        "resourceType": "User"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "iamagoodblob@myorg.co",
    "urn:omni:params:1.0:UserAttribute": {
        "good_blob": "sometimes"
}

List users​

Returns a list of users, sorted by creation time. Refer to the Embed tab to view an example specific to embedding.

GET /scim/v2/users
curl 'https://myorg.omniapp.co/api/scim/v2/users' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer TOKEN'

Parameters​

NameTypeRequiredDescription
filterstringA filter of the format userName eq "bob".
countintegerThe number of users to return. Defaults to 100.
startIndexintegerAn integer index that determines the starting point of the sorted result list. Defaults to 1.

Returns​

Returns a list of user objects, each of which represents a user.

200 OK
{
    "Resources": [
        {
            "active": true,
            "displayName": "Blobby",
            "emails": [
                {
                    "primary": true,
                    "value": "iamagoodblob@myorg.co"
                }
            ],
            "groups": [],
            "id": "9e8719d9-276a-4964-9395-a493189a247c",
            "meta": {
                "created": "2024-11-04T16:01:47.015Z",
                "lastModified": "2024-11-04T16:05:45.356Z",
                "resourceType": "User"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "userName": "iamagoodblob@myorg.co"
        },
    ],
    "itemsPerPage": 1,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "startIndex": 1,
    "totalResults": 1
}

Retrieve a user​

Retrieves a user using their unique ID.

GET /scim/v2/users/:id
curl 'https://myorg.omniapp.co/api/scim/v2/users/9e8719d9-276a-4964-9395-a493189a247c' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer TOKEN'

Parameters​

NameTypeRequiredDescription
idURL parameter✓The ID of the user to be retrieved.

Returns​

Returns the user object associated with the provided user ID.

200 OK
{
    "active": true,
    "displayName": "Blobby",
    "emails": [
        {
            "primary": true,
            "value": "iamagoodblob@myorg.co"
        }
    ],
    "groups": [],
    "id": "9e8719d9-276a-4964-9395-a493189a247c",
    "meta": {
        "created": "2024-12-03T23:13:14.109Z",
        "lastModified": "2024-12-03T23:13:14.109Z",
        "resourceType": "User"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "iamagoodblob@myorg.co",
    "urn:omni:params:1.0:UserAttribute": {
        "good_blob": "yes"
    }
}

Delete a user​

Deletes the specified user. Refer to the Embed tab to view an example specific to embedding.

DELETE /scim/v2/users/:id
curl DELETE 'https://myorg.omniapp.co/api/scim/v2/users/9e8719d9-276a-4964-9395-a493189a247c' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer TOKEN'

Parameters​

NameTypeRequiredDescription
idURL parameter✓The ID of the user to be deleted.

Returns​

Successful requests will return a 204 No Content status. No response body is expected.