User Invitations

This document contains endpoints for creating, updating, retrieving, resending, accepting, declining, and revoking user invitations in DocStudio.

User invitations add people to a corporate account or selected mailboxes and define their initial permissions and roles. A single invitation can include account access and access to one or more mailboxes.

Account administrators can create, update, resend, or revoke an invitation, while invited users can retrieve, accept, or decline their invitations. For complete request and response schemas, parameter requirements, and status codes, use the Swagger UI.

Business goals

User invitation endpoints support both account administration and the invited user’s side of the onboarding process:

• Onboard corporate users: Invite a person to join a DocStudio account

• Configure initial account access: Assign account permissions and roles during invitation

• Configure initial mailbox access: Add the invited user to one or more mailboxes with the required permissions and roles

• Correct pending invitations: Change the user’s name or assigned access before the invitation is accepted

• Recover an unanswered invitation: Resend the invitation when the original invitation was not received or has not been processed

• Let users respond to invitations: Retrieve, accept, or decline available invitations

• Cancel pending access: Revoke an invitation before the user joins the account

Endpoint summary

Invitation administration

Method	Endpoint	Purpose
POST	/api/v1/user/invite	Create an invitation with account and mailbox access
PUT	/api/v1/user/invite/{id}	Update an invitation by user UUID
POST	/api/v1/permission/invite/{accountUuid}/{userUuid}/resend	Resend an account invitation
DELETE	/api/v1/permission/invite/{accountUuid}/{userUuid}	Revoke an account invitation

Invitation response

Method	Endpoint	Purpose
GET	/api/v1/user/invites	Retrieve the authenticated user’s invitations
POST	/api/v1/user/invite/accept/{inviteCode}	Accept an invitation
DELETE	/api/v1/user/invite/decline/{inviteCode}	Decline an invitation

Invitation structure and headers

All invitation operations require an API token in the Authorization header. Requests that create or update an invitation must also use Content-Type: application/json.

Authorization: Bearer {token}
Content-Type: application/json

The invitation body contains information about the invited user and the access that must be assigned. The account object defines account access, while every object in mailboxes defines access within one mailbox.

Property	Type	Description
email	string	Email address of the invited user; accepted only when creating an invitation
firstName	string	First name of the invited user
lastName	string	Last name of the invited user
account	object	Account UUID, permission IDs, and account role UUIDs
mailboxes	array of objects	Mailbox UUIDs, permission IDs, and mailbox role UUIDs

Account and mailbox access objects use the following properties:

Property	Type	Description
uuid	UUID	UUID of the account or mailbox
permissions	array of integers	Numeric IDs of individual permissions
roles	array of UUIDs	UUIDs of permission roles

Use permission IDs and role UUIDs returned by the Permission Roles endpoints. Account roles and permissions must be included in the account object, while mailbox roles and permissions must be included in the corresponding mailboxes object.

The 0 permission ID shown in Swagger is a schema example rather than a permission that should be copied into a production request. Replace it with an actual account or mailbox permission ID.

Path parameters

Parameter	Type	Required	Description
id	UUID	Yes	UUID of the invited user whose invitation must be updated
accountUuid	UUID	Yes	UUID of the account to which the user was invited
userUuid	UUID	Yes	UUID of the invited user
inviteCode	string	Yes	Invitation code returned with the invitation data

Practical example: Invite a user to an account and mailbox

A company wants to invite a new contract reviewer to its corporate account. The user must receive an account role and access to the mailbox in which incoming contracts are processed.

Create the invitation

A successful request returns 201 Created and the invited user’s UUID. Use this value as {id} when updating the invitation and as {userUuid} when resending or revoking it.

Node.js

const response = await fetch(
  "https://api.docstudio.com/api/v1/user/invite",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      account: {
        permissions: [123],
        roles: ["{accountRoleUuid}"],
        uuid: "{accountUuid}"
      },
      mailboxes: [
        {
          permissions: [456],
          roles: ["{mailboxRoleUuid}"],
          uuid: "{mailboxUuid}"
        }
      ],
      firstName: "Alex",
      lastName: "Morgan",
      email: "[e-mail]"
    })
  }
);

const body = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed: ${response.status}\n${body}`
  );
}

console.log(body);

PHP

<?php

$payload = json_encode([
    "account" => [
        "permissions" => [123],
        "roles" => [
            "{accountRoleUuid}"
        ],
        "uuid" => "{accountUuid}"
    ],
    "mailboxes" => [
        [
            "permissions" => [456],
            "roles" => [
                "{mailboxRoleUuid}"
            ],
            "uuid" => "{mailboxUuid}"
        ]
    ],
    "firstName" => "Alex",
    "lastName" => "Morgan",
    "email" => "[e-mail]"
], JSON_THROW_ON_ERROR);

$curl = curl_init(
    "https://api.docstudio.com/api/v1/user/invite"
);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        "Request failed: {$status}\n{$body}"
    );
}

echo $body;

Python

import requests

response = requests.post(
    "https://api.docstudio.com/api/v1/user/invite",
    headers={
        "Authorization": "Bearer {token}",
    },
    json={
        "account": {
            "permissions": [123],
            "roles": [
                "{accountRoleUuid}",
            ],
            "uuid": "{accountUuid}",
        },
        "mailboxes": [
            {
                "permissions": [456],
                "roles": [
                    "{mailboxRoleUuid}",
                ],
                "uuid": "{mailboxUuid}",
            }
        ],
        "firstName": "Alex",
        "lastName": "Morgan",
        "email": "[e-mail]",
    },
    timeout=30,
)

response.raise_for_status()
print(response.text)

Ruby

require "json"
require "net/http"
require "uri"

payload = {
  account: {
    permissions: [123],
    roles: [
      "{accountRoleUuid}"
    ],
    uuid: "{accountUuid}"
  },
  mailboxes: [
    {
      permissions: [456],
      roles: [
        "{mailboxRoleUuid}"
      ],
      uuid: "{mailboxUuid}"
    }
  ],
  firstName: "Alex",
  lastName: "Morgan",
  email: "[e-mail]"
}

uri = URI(
  "https://api.docstudio.com/api/v1/user/invite"
)

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Content-Type"] = "application/json"
request.body = JSON.generate(payload)

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: uri.scheme == "https"
) do |http|
  http.request(request)
end

unless response.is_a?(Net::HTTPSuccess)
  raise "Request failed: #{response.code}\n#{response.body}"
end

puts response.body

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := map[string]any{
		"account": map[string]any{
			"permissions": []int{123},
			"roles": []string{
				"{accountRoleUuid}",
			},
			"uuid": "{accountUuid}",
		},
		"mailboxes": []map[string]any{
			{
				"permissions": []int{456},
				"roles": []string{
					"{mailboxRoleUuid}",
				},
				"uuid": "{mailboxUuid}",
			},
		},
		"firstName": "Alex",
		"lastName":  "Morgan",
		"email":     "[e-mail]",
	}

	requestBody, err := json.Marshal(payload)
	if err != nil {
		panic(err)
	}

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/user/invite",
		bytes.NewReader(requestBody),
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)
	request.Header.Set(
		"Content-Type",
		"application/json",
	)

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"Request failed: %s\n%s",
			response.Status,
			body,
		))
	}

	fmt.Println(string(body))
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String payload = """
        {
          "account": {
            "permissions": [
              123
            ],
            "roles": [
              "{accountRoleUuid}"
            ],
            "uuid": "{accountUuid}"
          },
          "mailboxes": [
            {
              "permissions": [
                456
              ],
              "roles": [
                "{mailboxRoleUuid}"
              ],
              "uuid": "{mailboxUuid}"
            }
          ],
          "firstName": "Alex",
          "lastName": "Morgan",
          "email": "[e-mail]"
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/user/invite"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .POST(
            HttpRequest.BodyPublishers.ofString(payload)
        )
        .build();

    HttpResponse<String> response =
        HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

    if (response.statusCode() < 200 ||
        response.statusCode() >= 300) {
      throw new RuntimeException(
          "Request failed: " + response.statusCode()
          + "\n" + response.body()
      );
    }

    System.out.println(response.body());
  }
}

.NET

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var payload = JsonSerializer.Serialize(new
{
    account = new
    {
        permissions = new[] { 123 },
        roles = new[]
        {
            "{accountRoleUuid}"
        },
        uuid = "{accountUuid}"
    },
    mailboxes = new[]
    {
        new
        {
            permissions = new[] { 456 },
            roles = new[]
            {
                "{mailboxRoleUuid}"
            },
            uuid = "{mailboxUuid}"
        }
    },
    firstName = "Alex",
    lastName = "Morgan",
    email = "[e-mail]"
});

using var client = new HttpClient();

using var request = new HttpRequestMessage(
    HttpMethod.Post,
    "https://api.docstudio.com/api/v1/user/invite"
);

request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", "{token}");

request.Content = new StringContent(
    payload,
    Encoding.UTF8,
    "application/json"
);

using var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Request failed: {(int)response.StatusCode}\n{body}"
    );
}

Console.WriteLine(body);

cURL

curl --request POST \
  --url 'https://api.docstudio.com/api/v1/user/invite' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "account": {
      "permissions": [
        123
      ],
      "roles": [
        "{accountRoleUuid}"
      ],
      "uuid": "{accountUuid}"
    },
    "mailboxes": [
      {
        "permissions": [
          456
        ],
        "roles": [
          "{mailboxRoleUuid}"
        ],
        "uuid": "{mailboxUuid}"
      }
    ],
    "firstName": "Alex",
    "lastName": "Morgan",
    "email": "[e-mail]"
  }'

A successful request returns 201 Created and a UUID. Save the returned value because the invitation management endpoints identify the invited user by UUID.

{
  "uuid": "{userUuid}"
}

Update the invitation

Update the invitation when the user’s name, account access, or mailbox access must be changed before acceptance. The {id} path parameter contains the UUID of the invited user.

Node.js

const response = await fetch(
  "https://api.docstudio.com/api/v1/user/invite/{id}",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer {token}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      account: {
        permissions: [123, 124],
        roles: ["{accountRoleUuid}"],
        uuid: "{accountUuid}"
      },
      mailboxes: [
        {
          permissions: [456, 457],
          roles: ["{mailboxRoleUuid}"],
          uuid: "{mailboxUuid}"
        }
      ],
      firstName: "Alex",
      lastName: "Morgan"
    })
  }
);

const body = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed: ${response.status}\n${body}`
  );
}

if (body) {
  console.log(body);
}

PHP

<?php

$payload = json_encode([
    "account" => [
        "permissions" => [123, 124],
        "roles" => [
            "{accountRoleUuid}"
        ],
        "uuid" => "{accountUuid}"
    ],
    "mailboxes" => [
        [
            "permissions" => [456, 457],
            "roles" => [
                "{mailboxRoleUuid}"
            ],
            "uuid" => "{mailboxUuid}"
        ]
    ],
    "firstName" => "Alex",
    "lastName" => "Morgan"
], JSON_THROW_ON_ERROR);

$url =
    "https://api.docstudio.com/api/v1/user/invite/{id}";

$curl = curl_init($url);

curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        "Request failed: {$status}\n{$body}"
    );
}

if ($body !== "") {
    echo $body;
}

Python

import requests

response = requests.put(
    "https://api.docstudio.com/api/v1/user/invite/{id}",
    headers={
        "Authorization": "Bearer {token}",
    },
    json={
        "account": {
            "permissions": [123, 124],
            "roles": [
                "{accountRoleUuid}",
            ],
            "uuid": "{accountUuid}",
        },
        "mailboxes": [
            {
                "permissions": [456, 457],
                "roles": [
                    "{mailboxRoleUuid}",
                ],
                "uuid": "{mailboxUuid}",
            }
        ],
        "firstName": "Alex",
        "lastName": "Morgan",
    },
    timeout=30,
)

response.raise_for_status()

if response.text:
    print(response.text)

Ruby

require "json"
require "net/http"
require "uri"

payload = {
  account: {
    permissions: [123, 124],
    roles: [
      "{accountRoleUuid}"
    ],
    uuid: "{accountUuid}"
  },
  mailboxes: [
    {
      permissions: [456, 457],
      roles: [
        "{mailboxRoleUuid}"
      ],
      uuid: "{mailboxUuid}"
    }
  ],
  firstName: "Alex",
  lastName: "Morgan"
}

uri = URI(
  "https://api.docstudio.com/api/v1/user/invite/{id}"
)

request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Bearer {token}"
request["Content-Type"] = "application/json"
request.body = JSON.generate(payload)

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: uri.scheme == "https"
) do |http|
  http.request(request)
end

unless response.is_a?(Net::HTTPSuccess)
  raise "Request failed: #{response.code}\n#{response.body}"
end

puts response.body unless response.body.empty?

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := map[string]any{
		"account": map[string]any{
			"permissions": []int{123, 124},
			"roles": []string{
				"{accountRoleUuid}",
			},
			"uuid": "{accountUuid}",
		},
		"mailboxes": []map[string]any{
			{
				"permissions": []int{456, 457},
				"roles": []string{
					"{mailboxRoleUuid}",
				},
				"uuid": "{mailboxUuid}",
			},
		},
		"firstName": "Alex",
		"lastName":  "Morgan",
	}

	requestBody, err := json.Marshal(payload)
	if err != nil {
		panic(err)
	}

	request, err := http.NewRequest(
		http.MethodPut,
		"https://api.docstudio.com/api/v1/user/invite/{id}",
		bytes.NewReader(requestBody),
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)
	request.Header.Set(
		"Content-Type",
		"application/json",
	)

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"Request failed: %s\n%s",
			response.Status,
			body,
		))
	}

	if len(body) > 0 {
		fmt.Println(string(body))
	}
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String payload = """
        {
          "account": {
            "permissions": [
              123,
              124
            ],
            "roles": [
              "{accountRoleUuid}"
            ],
            "uuid": "{accountUuid}"
          },
          "mailboxes": [
            {
              "permissions": [
                456,
                457
              ],
              "roles": [
                "{mailboxRoleUuid}"
              ],
              "uuid": "{mailboxUuid}"
            }
          ],
          "firstName": "Alex",
          "lastName": "Morgan"
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/user/invite/{id}"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .PUT(
            HttpRequest.BodyPublishers.ofString(payload)
        )
        .build();

    HttpResponse<String> response =
        HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

    if (response.statusCode() < 200 ||
        response.statusCode() >= 300) {
      throw new RuntimeException(
          "Request failed: " + response.statusCode()
          + "\n" + response.body()
      );
    }

    if (!response.body().isEmpty()) {
      System.out.println(response.body());
    }
  }
}

.NET

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var payload = JsonSerializer.Serialize(new
{
    account = new
    {
        permissions = new[] { 123, 124 },
        roles = new[]
        {
            "{accountRoleUuid}"
        },
        uuid = "{accountUuid}"
    },
    mailboxes = new[]
    {
        new
        {
            permissions = new[] { 456, 457 },
            roles = new[]
            {
                "{mailboxRoleUuid}"
            },
            uuid = "{mailboxUuid}"
        }
    },
    firstName = "Alex",
    lastName = "Morgan"
});

using var client = new HttpClient();

using var request = new HttpRequestMessage(
    HttpMethod.Put,
    "https://api.docstudio.com/api/v1/user/invite/{id}"
);

request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", "{token}");

request.Content = new StringContent(
    payload,
    Encoding.UTF8,
    "application/json"
);

using var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Request failed: {(int)response.StatusCode}\n{body}"
    );
}

if (!string.IsNullOrEmpty(body))
{
    Console.WriteLine(body);
}

cURL

curl --request PUT \
  --url 'https://api.docstudio.com/api/v1/user/invite/{id}' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "account": {
      "permissions": [
        123,
        124
      ],
      "roles": [
        "{accountRoleUuid}"
      ],
      "uuid": "{accountUuid}"
    },
    "mailboxes": [
      {
        "permissions": [
          456,
          457
        ],
        "roles": [
          "{mailboxRoleUuid}"
        ],
        "uuid": "{mailboxUuid}"
      }
    ],
    "firstName": "Alex",
    "lastName": "Morgan"
  }'Frese

The update schema does not contain email, so this operation does not change the invitation email address. A successful request returns 200 OK without a response body.

Resend the invitation

Resend an invitation when the user has not received or processed the original invitation. The request identifies both the account and the invited user.

Node.js

const response = await fetch(
  "https://api.docstudio.com/api/v1/permission/" +
  "invite/{accountUuid}/{userUuid}/resend",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}"
    }
  }
);

const body = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed: ${response.status}\n${body}`
  );
}

if (body) {
  console.log(body);
}

PHP

<?php

$url =
    "https://api.docstudio.com/api/v1/permission/" .
    "invite/{accountUuid}/{userUuid}/resend";

$curl = curl_init($url);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}"
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        "Request failed: {$status}\n{$body}"
    );
}

if ($body !== "") {
    echo $body;
}

Python

import requests

response = requests.post(
    "https://api.docstudio.com/api/v1/permission/"
    "invite/{accountUuid}/{userUuid}/resend",
    headers={
        "Authorization": "Bearer {token}",
    },
    timeout=30,
)

response.raise_for_status()

if response.text:
    print(response.text)

Ruby

require "net/http"
require "uri"

uri = URI(
  "https://api.docstudio.com/api/v1/permission/" \
  "invite/{accountUuid}/{userUuid}/resend"
)

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: uri.scheme == "https"
) do |http|
  http.request(request)
end

unless response.is_a?(Net::HTTPSuccess)
  raise "Request failed: #{response.code}\n#{response.body}"
end

puts response.body unless response.body.empty?

Go

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.docstudio.com/api/v1/permission/" +
		"invite/{accountUuid}/{userUuid}/resend"

	request, err := http.NewRequest(
		http.MethodPost,
		url,
		nil,
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"Request failed: %s\n%s",
			response.Status,
			body,
		))
	}

	if len(body) > 0 {
		fmt.Println(string(body))
	}
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String url =
        "https://api.docstudio.com/api/v1/permission/"
        + "invite/{accountUuid}/{userUuid}/resend";

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .POST(
            HttpRequest.BodyPublishers.noBody()
        )
        .build();

    HttpResponse<String> response =
        HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

    if (response.statusCode() < 200 ||
        response.statusCode() >= 300) {
      throw new RuntimeException(
          "Request failed: " + response.statusCode()
          + "\n" + response.body()
      );
    }

    if (!response.body().isEmpty()) {
      System.out.println(response.body());
    }
  }
}

.NET

using System;
using System.Net.Http;
using System.Net.Http.Headers;

var url =
    "https://api.docstudio.com/api/v1/permission/" +
    "invite/{accountUuid}/{userUuid}/resend";

using var client = new HttpClient();

using var request = new HttpRequestMessage(
    HttpMethod.Post,
    url
);

request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", "{token}");

using var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Request failed: {(int)response.StatusCode}\n{body}"
    );
}

if (!string.IsNullOrEmpty(body))
{
    Console.WriteLine(body);
}

cURL

curl --request POST \
  --url 'https://api.docstudio.com/api/v1/permission/invite/{accountUuid}/{userUuid}/resend' \
  --header 'Authorization: Bearer {token}'

A successful request returns 200 OK without a response body. The existing invitation configuration remains unchanged.

Retrieve available invitations

The invited user can retrieve their invitations with pagination. The default offset is 0, the default limit is 25, and the maximum supported limit is 1000.

Node.js

const url = new URL(
  "https://api.docstudio.com/api/v1/user/invites"
);

url.searchParams.set("offset", "0");
url.searchParams.set("limit", "25");

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: "Bearer {token}"
  }
});

const body = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed: ${response.status}\n${body}`
  );
}

console.log(body);

PHP

<?php

$baseUrl =
    "https://api.docstudio.com/api/v1/user/invites";

$query = http_build_query([
    "offset" => 0,
    "limit" => 25
]);

$curl = curl_init($baseUrl . "?" . $query);

curl_setopt_array($curl, [
    CURLOPT_HTTPGET => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}"
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        "Request failed: {$status}\n{$body}"
    );
}

echo $body;

Python

import requests

response = requests.get(
    "https://api.docstudio.com/api/v1/user/invites",
    headers={
        "Authorization": "Bearer {token}",
    },
    params={
        "offset": 0,
        "limit": 25,
    },
    timeout=30,
)

response.raise_for_status()
print(response.text)

Ruby

require "net/http"
require "uri"

uri = URI(
  "https://api.docstudio.com/api/v1/user/invites"
)

uri.query = URI.encode_www_form(
  offset: 0,
  limit: 25
)

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer {token}"

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: uri.scheme == "https"
) do |http|
  http.request(request)
end

unless response.is_a?(Net::HTTPSuccess)
  raise "Request failed: #{response.code}\n#{response.body}"
end

puts response.body

Go

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	endpoint, err := url.Parse(
		"https://api.docstudio.com/api/v1/user/invites",
	)
	if err != nil {
		panic(err)
	}

	query := endpoint.Query()
	query.Set("offset", "0")
	query.Set("limit", "25")
	endpoint.RawQuery = query.Encode()

	request, err := http.NewRequest(
		http.MethodGet,
		endpoint.String(),
		nil,
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"Request failed: %s\n%s",
			response.Status,
			body,
		))
	}

	fmt.Println(string(body))
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String url =
        "https://api.docstudio.com/api/v1/user/invites"
        + "?offset=0&limit=25";

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .GET()
        .build();

    HttpResponse<String> response =
        HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

    if (response.statusCode() < 200 ||
        response.statusCode() >= 300) {
      throw new RuntimeException(
          "Request failed: " + response.statusCode()
          + "\n" + response.body()
      );
    }

    System.out.println(response.body());
  }
}

.NET

using System;
using System.Net.Http;
using System.Net.Http.Headers;

var url =
    "https://api.docstudio.com/api/v1/user/invites" +
    "?offset=0&limit=25";

using var client = new HttpClient();

using var request = new HttpRequestMessage(
    HttpMethod.Get,
    url
);

request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", "{token}");

using var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Request failed: {(int)response.StatusCode}\n{body}"
    );
}

Console.WriteLine(body);

cURL

curl --request GET \
  --url 'https://api.docstudio.com/api/v1/user/invites?offset=0&limit=25' \
  --header 'Authorization: Bearer {token}'

A successful request returns 200 OK and a paginated collection. Each item contains the account, its assigned permissions, available mailboxes, their permissions, and the invitation code.

{
  "totalElements": 1,
  "sizeRequested": 25,
  "numberOfElements": 1,
  "data": [
    {
      "uuid": "{accountUuid}",
      "name": "Example Company",
      "system": false,
      "allowMicrosoftOfficeViewer": true,
      "corporateProfileEditRestricted": false,
      "company": true,
      "mfaEnabled": false,
      "permissions": [
        123
      ],
      "mailboxes": [
        {
          "uuid": "{mailboxUuid}",
          "name": "Contract Review",
          "permissions": [
            456
          ],
          "system": false,
          "invited": true
        }
      ],
      "documentSharingProviders": [],
      "recipientExperience": {
        "language": "en",
        "locale": "en-US",
        "timezone": "Europe/Berlin"
      },
      "hideOfficialTemplates": false,
      "hideCommunityTemplates": false,
      "code": "{inviteCode}"
    }
  ]
}

Use the returned code as {inviteCode} when accepting or declining the invitation. Do not use the account UUID or user UUID in place of this value.

Accept the invitation

Accepting the invitation adds the user to the account with the account and mailbox access defined in the invitation. Use the invitation code returned by GET /api/v1/user/invites.

Node.js

const response = await fetch(
  "https://api.docstudio.com/api/v1/user/" +
  "invite/accept/{inviteCode}",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}"
    }
  }
);

const body = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed: ${response.status}\n${body}`
  );
}

if (body) {
  console.log(body);
}

PHP

<?php

$url =
    "https://api.docstudio.com/api/v1/user/" .
    "invite/accept/{inviteCode}";

$curl = curl_init($url);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}"
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        "Request failed: {$status}\n{$body}"
    );
}

if ($body !== "") {
    echo $body;
}

Python

import requests

response = requests.post(
    "https://api.docstudio.com/api/v1/user/"
    "invite/accept/{inviteCode}",
    headers={
        "Authorization": "Bearer {token}",
    },
    timeout=30,
)

response.raise_for_status()

if response.text:
    print(response.text)

Ruby

require "net/http"
require "uri"

uri = URI(
  "https://api.docstudio.com/api/v1/user/" \
  "invite/accept/{inviteCode}"
)

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: uri.scheme == "https"
) do |http|
  http.request(request)
end

unless response.is_a?(Net::HTTPSuccess)
  raise "Request failed: #{response.code}\n#{response.body}"
end

puts response.body unless response.body.empty?

Go

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.docstudio.com/api/v1/user/" +
		"invite/accept/{inviteCode}"

	request, err := http.NewRequest(
		http.MethodPost,
		url,
		nil,
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"Request failed: %s\n%s",
			response.Status,
			body,
		))
	}

	if len(body) > 0 {
		fmt.Println(string(body))
	}
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String url =
        "https://api.docstudio.com/api/v1/user/"
        + "invite/accept/{inviteCode}";

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .POST(
            HttpRequest.BodyPublishers.noBody()
        )
        .build();

    HttpResponse<String> response =
        HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

    if (response.statusCode() < 200 ||
        response.statusCode() >= 300) {
      throw new RuntimeException(
          "Request failed: " + response.statusCode()
          + "\n" + response.body()
      );
    }

    if (!response.body().isEmpty()) {
      System.out.println(response.body());
    }
  }
}

.NET

using System;
using System.Net.Http;
using System.Net.Http.Headers;

var url =
    "https://api.docstudio.com/api/v1/user/" +
    "invite/accept/{inviteCode}";

using var client = new HttpClient();

using var request = new HttpRequestMessage(
    HttpMethod.Post,
    url
);

request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", "{token}");

using var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Request failed: {(int)response.StatusCode}\n{body}"
    );
}

if (!string.IsNullOrEmpty(body))
{
    Console.WriteLine(body);
}

cURL

curl --request POST \
  --url 'https://api.docstudio.com/api/v1/user/invite/accept/{inviteCode}' \
  --header 'Authorization: Bearer {token}'

A successful request returns 200 OK without a response body. The configured account and mailbox permissions become available to the user.

Decline or revoke an invitation

The invited user can decline an invitation when they do not want to join the account. An account administrator can instead revoke a pending invitation when the offered access must be cancelled.

Decline an invitation

Node.js

const response = await fetch(
  "https://api.docstudio.com/api/v1/user/" +
  "invite/decline/{inviteCode}",
  {
    method: "DELETE",
    headers: {
      Authorization: "Bearer {token}"
    }
  }
);

const body = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed: ${response.status}\n${body}`
  );
}

if (body) {
  console.log(body);
}

PHP

<?php

$url =
    "https://api.docstudio.com/api/v1/user/" .
    "invite/decline/{inviteCode}";

$curl = curl_init($url);

curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}"
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        "Request failed: {$status}\n{$body}"
    );
}

if ($body !== "") {
    echo $body;
}

Python

import requests

response = requests.delete(
    "https://api.docstudio.com/api/v1/user/"
    "invite/decline/{inviteCode}",
    headers={
        "Authorization": "Bearer {token}",
    },
    timeout=30,
)

response.raise_for_status()

if response.text:
    print(response.text)

Ruby

require "net/http"
require "uri"

uri = URI(
  "https://api.docstudio.com/api/v1/user/" \
  "invite/decline/{inviteCode}"
)

request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Bearer {token}"

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: uri.scheme == "https"
) do |http|
  http.request(request)
end

unless response.is_a?(Net::HTTPSuccess)
  raise "Request failed: #{response.code}\n#{response.body}"
end

puts response.body unless response.body.empty?

Go

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.docstudio.com/api/v1/user/" +
		"invite/decline/{inviteCode}"

	request, err := http.NewRequest(
		http.MethodDelete,
		url,
		nil,
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"Request failed: %s\n%s",
			response.Status,
			body,
		))
	}

	if len(body) > 0 {
		fmt.Println(string(body))
	}
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String url =
        "https://api.docstudio.com/api/v1/user/"
        + "invite/decline/{inviteCode}";

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .DELETE()
        .build();

    HttpResponse<String> response =
        HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

    if (response.statusCode() < 200 ||
        response.statusCode() >= 300) {
      throw new RuntimeException(
          "Request failed: " + response.statusCode()
          + "\n" + response.body()
      );
    }

    if (!response.body().isEmpty()) {
      System.out.println(response.body());
    }
  }
}

.NET

using System;
using System.Net.Http;
using System.Net.Http.Headers;

var url =
    "https://api.docstudio.com/api/v1/user/" +
    "invite/decline/{inviteCode}";

using var client = new HttpClient();

using var request = new HttpRequestMessage(
    HttpMethod.Delete,
    url
);

request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", "{token}");

using var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Request failed: {(int)response.StatusCode}\n{body}"
    );
}

if (!string.IsNullOrEmpty(body))
{
    Console.WriteLine(body);
}

cURL

curl --request DELETE \
  --url 'https://api.docstudio.com/api/v1/user/invite/decline/{inviteCode}' \
  --header 'Authorization: Bearer {token}'

A successful request returns 200 OK without a response body. The invitation is identified by its code.

Revoke an invitation

Node.js

const response = await fetch(
  "https://api.docstudio.com/api/v1/permission/" +
  "invite/{accountUuid}/{userUuid}",
  {
    method: "DELETE",
    headers: {
      Authorization: "Bearer {token}"
    }
  }
);

const body = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed: ${response.status}\n${body}`
  );
}

if (body) {
  console.log(body);
}

PHP

<?php

$url =
    "https://api.docstudio.com/api/v1/permission/" .
    "invite/{accountUuid}/{userUuid}";

$curl = curl_init($url);

curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}"
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        "Request failed: {$status}\n{$body}"
    );
}

if ($body !== "") {
    echo $body;
}

Python

import requests

response = requests.delete(
    "https://api.docstudio.com/api/v1/permission/"
    "invite/{accountUuid}/{userUuid}",
    headers={
        "Authorization": "Bearer {token}",
    },
    timeout=30,
)

response.raise_for_status()

if response.text:
    print(response.text)

Ruby

require "net/http"
require "uri"

uri = URI(
  "https://api.docstudio.com/api/v1/permission/" \
  "invite/{accountUuid}/{userUuid}"
)

request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Bearer {token}"

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: uri.scheme == "https"
) do |http|
  http.request(request)
end

unless response.is_a?(Net::HTTPSuccess)
  raise "Request failed: #{response.code}\n#{response.body}"
end

puts response.body unless response.body.empty?

Go

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.docstudio.com/api/v1/permission/" +
		"invite/{accountUuid}/{userUuid}"

	request, err := http.NewRequest(
		http.MethodDelete,
		url,
		nil,
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"Request failed: %s\n%s",
			response.Status,
			body,
		))
	}

	if len(body) > 0 {
		fmt.Println(string(body))
	}
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String url =
        "https://api.docstudio.com/api/v1/permission/"
        + "invite/{accountUuid}/{userUuid}";

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .DELETE()
        .build();

    HttpResponse<String> response =
        HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

    if (response.statusCode() < 200 ||
        response.statusCode() >= 300) {
      throw new RuntimeException(
          "Request failed: " + response.statusCode()
          + "\n" + response.body()
      );
    }

    if (!response.body().isEmpty()) {
      System.out.println(response.body());
    }
  }
}

.NET

using System;
using System.Net.Http;
using System.Net.Http.Headers;

var url =
    "https://api.docstudio.com/api/v1/permission/" +
    "invite/{accountUuid}/{userUuid}";

using var client = new HttpClient();

using var request = new HttpRequestMessage(
    HttpMethod.Delete,
    url
);

request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", "{token}");

using var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Request failed: {(int)response.StatusCode}\n{body}"
    );
}

if (!string.IsNullOrEmpty(body))
{
    Console.WriteLine(body);
}

cURL

curl --request DELETE \
  --url 'https://api.docstudio.com/api/v1/permission/invite/{accountUuid}/{userUuid}' \
  --header 'Authorization: Bearer {token}'

A successful request returns 200 OK without a response body. The request identifies the account and invited user.

Related topics

• Authorization

• Permission Roles

• Account and Mailbox Permissions

• Search Mailboxes and Contacts

• Error handling and API error codes