Guides
Log InStart Free Trial
Start typing to search…

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

Updated 14 days ago