Account Members

The people in an account. A person exists in Zuplo as soon as they are added: POST /v4/accounts/{accountId}/members with their email returns their userId (user_…) right away, whether or not they have ever signed in, and every pool and project accepts that userId at once. There is no separate invitation resource and nothing to poll.

How members behave:

Who. Account admins add, change and remove members. Every account member can list and read them.
Invited, then active. Someone new to the account is added with status: invited, and Zuplo emails them a link. They become active when they sign in: through the account's enterprise SSO connection if it has one, otherwise by accepting the email. Accepting happens in the Zuplo portal, not in v4. Everything they were given while invited (pools, projects) takes effect at that moment. Until then they cannot use it.
One per person. A person is in an account once, whatever the case of their email address. Adding an email that is already a member changes their role, and for an invited member sends the email again with a new link: that is how an invitation is resent.
Seven days. The link in the email works for seven days (invitationExpiresOn). After that the member stays invited; add them again to send a new link.
Seats. An invited member does not hold a seat. Adding someone new fails with 409 when the account already has as many active members as its plan allows, and so does their first sign-in, if the account filled up in the meantime.
sub. A member's sub, the subject their identity provider assigned them, is read-only and null until their first sign-in. It is not an identifier in v4: every path and reference uses userId.

List account members

GET

https://dev-api-v4-main-a471234.zuplo.app

/v4/accounts/{accountId}/members

Lists the people in the account, invited and active, oldest first, with their account role. Filter by email or by sub to look up one person's userId. Every account member can list them.

List account members › path Parameters

accountId

string · maxLength: 64 · required

The account ID, a UUID.

List account members › query Parameters

email

string · email · maxLength: 320

Only return the member with this email address (case-insensitive).

sub

UserSub · maxLength: 255

Only return the member with this sub, the subject their identity provider assigned them. Members who have not signed in yet have none.

The subject the identity provider of a person's Zuplo sign-in assigned them, for example auth0|… or samlp|…. Read-only: it is set at their first sign-in. It is not an identifier in v4, where people are their userId.

Example: auth0|65f1c2d9e4b0a1b2c3d4e5f6

limit

integer · min: 1 · max: 100

The maximum number of items to return.

Default: 10

offset

integer · min: 0

The number of items to skip before the first item returned.

Default: 0

List account members › Responses

A page of account members.

AccountMemberList

AccountMember[] · required

The account members on this page.

limit

integer · required

The page size that was applied.

offset

integer · required

The number of items skipped before this page.

total

integer · required

The number of items in the whole collection.

hasMore

boolean · required

Whether there are more items after this page.

next

string | null · required

The relative URL of the next page, or null on the last page.

Add or update an account member

POST

https://dev-api-v4-main-a471234.zuplo.app

/v4/accounts/{accountId}/members

Adds a person to the account by email, or changes the role of a person who is already in it. Returns 201 with the new member when the email is new to the account, and 200 when it already was a member. Only account admins can add people.

Someone new is added with status: invited and gets an email with a link to sign in. Their userId works everywhere at once: add it to pools (POST /v4/buckets/{bucketId}/ai/pools/{poolId}/members) and projects (POST /v4/projects/{projectId}/members, ai-user included) in the next requests, without waiting. Those grants take effect when the person becomes active, by signing in through the account's SSO connection or by accepting the email.

Adding an email that is already a member changes their role, so sending the same request again changes nothing. For a member who is still invited, it also sends the email again, with a new link and invitationExpiresOn: that is how an invitation is resent. Email addresses are compared case-insensitively, so [email protected] is the member [email protected].

Without role-based access control (an enterprise add-on), every account member is an admin: role defaults to admin, and any other role is a 400. With it, role defaults to member for someone new and is unchanged for an existing member when omitted.

Fails with 409 when the email is new to the account and the account already has as many active members as its plan allows. Invited members do not count toward that limit.

Add or update an account member › path Parameters

accountId

string · maxLength: 64 · required

The account ID, a UUID.

Add or update an account member › Request Body

A person to add to the account, by email, or whose account role to change.

UpsertAccountMemberRequest

email

string · email · maxLength: 320 · required

The person's email address. Someone new is invited at this address and signs in with it. Compared case-insensitively, without surrounding whitespace.

role

AccountRoleInput · enum

The account role to give a person. ai-user is a project role, so it is not one: give it on a project. Without role-based access control any value but admin is a 400. New values may be added.

Enum values:

admin

developer

member

Add or update an account member › Responses

The person already was a member. Their role was updated, and an invited member was sent the email again.

A person in an account, invited or active.

AccountMember

accountId

string · required

The account.

Example: 5f0c7c2e-8d3a-4b1e-9f2a-6c1d0e7b3a49

userId

UserId · maxLength: 64 · required

A person, identified by their Zuplo user ID (user_…). Zuplo assigns it when the person is first added to an account, before they ever sign in, and it never changes. Every userId and ownerId in v4 is one.

Example: user_Jm5tR8wQz2KcX7vB4nLp9HdS

required

The subject their identity provider assigned them, set at their first sign-in. Null while they are invited.

email

string · email · required

The person's email address. An invited member signs in with it.

Example: [email protected]

name

string | null · required

The person's display name, if they set one. Null while they are invited.

Example: Jane Doe

role

AccountRole · enum · required

A person's role in the account. New values may be added.

Enum values:

admin

developer

member

ai-user

status

AccountMemberStatus · enum · required

Whether a person can use the account yet. invited: they were added and emailed a link, and have not signed in since; their roles take effect when they do. active: they have signed in. New values may be added.

Enum values:

invited

active

invitationExpiresOn

string | null · date-time · required

When the link in the latest invitation email stops working, seven days after it was sent. Null once the member is active.

createdOn

string · date-time · required

When the person was added to the account.

POST/v4/accounts/{accountId}/members

curl https://dev-api-v4-main-a471234.zuplo.app/v4/accounts/:accountId/members \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "email": "[email protected]",
  "role": "developer"
}'

Example Request Body

{
  "email": "[email protected]",
  "role": "developer"
}

json

application/json

Example Responses

{
  "accountId": "5f0c7c2e-8d3a-4b1e-9f2a-6c1d0e7b3a49",
  "userId": "user_Jm5tR8wQz2KcX7vB4nLp9HdS",
  "sub": "auth0|65f1c2d9e4b0a1b2c3d4e5f6",
  "email": "[email protected]",
  "name": "Jane Doe",
  "role": "admin",
  "status": "invited",
  "invitationExpiresOn": "2024-08-25T15:00:00Z",
  "createdOn": "2024-08-25T15:00:00Z"
}

json

application/json

Get an account member

GET

https://dev-api-v4-main-a471234.zuplo.app

/v4/accounts/{accountId}/members/{userId}

Returns one person in the account, invited or active. Every account member can read them.

Get an account member › path Parameters

accountId

string · maxLength: 64 · required

The account ID, a UUID.

userId

UserId · maxLength: 64 · required

The user ID of an account member (user_…).

Example: user_Jm5tR8wQz2KcX7vB4nLp9HdS

Get an account member › Responses

The account member.

A person in an account, invited or active.

AccountMember

accountId

string · required

The account.

Example: 5f0c7c2e-8d3a-4b1e-9f2a-6c1d0e7b3a49

userId

UserId · maxLength: 64 · required

Example: user_Jm5tR8wQz2KcX7vB4nLp9HdS

required

The subject their identity provider assigned them, set at their first sign-in. Null while they are invited.

email

string · email · required

The person's email address. An invited member signs in with it.

Example: [email protected]

name

string | null · required

The person's display name, if they set one. Null while they are invited.

Example: Jane Doe

role

AccountRole · enum · required

A person's role in the account. New values may be added.

Enum values:

admin

developer

member

ai-user

status

AccountMemberStatus · enum · required

Enum values:

invited

active

invitationExpiresOn

string | null · date-time · required

When the link in the latest invitation email stops working, seven days after it was sent. Null once the member is active.

createdOn

string · date-time · required

When the person was added to the account.

Remove an account member

DELETE

https://dev-api-v4-main-a471234.zuplo.app

/v4/accounts/{accountId}/members/{userId}

Removes a person from the account, with their roles on its projects and AI pools. For an invited member, the link in their email stops working. Only account admins can remove people. A repeated delete returns 404, which clients should treat as success.

Remove an account member › path Parameters

accountId

string · maxLength: 64 · required

The account ID, a UUID.

userId

UserId · maxLength: 64 · required

The user ID of an account member (user_…).

Example: user_Jm5tR8wQz2KcX7vB4nLp9HdS

Remove an account member › Responses

The member was removed.

No data returned

Accounts Projects