Content Management API > Invitation

Invite a new user

Sends an invitation email to the given address. Invitation emails are capped per day for each project owner: the cap is shared by all the projects of the owner and by all the API tokens, and it counts both new and resent invitations. Past the cap the API answers 429 RATE_LIMIT_EXCEEDED, and the X-RateLimit-Reset header tells how many seconds are left before new invitations can be sent.

Body parameters

type string Required

Must be exactly "site_invitation".

attributes.email string Required

Example:

"mark.smith@example.com"

relationships.role.data Required

Role

Type: ResourceLinkage<"role">

Returns

Returns a resource object of type site_invitation.

Examples

1
POST https://site-api.datocms.com/site-invitations HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3
5
Content-Type: application/vnd.api+json
6

7
{
8
  "data": {
9
    "type": "site_invitation",
10
    "attributes": {
11
      "email": "mark.smith@example.com"
12
    },
13
    "relationships": {
14
      "role": {
15
        "data": {
16
          "type": "role",
17
          "id": "34"
18
        }
19
      }
20
    }
21
  }
22
}

1
curl -g 'https://site-api.datocms.com/site-invitations' \
2
  -X POST \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3" \
6
  -H "Content-Type: application/vnd.api+json" \
7
  --data-binary '{"data":{"type":"site_invitation","attributes":{"email":"mark.smith@example.com"},"relationships":{"role":{"data":{"type":"role","id":"34"}}}}}'

1
await fetch("https://site-api.datocms.com/site-invitations", {
2
  method: "POST",
3
  headers: {
4
    Authorization: "Bearer YOUR-API-TOKEN",
5
    Accept: "application/json",
6
    "X-Api-Version": "3",
7
    "Content-Type": "application/vnd.api+json",
8
  },
9
  body: JSON.stringify({
10
    data: {
11
      type: "site_invitation",
12
      attributes: { email: "mark.smith@example.com" },
13
      relationships: { role: { data: { type: "role", id: "34" } } },
14
    },
15
  }),
16
});

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "data": {
9
    "type": "site_invitation",
10
    "id": "312",
11
    "attributes": {
12
      "email": "mark.smith@example.com",
13
      "expired": "mark.smith@example.com"
14
    },
15
    "relationships": {
16
      "role": {
17
        "data": {
18
          "type": "role",
19
          "id": "34"
20
        }
21
      }
22
    }
23
  }
24
}