cURL
curl --request POST \
--url https://api.nekt.ai/api/v1/invitations/ \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"email": "jsmith@example.com",
"first_name": "<string>",
"last_name": "<string>",
"role": "member",
"other_functional_area": "<string>"
}
'import requests
url = "https://api.nekt.ai/api/v1/invitations/"
payload = {
"email": "jsmith@example.com",
"first_name": "<string>",
"last_name": "<string>",
"role": "member",
"other_functional_area": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
email: 'jsmith@example.com',
first_name: '<string>',
last_name: '<string>',
role: 'member',
other_functional_area: '<string>'
})
};
fetch('https://api.nekt.ai/api/v1/invitations/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nekt.ai/api/v1/invitations/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => 'jsmith@example.com',
'first_name' => '<string>',
'last_name' => '<string>',
'role' => 'member',
'other_functional_area' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.nekt.ai/api/v1/invitations/"
payload := strings.NewReader("{\n \"email\": \"jsmith@example.com\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"role\": \"member\",\n \"other_functional_area\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.nekt.ai/api/v1/invitations/")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"jsmith@example.com\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"role\": \"member\",\n \"other_functional_area\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nekt.ai/api/v1/invitations/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"jsmith@example.com\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"role\": \"member\",\n \"other_functional_area\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"email": "jsmith@example.com",
"sent_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z",
"accepted_at": "2023-11-07T05:31:56Z",
"revoked_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"created_by": {
"id": 123,
"first_name": "<string>",
"last_name": "<string>",
"email": "jsmith@example.com",
"picture": "<string>",
"role": "<string>",
"functional_area": "data_analytics",
"other_functional_area": "<string>",
"date_joined": "2023-11-07T05:31:56Z",
"last_login": "2023-11-07T05:31:56Z",
"is_active": false,
"is_pending": false
},
"first_name": "<string>",
"last_name": "<string>",
"role": "member",
"functional_area": "data_analytics",
"other_functional_area": "<string>"
}Invitations
Invite User
Invite one person to your organization, or resend the invitation they already have.
POST
/
api
/
v1
/
invitations
/
cURL
curl --request POST \
--url https://api.nekt.ai/api/v1/invitations/ \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"email": "jsmith@example.com",
"first_name": "<string>",
"last_name": "<string>",
"role": "member",
"other_functional_area": "<string>"
}
'import requests
url = "https://api.nekt.ai/api/v1/invitations/"
payload = {
"email": "jsmith@example.com",
"first_name": "<string>",
"last_name": "<string>",
"role": "member",
"other_functional_area": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
email: 'jsmith@example.com',
first_name: '<string>',
last_name: '<string>',
role: 'member',
other_functional_area: '<string>'
})
};
fetch('https://api.nekt.ai/api/v1/invitations/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nekt.ai/api/v1/invitations/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => 'jsmith@example.com',
'first_name' => '<string>',
'last_name' => '<string>',
'role' => 'member',
'other_functional_area' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.nekt.ai/api/v1/invitations/"
payload := strings.NewReader("{\n \"email\": \"jsmith@example.com\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"role\": \"member\",\n \"other_functional_area\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.nekt.ai/api/v1/invitations/")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"jsmith@example.com\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"role\": \"member\",\n \"other_functional_area\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nekt.ai/api/v1/invitations/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"jsmith@example.com\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"role\": \"member\",\n \"other_functional_area\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"email": "jsmith@example.com",
"sent_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z",
"accepted_at": "2023-11-07T05:31:56Z",
"revoked_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"created_by": {
"id": 123,
"first_name": "<string>",
"last_name": "<string>",
"email": "jsmith@example.com",
"picture": "<string>",
"role": "<string>",
"functional_area": "data_analytics",
"other_functional_area": "<string>",
"date_joined": "2023-11-07T05:31:56Z",
"last_login": "2023-11-07T05:31:56Z",
"is_active": false,
"is_pending": false
},
"first_name": "<string>",
"last_name": "<string>",
"role": "member",
"functional_area": "data_analytics",
"other_functional_area": "<string>"
}Invites a single person to your organization. The same call also resends an existing invitation: posting an address that already has a live invitation resends it rather than creating a second one.
Inviting someone provisions them immediately as a pending member, so you can add them to permission groups and grant them access before they accept. See Pending users and pre-granted invitations below.
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | The address to invite. Normalized before storing, so casing never creates a duplicate. |
role | string | No | One of owner, admin, or member. Defaults to member. |
first_name | string | No | Shown in the member list before the person accepts. |
last_name | string | No | Shown in the member list before the person accepts. |
functional_area | string | No | The invitee’s functional area. |
other_functional_area | string | No | Free-text functional area, when none of the predefined options fit. |
first_name and last_name are optional. An admin often has only an address, and the person names themselves afterward from their profile or the onboarding step. The invitation email greets an unnamed invitee by their address.Response
Returns the Invitation object. The status code tells you which of the two things happened:201 Created— a new invitation was created.200 OK— an existing invitation was resent.
Example
curl --request POST \
--url https://api.nekt.ai/api/v1/invitations/ \
--header "x-api-key: YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"email": "newcomer@example.com",
"role": "member"
}'
Resending and role changes
Sending the same address again is safe and is how you chase someone who has not accepted. Nobody is duplicated: the existing invitation is resent with a fresh expiry, and the invitee’s existing groups and grants are untouched. If therole differs from the outstanding invitation, the resend is a role change — it moves the person on both the invitation and their pending membership.
Moving an existing
admin or owner invitee to another role requires an owner. This is the same ceiling that applies to changing the role of an accepted member.Pending users and pre-granted invitations
Because an invitation provisions the person right away, they exist as a pending member the moment the call succeeds:- Grant access before acceptance. A pending member is a normal target for the group editor and every permission-assign endpoint — no separate flow.
- Pending is not inactive. In the member list a pending member carries its own status; it is not the same as a deactivated user.
- They cannot log in until they accept. The invitation token is the only proof that the person controls the address.
- Revoking is destructive. Revoking (see Errors) removes the invitee’s groups and grants, not just the email.
Authentication
This endpoint requires an API key in thex-api-key header.
Only an owner or an admin can invite, and nobody can invite somebody to a role above their own. For an API key, that ceiling is read from the role of the user who created the key.
Errors
| Status | When |
|---|---|
400 | The address already belongs to an active member of the organization. |
400 | email is missing or malformed. |
403 | The caller is a member, or the request names a role above the caller’s own. |
403 | The request changes the role of an existing admin or owner invitee and the caller is not an owner. |
Related
- Bulk Invite Users — invite several people in one call.
- Invitation object — the full response schema.
Authorizations
API Key authentication. Format: 'x-api-key: api_key'
Body
application/jsonapplication/x-www-form-urlencodedmultipart/form-data
Maximum string length:
254Maximum string length:
150Maximum string length:
150Defaults to member. You cannot invite somebody to a role above your own, and on the Free plan only owners can be invited.
owner- Owneradmin- Adminmember- Member
Available options:
owner, admin, member data_analytics- Data & Analyticssales- Salescustomer_support- Customer Supportoperations- Operationsmarketing- Marketingfinance- Financeproduct_development- Product Developmentgrowth- Growthexecutive_leadership- Executive Leadershipother- Other
Available options:
data_analytics, sales, customer_support, operations, marketing, finance, product_development, growth, executive_leadership, other Maximum string length:
128Response
201 - application/json
Maximum string length:
254Show child attributes
Show child attributes
Maximum string length:
150Maximum string length:
150Defaults to member. You cannot invite somebody to a role above your own, and on the Free plan only owners can be invited.
owner- Owneradmin- Adminmember- Member
Available options:
owner, admin, member data_analytics- Data & Analyticssales- Salescustomer_support- Customer Supportoperations- Operationsmarketing- Marketingfinance- Financeproduct_development- Product Developmentgrowth- Growthexecutive_leadership- Executive Leadershipother- Other
Available options:
data_analytics, sales, customer_support, operations, marketing, finance, product_development, growth, executive_leadership, other Maximum string length:
128Was this page helpful?