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 -L -X POST'https://myorg.omniapp.co/api/scim/v2/users' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
    "displayName": "Blobby",
    "userName": "iamagoodblob@myorg.co",
    "urn:omni:params:1.0:UserAttribute": {
        "good_blob": "yes"
    }
}'

Parameters

Parameter	Type	Required	Default	Description
displayName	string	Yes ✓	n/a	The user's display name. For example, `Blobby`.
userName	string	Yes ✓	n/a	The user's email address.
urn:omni:params:1.0:UserAttribute	object	No X	n/a	An 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.

Response

201 Created

Successful requests will return a 201 Created status and a response body similar to the following:

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"
    }
}

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

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 -L -X PUT 'https://myorg.omniapp.co/api/scim/v2/users/9e8719d9-276a-4964-9395-a493189a247c' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
    "urn:omni:params:1.0:UserAttribute": {
        "good_blob": "sometimes"
    }

Parameters

Parameter	Type	Required	Default	Description
id	URL parameter	Yes ✓	n/a	The ID of the user to be updated.
displayName	string	No X	n/a	The user's display name. For example, `Blobby`.
userName	string	Yes ✓	n/a	The user's email address. It must match the user's existing email address and cannot be changed.
urn:omni:params:1.0:UserAttribute	object	No X	n/a	An 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.

Response

200 OK

Successful requests will return a 200 OK status and a response body containing 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"
}

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

List users

Returns a list of users, sorted by creation time. This endpoint supports filtering.

Use the List embed users endpoint to retrieve embed users.

Basic request
Filters

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

GET /scim/v2/users?filter=userName eq ':userName'
curl -L 'https://myorg.omniapp.co/api/scim/v2/users?filter=userName eq "iamagoodblob@blobsrus.co' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Parameters

Note: All parameters must be provided as query parameters.

Parameter Type Required Default Description

Parameter	Type	Required	Default	Description
filter	string	No X	n/a	Filter to return a specific user using `userName` field. The filter should be provided in the following format: `<userName> eq "<userId>` For example: `userName eq "iamagoodblob@blobsrus.co"`
count	integer	No X	100	The number of users to return. Defaults to `100`.
startIndex	integer	No X	1	An integer index that determines the starting point of the sorted result list. Defaults to `1`.

filter

string

No X

n/a

Filter to return a specific user using userName field. The filter should be provided in the following format: <userName> eq "<userId>

For example: userName eq "iamagoodblob@blobsrus.co"

count

integer

No X

100

The number of users to return. Defaults to 100.

startIndex

integer

No X

An integer index that determines the starting point of the sorted result list. Defaults to 1.

Response

200 OK

Successful requests will return a 200 OK status and a response body containing 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
}

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

List embed users

Returns a list of embed users, sorted by creation time. This endpoint supports filtering.

Use the List users endpoint to retrieve standard users.

Basic request
Filter by embed ID
Filter by username

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

GET /scim/v2/embed/users?filter=embedExternalId eq ':embedExternalId'
curl -L 'https://myorg.omniapp.co/api/scim/v2/embed/users?filter=embedExternalId eq "102' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

GET /scim/v2/embed/users?filter=userName eq ':userName'
curl -L 'https://myorg.omniapp.co/api/scim/v2/embed/users?filter=userName eq "embed-user-i_4TrNwyVTu34bZaC35VJVD3-pknp4YF7V8_Bi4TMdw@myorg.embed-exploreomni.co' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Parameters

Note: All parameters must be provided as query parameters.

Parameter Type Required Default Description

Parameter	Type	Required	Default	Description
filter	string	No X	n/a	Filter to return a specific user using either the `userName` and `embedExternalId` fields. The filter should be provided in the following format: `<fieldName> eq "<userId>` For example: `userName eq "iamagoodblob@blobsrus.co"` or `embedExternalId eq "102"`
count	integer	No X	100	The number of users to return. Defaults to `100`.
startIndex	integer	No X	1	An integer index that determines the starting point of the sorted result list. Defaults to `1`.

filter

string

No X

n/a

Filter to return a specific user using either the userName and embedExternalId fields. The filter should be provided in the following format: <fieldName> eq "<userId>

For example: userName eq "iamagoodblob@blobsrus.co" or embedExternalId eq "102"

count

integer

No X

100

The number of users to return. Defaults to 100.

startIndex

integer

No X

An integer index that determines the starting point of the sorted result list. Defaults to 1.

Response

200 OK

Successful requests will return a 200 OK status and a response body containing a list of user objects, each of which represents a user.

200 OK
{
    "Resources": [
        {
            "active": true,
            "displayName": "Blobby",
            "emails": [
                {
                    "primary": true,
                    "value": "embed-user-i_4TrNwyVTu34bZaC35VJVD3-pknp4YF7V8_Bi4TMdw@myorg.embed-exploreomni.co"
                }
            ],
            "groups": [
                {
                    "display": "All Embed Users",
                    "value": "4GcvQ2D9"
                },
                {
                    "display": "Omni",
                    "value": "nqGuU_uh"
                }
            ],
            "id": "2212aecf-a2ba-4d99-b23b-f615bc4c6522",
            "meta": {
                "created": "2024-09-30T20:25:01.822Z",
                "lastModified": "2024-09-30T20:51:47.558Z",
                "resourceType": "User"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "userName": "embed-user-i_4TrNwyVTu34bZaC35VJVD3-pknp4YF7V8_Bi4TMdw@myorg.embed-exploreomni.co",
            "embedEmail": null,
            "embedEntity": "omni",
            "embedExternalId": "blobby-manager"
        }
    ],
    "itemsPerPage": 1,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "startIndex": 1,
    "totalResults": 1
}

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Retrieve a user

Retrieves a user using their unique ID.

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

Parameters

Parameter	Type	Required	Default	Description
id	URL parameter	Yes ✓	n/a	The ID of the user to be retrieved.

Response

200 OK

Successful requests will return a 200 OK status and a response body containing 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"
    }
}

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Delete a user

Deletes the specified user. Use the Delete an embed user endpoint to delete embed users.

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

Parameters

Parameter	Type	Required	Default	Description
userId	URL parameter	Yes ✓	n/a	The ID of the user to be deleted.

Response

204 No Content

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

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Delete an embed user

Deletes the specified embed user. Use the Delete a user endpoint to delete standard users.

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

Parameters

Parameter	Type	Required	Default	Description
userId	URL parameter	Yes ✓	n/a	The ID of the embed user to be deleted.

Response

204 No Content

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

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Create a user​

Parameters​

Response​

Update a user​

Parameters​

Response​

List users​

Parameters​

Response​

List embed users​

Parameters​

Response​

Retrieve a user​

Parameters​

Response​

Delete a user​

Parameters​

Response​

Delete an embed user​

Parameters​

Response​

Create a user

Parameters

Response

Update a user

Parameters

Response

List users

Parameters

Response

List embed users

Parameters

Response

Retrieve a user

Parameters

Response

Delete a user

Parameters

Response

Delete an embed user

Parameters

Response