User API

🚧

If using the EU instance of Opsgenie, the URL needs to be https://api.eu.opsgenie.com for requests to be successful.

General Information

Domains

📘

Create an API Integration and obtain your apiKey to make requests listed above. Please make sure that the integration is not restricted to access configurations.

Create User

Create user request is used to add new users in Opsgenie and it is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management.

JSON Body Fields

FieldsMandatoryDescriptionLimit
usernametrueE-mail address of the user100 chars
fullNametrueName of the user512 chars
roletrueRole of user. It may be one of owner, admin, user or the name of a custom role you've created.
skypeUsernamefalseSkype username of the user
userAddressfalseAddress of the user
tagsfalseList of labels attached to the user. You can label users to differentiate them from the rest. For example, you can add ITManager tag to differentiate people with this role from others.
detailsfalseSet of user defined properties.
timezonefalseTimezone of the user. If not set, timezone of the customer will be used instead. You can refer to Supported Timezone IDs. More information about timezones can be found in Time Constraints document
localefalseLocation information of the user. If not set, locale of the customer will be used instead. Please look at Supported Locale IDs for available locales.
invitationDisabledfalseInvitation email will not be sent if set to true. Default value is false

userAddress field example:

"userAddress": {
    "country": "US",
    "state": "Indiana",
    "city": "Terre Haute",
    "line": "567 Stratford Park",
    "zipCode": "47802"
}

details field example:

"details": {
    "detail1key": [
        "detail1dvalue1",
        "detail1value2"
    ],
    "detail2key": [
        "detail2value"
    ]
}

tags field example:

"tags": [
    "tag1",
    "tag3"
]

Sample Requests

curl -X POST  'https://api.opsgenie.com/v2/users'
    --header 'Authorization: GenieKey eb24brsfaa2-4ba2-a551q-1brsf565c889'
    --data
'{
    "username": "[email protected]",
    "fullName": "john doe",
    "skypeUsername":"doejohn",
    "role": {
        "name": "Admin"
    },
    "timeZone": "UTC-5",
    "locale": "en_US",
    "userAddress": {
        "country": "US",
        "state": "Indiana",
        "city": "Terre Haute",
        "line": "567 Stratford Park",
        "zipCode": "47802"
    },
    "details": {
        "detail1Key": [ "detail1dValue1","detail1Value2" ],
        "detail2Key": [ "detail2Value" ]
    },
    "tags":["tag1","tag3"]
}'

Response:

{
    "result": "Created",
    "data": {
       "id": "415ec30e-80ce-4219-b16e-0d4e5dc50f0a",
        "name": "[email protected]"
    },
    "took": 1.141,
    "requestId": "5469f0c6-dc71-4bf0-a417-d3792dda3417"
}

Get User

Get user request is used to retrieve a single user

In-Line Parameters

Referred NameDescription
identifierUsername or id of the user

Query Parameters

ParameterMandatoryDescription
expandfalseComma separated list of strings to create a more detailed response. The only expandable field for user api is contact

Sample Request

curl -X GET  'https://api.opsgenie.com/v2/users/[email protected]?expand=contact'
    --header 'Authorization: GenieKey eb24brsfaa2-4ba2-a551q-1brsf565c889'

Sample Request

curl -X GET  'https://api.opsgenie.com/v2/users/f4df67fe-15cb-4c88-ad9c-a1a83a785fe6?expand=contact'
    --header 'Authorization: GenieKey eb24brsfaa2-4ba2-a551q-1brsf565c889'

Response

{
    "data": {
        "blocked": false,
        "verified": false,
        "id": "f4df67fe-15cb-4c88-ad9c-a1a83a785fe6",
        "username": "[email protected]",
        "fullName": "john doe",
        "role": {
            "id": "Admin",
            "name": "Admin"
        },
        "skypeUsername": "doejohn",
        "timeZone": "GMT",
        "locale": "en_US",
        "tags": [ "tag1", "tag3" ],
        "userAddress": {
            "country": "US",
            "state": "Indiana",
            "city": "Terre Haute",
            "line": "567 Stratford Park",
            "zipCode": "47802"
        },
        "details": {
            "detail1key": ["detail1dvalue1", "detail1value2"],
            "detail2key": ["detail2value"]
        },
        "createdAt": "2017-05-23T08:38:28.17Z",
        "userContacts": [
            {
                "to": "[email protected]",
                "id": "d8431b13-aed2-4d71-90d4-cd603d4ddcf6",
                "contactMethod": "email",
                "enabled": true
            }
        ],
    },
    "expandable": ["contact"],
    "took": 0.027,
    "requestId": "8d210527-445f-4756-9a31-8dce227cf10b"
}

Update User (Partial)

Update user request is used to update users in partial manner and it is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management.

In-Line Parameters

Referred NameDescription
identifierIdentifier of the user

JSON Body Fields

FieldsMandatoryDescriptionLimit
usernamefalseLogin e-mail address of the user. If the given username is different than the current username, a verification e-mail will be sent to the given e-mail address.100 chars
fullNamefalseName of the user512 chars
rolefalseRole of user. It may be one of "Owner", Admin", "User" or the name of a custom role you've created.10000 chars
skypeUsernamefalseSkype username of the user
userAddressfalseAddress of the user
tagsfalselist of labels attached to the user. You can label users to differentiate them from the rest. For example, you can add ITManager tag to differentiate people with this role from others.
detailsfalseSet of user defined properties.
timezonefalseTimezone of the user. If not set, timezone of the customer will be used instead. You can refer to Supported Timezone IDs for available timezones. More information about timezones can be found in Time Constraints and Timezones document
localefalseLocation information of the user. If not set, locale of the customer will be used instead. Please look at Supported Locale Ids for available locales.

Sample Request

curl -X PATCH 'https://api.opsgenie.com/v2/users/[email protected]'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "fullName": "Lex Luthor",
    "role": {
        "name": "admin"
    }
}'

Sample Request

curl -X PATCH 'https://api.opsgenie.com/v2/users/[email protected]'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "timeZone": "US/Arizona",
    "userAddress": {
        "city":"Phoenix",
        "state": "Arizona"
    }
}'

Response:

{
    "result": "Updated",
    "took": 1.386,
    "requestId": "c072080b-067d-4514-aec9-2491224ab58a"
}

Delete User

Delete user request is used to delete users in Opsgenie and it is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management.

In-Line Parameters

Referred NameDescription
identifierUsername or id of the user

Sample Request

curl -X DELETE 'https://api.opsgenie.com/v2/users/[email protected]'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'

Response

{
    "result": "Deleted",
    "took": 1.871,
    "requestId": "c43c2e5c-e9a5-4527-80e3-97df8d9369e2"
}

List User

List users request is used to list users in Opsgenie. It takes the following parameters:

Query Parameters

ParameterMandatoryDescriptionDefault
limitfalseNumber of users to retrieve100
offsetfalseNumber of users to skip from start0
sortfalseField to use in sorting. Should be one of username, fullName and insertedAt username
orderfalseDirection of sorting. Should be one of asc or desc asc
queryfalseField:value combinations with most of user fields to make more advanced searches. Possible fields are username, fullName blocked, verified, role, locale, timeZone, userAddress and createdAt

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/users'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/users?sort=fullName&order=desc&limit=5&offset=1'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/users?query=fullName:doe'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/users?limit=2&offset=3&order=DESC&sort=fullName&query=role:admin'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'

Response

{
    "totalCount": 8,
    "data": [
        {
            "blocked": false,
            "verified": false,
            "id": "b5b92115-bfe7-43eb-8c2a-e467f2e5ddc4",
            "username": "[email protected]",
            "fullName": "john doe",
            "role": {
                "id": "Admin",
                "name": "Admin"
            },
            "timeZone": "Europe/Kirov",
            "locale": "en_US",
            "userAddress": {
                "country": "",
                "state": "",
                "city": "",
                "line": "",
                "zipCode": ""
            },
            "createdAt": "2017-05-12T08:34:30.283Z",
        },
        {
            "blocked": false,
            "verified": false,
            "id": "e07c63f0-dd8c-4ad4-983e-4ee7dc600463",
            "username": "[email protected]",
            "fullName": "jane doe",
            "role": {
                "id": "Admin",
                "name": "Admin"
            },
            "timeZone": "Europe/Moscow",
            "locale": "en_GB",
            "tags": [ "tag1", "tag3"],
            "userAddress": {
                "country": "US",
                "state": "Indiana",
                "city": "Terre Haute",
                "line": "567 Stratford Park",
                "zipCode": "47802"
            },
            "details": {
                "detail1key": ["detail1dvalue1", "detail1value2"],
                "detail2key": ["detail2value" ]
            },
            "createdAt": "2017-05-12T09:39:14.41Z",
        }
    ],
    "paging": {
        "prev": "http://api.opsgenie.com/v2/users?limit=2&offset=1&order=DESC&sort=fullName&query=role%3Aadmin",
        "next": "http://api.opsgenie.com/v2/users?limit=2&offset=5&order=DESC&sort=fullName&query=role%3Aadmin",
        "first": "http://api.opsgenie.com/v2/users?limit=2&offset=0&order=DESC&sort=fullName&query=role%3Aadmin",
        "last": "http://api.opsgenie.com/v2/users?limit=2&offset=6&order=DESC&sort=fullName&query=role%3Aadmin"
    },
    "took": 0.261,
    "requestId": "d2c50d0c-1c44-4fa5-99d4-20d1e7ca9938"
}

List User Escalations

List user escalation request is used to list a single users escalations in Opsgenie.

In-Line Parameters

Referred NameDescription
identifierUsername or id of the user

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/users/[email protected]/escalations'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'

Response

{
    "data": [
        {
            "id": "d2cd4dd9-0f76-4c13-b379-f5d95f0c4438",
            "name": "TeamName_escalation",
            "ownerTeam": {
                "id": "6fa6848c-8cac-4cea-8a98-ad9ff23d9b16",
                "name": "TeamName"
            },
            "rules": [
                {
                    "condition": "if-not-acked",
                    "notifyType": "default",
                    "delay": {
                        "timeAmount": 0,
                        "timeUnit": "minutes"
                    },
                    "recipient": {
                        "type": "schedule",
                        "id": "f6afc4c3-0e8d-467e-85f0-03b24e2eb920",
                        "name": "TeamName_schedule"
                    }
                },
                {
                    "condition": "if-not-acked",
                    "notifyType": "next",
                    "delay": {
                        "timeAmount": 5,
                        "timeUnit": "minutes"
                    },
                    "recipient": {
                        "type": "schedule",
                        "id": "f6afc4c3-0e8d-467e-85f0-03b24e2eb920",
                        "name": "TeamName_schedule"
                    }
                },
                {
                    "condition": "if-not-acked",
                    "notifyType": "all",
                    "delay": {
                        "timeAmount": 10,
                        "timeUnit": "minutes"
                    },
                    "recipient": {
                        "type": "team",
                        "id": "6fa6848c-8cac-4cea-8a98-ad9ff23d9b16",
                        "name": "TeamName"
                    }
                }
            ]
        }
    ],
    "took": 0.078,
    "requestId": "87da839d-5925-45bd-81ca-62227565632b"
}

List User Teams

List user teams request is used to list users teams.

In-Line Parameters

Referred NameDescription
identifierUsername or id of the user

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/users/[email protected]/teams'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'

Response

{
    "data": [
        {
            "id": "6fa6848c-8cac-4cea-8a98-ad9ff23d9b16",
            "name": "TeamName"
        }
    ],
    "took": 0.023,
    "requestId": "bc40b7ad-11ee-4dcd-ae5f-6d75dbc16261"
}

List User Forwarding Rules

List user forwarding rules request is used to list users forwarding rules.

In-Line Parameters

Referred NameDescription
identifierUsername or id of the user

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/users/[email protected]/forwarding-rules'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'

Response

{
    "data": [
        {
            "fromUser": {
                "id": "3562dd54-d8b9-4bb1-b51d-7e9866e4c5a5",
                "username": "[email protected]"
            },
            "toUser": {
                "id": "54fa5e6a-1b67-4859-9cfc-2f39075f1cea",
                "username": "[email protected]"
            },
            "startDate": "2017-05-25T00:00:00Z",
            "endDate": "2017-05-27T00:00:00Z",
            "alias": "",
            "id": "f4627108-319e-4895-b0ac-354e7296d862"
        }
    ],
    "took": 0.023,
    "requestId": "33e5808f-856d-416e-a4c6-d19c4ce1f215"
}

List User Schedules

List user schedules request is used to list a single users schedules.

In-Line Parameters

Referred NameDescription
identifierUsername or id of the user

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/users/[email protected]/schedules'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'

Response

{
    "data": [
        {
            "id": "f6afc4c3-0e8d-467e-85f0-03b24e2eb920",
            "name": "TeamName_schedule",
            "enabled": true
        }
    ],
    "took": 0.076,
    "requestId": "ab95b7ac-2d5c-4d75-ae59-51a49199aa96"
}

Get Saved Search

In-Line Parameters

Referred NameDescription
identifierIdentifier of the saved search

Query Parameters

ParameterMandatoryDescription
identifierTypefalseType of the identifier that is provided as an in-line parameter. Possible values are id and name. Default value is id.

Sample Requests

curl -X GET 'https://api.opsgenie.com/v2/users/saved-searches/805a2963-c5f5-40f1-861c-02310a73966b'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'
curl -H "Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889" -X GET 'https://api.opsgenie.com/v2/users/saved-searches/default-saved-search?identifierType=name'

Sample Response

{
    "data": {
        "id": "805a2963-c5f5-40f1-861c-02310a73966b",
        "name": "default-saved-search",
        "description": "",
        "ownerId": "22b852e0-cf95-4fe6-927b-ebf221331dc6",
        "query": "john"
    },
    "took": 0.106,
    "requestId": "dd7c2771-065f-4934-a8b8-69c1e3da6f9c"
}

List Saved Searches

Sample Request

curl -H "Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889" -X GET 'https://api.opsgenie.com/v2/users/saved-searches

Sample Response

{
    "data": [
        {
            "id": "62f8c603-bd23-4450-8a65-f6dd413079ac",
            "name": "saved-search-2"
        },
        {
            "id": "805a2963-c5f5-40f1-861c-02310a73966b",
            "name": "default-saved-search"
        }
    ],
    "took": 0.118,
    "requestId": "1515aa5b-de4a-4c7b-a0c1-578b258017a6"
}

Delete Saved Search

In-Line Parameters

Referred NameDescription
identifierIdentifier of the saved search

Query Parameters

ParemeterMandatoryDescription
identifierTypefalseType of the identifier that is provided as an in-line parameter. Possible values are id and name. Default value is id.

Sample Requests

curl -H "Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889" -X DELETE 'https://api.opsgenie.com/v2/users/saved-searches/805a2963-c5f5-40f1-861c-02310a73966b

Sample Response

{
    "result": "Deleted",
    "took": 0.051,
    "requestId": "ad8a6ba8-e210-467a-b6d2-f0e70c2dc293"
}