Retrieve all access requests [GET]

This endpoint allows you to retrieve a list of all recent access requests.

Request

1
GET https://api.sendgrid.com/v3/scopes/requests HTTP/1.1
URI Parameter Required Requirements Description
limit No Some integer Optional field to limit the number of results returned.
offset No Some integer Optional beginning point in the list to retrieve from.

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
HTTP/1.1 200
[
  {
    "id": 1,
    "scope_group_name": "Mail Settings",
    "username": "teammate1",
    "email": "teammate1@example.com",
    "first_name": "Teammate",
    "last_name": "One"
  },
  {
    "id": 2,
    "scope_group_name": "Stats",
    "username": "teammate2",
    "email": "teammate2@example.com",
    "first_name": "Teammate",
    "last_name": "Two"
  }
]

Deny an access request [DELETE]

This endpoint allows you to deny an attempt to access your account.

Request

1
DELETE https://api.sendgrid.com/v3/scopes/requests/{request_id} HTTP/1.1
URI Parameter Required Requirements Description
request_id yes String The ID of the request that you want to deny.

Response

1
HTTP/1.1 204

Approve an access request [PATCH]

This endpoint allows you to approve an access attempt.

Note: Only teammate admins can call this endpoint to approve another teammate’s access request.

Request

1
PATCH https://api.sendgrid.com/v3/scopes/requests/approve/{id} HTTP/1.1
URI Parameter Required Requirements Description
id yes String The ID of the request that you want to approve.

Response

1
2
3
4
HTTP/1.1 201
{
  "id": 10
}

Resend a teammate invite [POST]

This endpoint allows you to resend a teammate invite.

Note: Teammate invitations will expire after 7 days. Resending an invite will reset the expiration date.

Request

1
POST https://api.sendgrid.com/v3/teammates/pending/{token}/resend HTTP/1.1
URI Parameter Required Requirements Description
token yes String The token for the invite that you want to resend.

Response

1
2
3
4
5
6
7
8
9
10
HTTP/1.1 200
{
  "pending_id": "abc123abc",
  "email": "teammate1@example.com",
  "scopes": [
    "user.profile.read",
    "user.profile.update"
  ],
  "is_admin": false
}

Retrieve a list of all pending teammates [GET]

This endpoint allows you to retrieve a list of all pending teammate invitations.

Note: Each teammate invitation is valid for 7 days. Users may resend the invite to refresh the expiration date.

Request

1
GET https://api.sendgrid.com/v3/teammates/pending HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
HTTP/1.1 200
{
  "result": [
    {
      "email": "user1@example.com",
      "scopes": [
        "user.profile.read",
        "user.profile.edit"
      ],
      "is_admin": false,
      "pending_id": "abcd123abc",
      "expiration_date": 1456424263
    },
    {
      "email": "user2@example.com",
      "scopes": [],
      "is_admin": true,
      "pending_id": "bcde234bcd",
      "expiration_date": 1456424263
    }
  ]
}

Delete a pending teammate invite [DELETE]

This endpoint allows you to delete a pending teammate invite.

Request

1
DELETE https://api.sendgrid.com/v3/teammates/pending/{token} HTTP/1.1
URI Parameter Required Requirements Description
token yes String The token for the invite that you want to delete.

Response

1
HTTP/1.1 204

Invite a teammate [POST]

This endpoint allows you to send a teammate invitation via email with a predefined set of scopes, or permissions. A teammate invite will expire after 7 days, but you may resend the invite at any time to reset the expiration date. Essentials, Legacy Lite, and Free Trial users may create up to one teammate per account. There is not a teammate limit for Pro and higher plans.

Request

1
POST https://api.sendgrid.com/v3/teammates HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
{
  "email": "teammate1@example.com",
  "scopes": [
    "user.profile.read",
    "user.profile.update"
  ],
  "is_admin": false
}

Response

1
2
3
4
5
6
7
8
9
10
HTTP/1.1 201
{
  "pending_id": "abc123abc",
  "email": "teammate1@example.com",
  "scopes": [
    "user.profile.read",
    "user.profile.update"
  ],
  "is_admin": false
}

Retrieve a list of all teammates [GET]

This endpoint allows you to retrieve a list of all current teammates.

Each account may have no more than 1,000 teammates.

Request

1
GET https://api.sendgrid.com/v3/teammates HTTP/1.1
URI Parameter Required Requirements Description
limit No Some integer Optional field to limit the number of results returned.
offset No Some integer Optional beginning point in the list to retrieve from.

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
HTTP/1.1 200
{
  "results": [
    {
      "username": "teammate1",
      "email": "teammate1@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "user_type": "owner",
      "is_admin": true,
      "phone": "123-345-3453",
      "website": "www.example.com",
      "company": "ACME Inc.",
      "address": "123 Acme St",
      "address2": "",
      "city": "City",
      "state": "CA",
      "country": "USA",
      "zip": "12345"
    },
    {
      "username": "teammate2",
      "email": "teammate2@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "user_type": "teammate",
      "is_admin": false,
      "phone": "123-345-3453",
      "website": "www.example.com",
      "company": "ACME Inc.",
      "address": "123 Acme St",
      "address2": "",
      "city": "City",
      "state": "CA",
      "country": "USA",
      "zip": "12345"
    },
    {
      "username": "teammate3",
      "email": "teammate3@example.com",
      "first_name": "Steve",
      "last_name": "Doe",
      "user_type": "admin",
      "is_admin": true,
      "phone": "123-345-3453",
      "website": "www.example.com",
      "company": "ACME Inc.",
      "address": "123 Acme St",
      "address2": "",
      "city": "City",
      "state": "CA",
      "country": "USA",
      "zip": "12345"
    }
  ]
}

Retrieve a specific teammate [GET]

This endpoint allows you to retrieve a specific teammate by username.

Request

1
GET https://api.sendgrid.com/v3/teammates/{username} HTTP/1.1
URI Parameter Required Requirements Description
username Yes String The username of the teammate that you want to retrieve.

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
HTTP/1.1 200
{
  "username": "teammate1",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "teammate1@example.com",
  "scopes": [
    "user.profile.read",
    "user.profile.update",
    "..."
  ],
  "user_type": "admin",
  "is_admin": true,
  "phone": "123-345-3453",
  "website": "www.example.com",
  "company": "ACME Inc.",
  "address": "123 Acme St",
  "address2": "",
  "city": "City",
  "state": "CA",
  "country": "USA",
  "zip": "12345"
}

Update teammate’s permissions [PATCH]

This endpoint allows you to update a teammate’s permissions.

To turn a teammate into an admin, the request body should contain an is_admin set to true. Otherwise, set is_admin to false and pass in all the scopes that a teammate should have.

Only the parent user or other admin teammates can update another teammate’s permissions.

Admin users can only update permissions.

Request

1
PATCH https://api.sendgrid.com/v3/teammates/{username} HTTP/1.1
Request Body
1
2
3
4
5
6
7
{
  "scopes": [
    "user.profile.read",
    "user.profile.edit"
  ],
  "is_admin": false
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
HTTP/1.1 200
{
  "username": "teammate1",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "teammate1@example.com",
  "scopes": [
    "user.profile.read",
    "user.profile.edit"
  ],
  "user_type": "teammate",
  "is_admin": false,
  "phone": "123-345-3453",
  "website": "www.example.com",
  "company": "ACME Inc.",
  "address": "123 Acme St",
  "address2": "",
  "city": "City",
  "state": "CA",
  "country": "USA",
  "zip": "12345"
}

Delete a teammate [DELETE]

This endpoint allows you to delete a teammate.

Only the parent user or an admin teammate can delete another teammate.

Request

1
DELETE https://api.sendgrid.com/v3/teammates/{username} HTTP/1.1

Response

1
HTTP/1.1 204