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.

HTTP Method	URL
POST	https://api.opsgenie.com/v2/users

JSON Body Fields

Fields	Mandatory	Description	Limit
username	true	E-mail address of the user	100 chars
fullName	true	Name of the user	512 chars
role	true	Role of user. It may be one of admin, user or the name of a custom role you've created.
skypeUsername	false	Skype username of the user
userAddress	false	Address of the user
tags	false	List 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.
details	false	Set of user defined properties.
timezone	false	Timezone 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 and time zones document.
locale	false	Location information of the user. If not set, locale of the customer will be used instead. Please look at Supported Locale IDs for available locales.
invitationDisabled	false	Invitation 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'
		-H "Content-Type: application/json"
    --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

HTTP Method	URL
GET	https://api.opsgenie.com/v2/users/:identifier

In-Line Parameters

Referred Name	Description
identifier	Username or id of the user

Query Parameters

Parameter	Mandatory	Description
expand	false	Comma 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.

📘
If you have integrated your Opsgenie account with Atlassian Accounts, you can no longer perform an update via API calls.

HTTP Method	URL
PATCH	https://api.opsgenie.com/v2/users/:identifier

In-Line Parameters

Referred Name	Description
identifier	Identifier of the user

JSON Body Fields

Fields	Mandatory	Description	Limit
username	false	Login 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
fullName	false	Name of the user	512 chars
role	false	Role of user. It may be one of Admin, User or the name of a custom role you've created.	10000 chars
skypeUsername	false	Skype username of the user
userAddress	false	Address of the user
tags	false	list 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.
details	false	Set of user defined properties.
timezone	false	Timezone 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 and time zones document.
locale	false	Location 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.

HTTP Method	URL
DELETE	https://api.opsgenie.com/v2/users/:identifier

In-Line Parameters

Referred Name	Description
identifier	Username 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:

HTTP Method	URL
GET	https://api.opsgenie.com/v2/users

Query Parameters

Parameter	Mandatory	Description	Default
limit	false	Number of users to retrieve	100
offset	false	Number of users to skip from start	0
sort	false	Field to use in sorting. Should be one of username, fullName and createdAt	username
order	false	Direction of sorting. Should be one of asc or desc	asc
query	false	Field: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.

HTTP Method	URL
GET	https://api.opsgenie.com/v2/users/:identifier/escalations

In-Line Parameters

Referred Name	Description
identifier	Username 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.

HTTP Method	URL
GET	https://api.opsgenie.com/v2/users/:identifier/teams

In-Line Parameters

Referred Name	Description
identifier	Username 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.

HTTP Method	URL
GET	https://api.opsgenie.com/v2/users/:identifier/forwarding-rules

In-Line Parameters

Referred Name	Description
identifier	Username 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.

HTTP Method	URL
GET	https://api.opsgenie.com/v2/users/:identifier/schedules

In-Line Parameters

Referred Name	Description
identifier	Username 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

HTTP Method	URL
GET	https://api.opsgenie.com/v2/users/saved-searches/:identifier

In-Line Parameters

Referred Name	Description
identifier	Identifier of the saved search

Query Parameters

Parameter	Mandatory	Description
identifierType	false	Type 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

HTTP Method	URL
GET	https://api.opsgenie.com/v2/users/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

HTTP Method	URL
DELETE	https://api.opsgenie.com/v1/incidents/saved-searches/:identifier

In-Line Parameters

Referred Name	Description
identifier	Identifier of the saved search

Query Parameters

Paremeter	Mandatory	Description
identifierType	false	Type 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"
}