User API

General Information

Domains


Requests

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 owner, 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 for available timezones. More information about timezones can be found in Time Constraints and Timezones 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'
    --header 'Authorization: GenieKey eb24brsfaa2-4ba2-a551q-1brsf565c889'
    --data
'{
    "username": "john.doe@opsgenie.com",
    "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": "john.doe@opsgenie.com"
    },
    "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/john.doe@opsgenie.com?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": "john.doe@opsgenie.com",
        "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": "john.doe@opsgenie.com",
                "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.

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
fullName false Name of the user 512 chars
role false Role of user. It may be one of "Owner", 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 for available timezones. More information about timezones can be found in Time Constraints and Timezones 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/john.doe@opsgenie.com'
    --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/john.doe@opsgenie.com'
    --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/john.doe@opsgenie.com'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'
Response:
{
    "result": "Deleted",
    "took": 1.871,
    "requestId": "c43c2e5c-e9a5-4527-80e3-97df8d9369e2"
}

List Users

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 insertedAt 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?sortField=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": "john.doe@opsgenie.com",
            "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": "jane.doe@opsgenie.com",
            "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/john.doe@opsgenie.com/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/john.doe@opsgenie.com/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/john.doe@opsgenie.com/forwarding-rules'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'
Response:
{
    "data": [
        {
            "fromUser": {
                "id": "3562dd54-d8b9-4bb1-b51d-7e9866e4c5a5",
                "username": "john.doe@opsgenie.com"
            },
            "toUser": {
                "id": "54fa5e6a-1b67-4859-9cfc-2f39075f1cea",
                "username": "jane.doe@opsgenie.com"
            },
            "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/john.doe@opsgenie.com/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"
}