<commit_before>---
layout: page
weight: 100
title: Teammates API
seo:
  description: Create and Manage Your Teammates
  title: Teammates API
navigation:
  show: true
---

{% anchor h2 %}
Retrieve all access requests [GET]
{% endanchor %}

{% apiv3example get GET https://api.sendgrid.com/v3/scopes/requests %}

{% parameters get %}
 {% parameter limit No 'Some integer' 'Optional field to limit the number of results returned.' %}
 {% parameter offset No 'Some integer' 'Optional beginning point in the list to retrieve from.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 200
[
  {
    "id": 1,
    "scope_group_name": "Mail Settings",
    "username": "teammate1",
    "email": "<EMAIL>",
    "first_name": "Teammate",
    "last_name": "One"
  },
  {
    "id": 2,
    "scope_group_name": "Stats",
    "username": "teammate2",
    "email": "<EMAIL>",
    "first_name": "Teammate",
    "last_name": "Two"
  }
]
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Deny an access attempt [DELETE]
{% endanchor %}

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

{% apiv3example delete DELETE https://api.sendgrid.com/v3/scopes/requests/{request_id} %}

{% parameters get %}
 {% parameter request_id yes 'String' 'The ID of the request that you want to deny.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 204
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Approve an access attempt [PATCH]
{% endanchor %}

{% apiv3example patch PATCH https://api.sendgrid.com/v3/scopes/requests/approve/{id} %}

{% parameters get %}
  {% parameter id yes "String" 'The ID of the request that you want to approve.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 201
{
  "id": 10
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Resend a teammate invite [POST]
{% endanchor %}

Teammate invitations expire after 7 days.

{% apiv3example post POST https://api.sendgrid.com/v3/teammates/pending/{token}/resend %}

{% parameters get %}
 {% parameter token yes 'String' 'The token for the invite that you want to resend.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 200
{
  "pending_id": "abc123abc",
  "email": "<EMAIL>",
  "scopes": [
    "user.profile.read",
    "user.profile.update"
  ],
  "is_admin": false
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Retrieve a list of all pending teammates [GET]
{% endanchor %}

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

{% apiv3example get GET https://api.sendgrid.com/v3/teammates/pending %}

{% v3response %}
HTTP/1.1 200
{
  "result": [
    {
      "email": "<EMAIL>",
      "scopes": [
        "user.profile.read",
        "user.profile.edit"
      ],
      "is_admin": false,
      "pending_id": "abcd123abc",
      "expiration_date": 1456424263
    },
    {
      "email": "<EMAIL>",
      "scopes": [],
      "is_admin": true,
      "pending_id": "bcde234bcd",
      "expiration_date": 1456424263
    }
  ]
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Delete a pending teammate invite
{% endanchor %}

{% apiv3example delete DELETE https://api.sendgrid.com/v3/teammates/pending/{token} %}

{% parameters get %}
 {% parameter token yes 'String' 'The token for the invite that you want to delete.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 204
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Invite a teammate [POST]
{% endanchor %}

{% apiv3example post POST https://api.sendgrid.com/v3/teammates %}

{% apiv3requestbody %}
{
  "email": "<EMAIL>",
  "scopes": [
    "user.profile.read",
    "user.profile.update"
  ],
  "is_admin": false
}
{% endapiv3requestbody %}

{% v3response %}
HTTP/1.1 201
{
  "pending_id": "abc123abc",
  "email": "<EMAIL>",
  "scopes": [
    "user.profile.read",
    "user.profile.update"
  ],
  "is_admin": false
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Retrieve a list of all teammates [GET]
{% endanchor %}

{% info %}
Each account may have no more than 1,000 teammates.
{% endinfo %}

{% apiv3example get GET https://api.sendgrid.com/v3/teammates %}

{% parameters get %}
 {% parameter limit No 'Some integer' 'Optional field to limit the number of results returned.' %}
 {% parameter offset No 'Some integer' 'Optional beginning point in the list to retrieve from.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 200
{
  "results": [
    {
      "username": "teammate1",
      "email": "<EMAIL>",
      "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": "<EMAIL>",
      "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": "<EMAIL>",
      "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"
    }
  ]
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Retrieve a specific teammate [GET]
{% endanchor %}

{% apiv3example get GET https://api.sendgrid.com/v3/teammates/{username} %}

{% parameters get %}
 {% parameter username Yes 'String' 'The username of the teammate that you want to retrieve.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 200
{
  "username": "teammate1",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "<EMAIL>",
  "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"
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Update teammate's permissions
{% endanchor %}

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. However, admin users can only update permissions.

{% apiv3example patch PATCH https://api.sendgrid.com/v3/teammates/{username} %}

{% apiv3requestbody %}
{
  "scopes": [
    "user.profile.read",
    "user.profile.edit"
  ],
  "is_admin": false
}
{% endapiv3requestbody %}

{% v3response %}
HTTP/1.1 200
{
  "username": "teammate1",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "<EMAIL>",
  "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"
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Delete a teammate
{% endanchor %}

{% info %}
Only the parent user or an admin teammate can delete another teammate.
{% endinfo %}

{% apiv3example delete DELETE https://api.sendgrid.com/v3/teammates/{username} %}

{% v3response %}
HTTP/1.1 204
{% endv3response %}<commit_msg>added endpoint descriptions to Teammates API docs<commit_after>---
layout: page
weight: 100
title: Teammates API
seo:
  description: Create and Manage Your Teammates
  title: Teammates API
navigation:
  show: true
---

{% anchor h2 %}
Retrieve all access requests [GET]
{% endanchor %}

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

{% apiv3example get GET https://api.sendgrid.com/v3/scopes/requests %}

{% parameters get %}
 {% parameter limit No 'Some integer' 'Optional field to limit the number of results returned.' %}
 {% parameter offset No 'Some integer' 'Optional beginning point in the list to retrieve from.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 200
[
  {
    "id": 1,
    "scope_group_name": "Mail Settings",
    "username": "teammate1",
    "email": "<EMAIL>",
    "first_name": "Teammate",
    "last_name": "One"
  },
  {
    "id": 2,
    "scope_group_name": "Stats",
    "username": "teammate2",
    "email": "<EMAIL>",
    "first_name": "Teammate",
    "last_name": "Two"
  }
]
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Deny an access attempt [DELETE]
{% endanchor %}

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

{% apiv3example delete DELETE https://api.sendgrid.com/v3/scopes/requests/{request_id} %}

{% parameters get %}
 {% parameter request_id yes 'String' 'The ID of the request that you want to deny.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 204
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Approve an access attempt [PATCH]
{% endanchor %}

This endpoint allows you to approve an access attempt.

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

{% apiv3example patch PATCH https://api.sendgrid.com/v3/scopes/requests/approve/{id} %}

{% parameters get %}
  {% parameter id yes "String" 'The ID of the request that you want to approve.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 201
{
  "id": 10
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Resend a teammate invite [POST]
{% endanchor %}

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.**

{% apiv3example post POST https://api.sendgrid.com/v3/teammates/pending/{token}/resend %}

{% parameters get %}
 {% parameter token yes 'String' 'The token for the invite that you want to resend.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 200
{
  "pending_id": "abc123abc",
  "email": "<EMAIL>",
  "scopes": [
    "user.profile.read",
    "user.profile.update"
  ],
  "is_admin": false
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Retrieve a list of all pending teammates [GET]
{% endanchor %}

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.**

{% apiv3example get GET https://api.sendgrid.com/v3/teammates/pending %}

{% v3response %}
HTTP/1.1 200
{
  "result": [
    {
      "email": "<EMAIL>",
      "scopes": [
        "user.profile.read",
        "user.profile.edit"
      ],
      "is_admin": false,
      "pending_id": "abcd123abc",
      "expiration_date": 1456424263
    },
    {
      "email": "<EMAIL>",
      "scopes": [],
      "is_admin": true,
      "pending_id": "bcde234bcd",
      "expiration_date": 1456424263
    }
  ]
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Delete a pending teammate invite
{% endanchor %}

This endpoint allows you to delete a pending teammate invite.

{% apiv3example delete DELETE https://api.sendgrid.com/v3/teammates/pending/{token} %}

{% parameters get %}
 {% parameter token yes 'String' 'The token for the invite that you want to delete.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 204
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Invite a teammate [POST]
{% endanchor %}

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.

{% apiv3example post POST https://api.sendgrid.com/v3/teammates %}

{% apiv3requestbody %}
{
  "email": "<EMAIL>",
  "scopes": [
    "user.profile.read",
    "user.profile.update"
  ],
  "is_admin": false
}
{% endapiv3requestbody %}

{% v3response %}
HTTP/1.1 201
{
  "pending_id": "abc123abc",
  "email": "<EMAIL>",
  "scopes": [
    "user.profile.read",
    "user.profile.update"
  ],
  "is_admin": false
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Retrieve a list of all teammates [GET]
{% endanchor %}

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

{% info %}
Each account may have no more than 1,000 teammates.
{% endinfo %}

{% apiv3example get GET https://api.sendgrid.com/v3/teammates %}

{% parameters get %}
 {% parameter limit No 'Some integer' 'Optional field to limit the number of results returned.' %}
 {% parameter offset No 'Some integer' 'Optional beginning point in the list to retrieve from.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 200
{
  "results": [
    {
      "username": "teammate1",
      "email": "<EMAIL>",
      "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": "<EMAIL>",
      "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": "<EMAIL>",
      "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"
    }
  ]
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Retrieve a specific teammate [GET]
{% endanchor %}

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

{% apiv3example get GET https://api.sendgrid.com/v3/teammates/{username} %}

{% parameters get %}
 {% parameter username Yes 'String' 'The username of the teammate that you want to retrieve.' %}
{% endparameters %}

{% v3response %}
HTTP/1.1 200
{
  "username": "teammate1",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "<EMAIL>",
  "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"
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Update teammate's permissions
{% endanchor %}

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. However, admin users can only update permissions.

{% apiv3example patch PATCH https://api.sendgrid.com/v3/teammates/{username} %}

{% apiv3requestbody %}
{
  "scopes": [
    "user.profile.read",
    "user.profile.edit"
  ],
  "is_admin": false
}
{% endapiv3requestbody %}

{% v3response %}
HTTP/1.1 200
{
  "username": "teammate1",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "<EMAIL>",
  "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"
}
{% endv3response %}

{% endapiv3example %}

*****

{% anchor h2 %}
Delete a teammate
{% endanchor %}

This endpoint allows you to delete a teammate.

{% info %}
Only the parent user or an admin teammate can delete another teammate.
{% endinfo %}

{% apiv3example delete DELETE https://api.sendgrid.com/v3/teammates/{username} %}

{% v3response %}
HTTP/1.1 204
{% endv3response %}
{'fraction_non_alphanumeric': 0.1742767925528781, 'fraction_numerical': 0.03199198727390561, 'mean_word_length': 3.3400664791613397, 'pattern_counts': {'":': 230, '<': 27, '<?xml version=': 0, '>': 27, 'https://': 22, 'lorem ipsum': 0, 'www.': 10, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1359881', 'n_tokens_mistral': 6501, 'n_tokens_neox': 5751, 'n_words': 1602}