Users
Invite a user
Invite someone into your organization. This replaces the standard create: you send an email address rather than a user id.
If no account exists for the email, one is created. Either way an invitation email goes out, and the membership starts with appUser.status set to pending until they accept.
POST
/
organization-member
Invite a user
curl --request POST \
--url https://{instance}/api/v2/organization-member \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"email": "jsmith@example.com",
"name": "<string>",
"roleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"roleType": "custom"
}
'const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
email: 'jsmith@example.com',
name: '<string>',
roleId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
roleType: 'custom'
})
};
fetch('https://{instance}/api/v2/organization-member', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{instance}/api/v2/organization-member"
payload = {
"email": "jsmith@example.com",
"name": "<string>",
"roleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"roleType": "custom"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"value": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"appUserId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"roleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"roleType": "custom",
"status": "active",
"appUser": {
"email": "jsmith@example.com",
"name": "<string>",
"status": "pending",
"isApiKey": true
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}{
"error": {
"message": "<string>",
"code": "BAD_REQUEST",
"requestId": "<string>",
"details": [
{
"path": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"missingPermissions": [
"<string>"
]
},
"context": {}
}{
"error": {
"message": "<string>",
"code": "BAD_REQUEST",
"requestId": "<string>",
"details": [
{
"path": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"missingPermissions": [
"<string>"
]
},
"context": {}
}{
"error": {
"message": "<string>",
"code": "BAD_REQUEST",
"requestId": "<string>",
"details": [
{
"path": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"missingPermissions": [
"<string>"
]
},
"context": {}
}{
"error": {
"message": "<string>",
"code": "BAD_REQUEST",
"requestId": "<string>",
"details": [
{
"path": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"missingPermissions": [
"<string>"
]
},
"context": {}
}{
"error": {
"message": "<string>",
"code": "BAD_REQUEST",
"requestId": "<string>",
"details": [
{
"path": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"missingPermissions": [
"<string>"
]
},
"context": {}
}{
"error": {
"message": "<string>",
"code": "BAD_REQUEST",
"requestId": "<string>",
"details": [
{
"path": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"missingPermissions": [
"<string>"
]
},
"context": {}
}Authorizations
Organization-scoped API key. Create one in the BuildingSwell app under Organization settings, API keys.
Body
application/json
Where to send the invitation.
Display name for the new account. Only used when the account does not exist yet.
Role to assign.
admin grants everything. custom follows roleId.
Available options:
admin, custom Response
The new membership.
A user account's membership in your organization, including the role it carries.
Show child attributes
Show child attributes
⌘I
Invite a user
curl --request POST \
--url https://{instance}/api/v2/organization-member \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"email": "jsmith@example.com",
"name": "<string>",
"roleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"roleType": "custom"
}
'const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
email: 'jsmith@example.com',
name: '<string>',
roleId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
roleType: 'custom'
})
};
fetch('https://{instance}/api/v2/organization-member', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{instance}/api/v2/organization-member"
payload = {
"email": "jsmith@example.com",
"name": "<string>",
"roleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"roleType": "custom"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"value": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"appUserId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"roleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"roleType": "custom",
"status": "active",
"appUser": {
"email": "jsmith@example.com",
"name": "<string>",
"status": "pending",
"isApiKey": true
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}{
"error": {
"message": "<string>",
"code": "BAD_REQUEST",
"requestId": "<string>",
"details": [
{
"path": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"missingPermissions": [
"<string>"
]
},
"context": {}
}{
"error": {
"message": "<string>",
"code": "BAD_REQUEST",
"requestId": "<string>",
"details": [
{
"path": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"missingPermissions": [
"<string>"
]
},
"context": {}
}{
"error": {
"message": "<string>",
"code": "BAD_REQUEST",
"requestId": "<string>",
"details": [
{
"path": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"missingPermissions": [
"<string>"
]
},
"context": {}
}{
"error": {
"message": "<string>",
"code": "BAD_REQUEST",
"requestId": "<string>",
"details": [
{
"path": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"missingPermissions": [
"<string>"
]
},
"context": {}
}{
"error": {
"message": "<string>",
"code": "BAD_REQUEST",
"requestId": "<string>",
"details": [
{
"path": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"missingPermissions": [
"<string>"
]
},
"context": {}
}{
"error": {
"message": "<string>",
"code": "BAD_REQUEST",
"requestId": "<string>",
"details": [
{
"path": "<string>",
"message": "<string>",
"code": "<string>"
}
],
"missingPermissions": [
"<string>"
]
},
"context": {}
}