Team Members API

Team members are the humans who collaborate inside a team: the creator who owns it and the people they invited to help run its projects.

Team members are the humans who collaborate inside a team: the creator who owns it and the people they invited to help run its projects. They are distinct from a project's members, the subscribers who buy plans, who are modelled separately and reached through the Members endpoints.

A collaborator joins by invitation to an email address with a role code, holds one role at a time, and leaves either by removal or by having an unaccepted invitation withdrawn; both take the same ability, because both revoke the same prospective access. The team's owner appears as the first row of the roster but is not a membership: ownership cannot be re-roled or removed here. Reading who is on a team and reading how to reach them are separate asks, so email is present only when the token carries team-member:view and is otherwise absent from the row altogether.

The list is not paginated, since a team's collaborator list is small by construction. Every change announces itself as a team.* event.

Background

What the API refuses

The teams package enforces these itself; the API restates them rather than letting a plainly-invalid request surface as a 500.

Attempt	Result
Re-role or remove the owner	`404`: ownership is not a membership row
Invite someone already in the team	`422`
Name a `role` code the team does not have	`422`
Address a user who is not in the team	`404`
Address a team the caller cannot see	`404`

A team is visible only when the caller owns it or is a member. Tokens scoped to a different team get 404 RESOURCE_NOT_FOUND on every route here; existence never leaks.

Endpoints

GET/v1/teams/{team}/membersList a team's members POST/v1/teams/{team}/membersInvite a team member GET/v1/teams/{team}/members/{member}Get a team member DELETE/v1/teams/{team}/members/{member}Remove a team member PATCH/v1/teams/{team}/members/{member}/roleChange a team member's role DELETE/v1/teams/{team}/invitations/{invitation}Withdraw an invitation

List a team's members

GET

curl https://api.subscriby.net/v1/teams/$TEAM_ID/members \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

The team's owner as the first row followed by every member. Not paginated: a team's collaborator list is small by construction.

email is omitted entirely unless the token carries team-member:view. Listing who is on a team and reading how to reach them are different asks, and the fine-grained ability is what separates them. A roster-only token gets every other field and no email key at all: not null, absent.

The same team-member:view-any permission gates the dashboard's Settings → Teams → Manage Members page: only team owners and members holding the permission via their role can load it. Free-tier teams auto-assign everyone as owner, so this only matters on Growth-tier teams with multiple collaborators.

Requires ability

team-member:view-any

The token must hold this ability, or the call is refused with 403.

MCP tool

list_team_members

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.

In: header

Path Parameters

team*string

The team, resolved by the route binder.

Formatuuid

Responses

200OKapplication/json

Array of TeamMemberResource

data*array<>

The items.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/teams/497f6eca-6276-4993-bfeb-53cbbbba6f08/members"

{  "data": [    {      "id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",      "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",      "name": "Priya Patel",      "email": "[email protected]",      "role_id": "d05e1a83-7c46-4f29-b613-8ae407c9d251",      "is_owner": false,      "joined_at": "2026-04-02T14:15:00Z"    }  ]}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: TeamMemberResource[];}export interface TeamMemberResource {  id: string;  team_id: string;  name: string;  email?: string;  role_id: string | null;  is_owner: boolean;  joined_at: string | null;}

Invite a team member

POST

curl -X POST https://api.subscriby.net/v1/teams/$TEAM_ID/members \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{"email": "[email protected]", "role": "support-agent"}'

Addressed by email, not user id: the invitee may not have a Subscriby account yet, which is what separates inviting from adding. They receive an invitation message with a link; the membership row appears when they accept.

role is a role code on that team, such as support-agent, not a role id. Create it first with Roles if it does not exist.

Answers 201 with the invitation summary. Emits team.member.invited, then team.member.joined when they accept.

Requires ability

team-member:invite

The token must hold this ability, or the call is refused with 403.

Fires one event

team.member.invited

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

invite_team_member

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

team*string

The team, resolved by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Formatuuid

Request body

JSONWhat the request carriesRequiredapplication/json

Who to invite and as what. An invitation names an email rather than a user, because the invitee may not have an account yet.

email*string

The invitee's email address, up to 255 characters. They receive an invitation message with a link; the membership appears when they accept.

Formatemail

Lengthlength <= 255

role*string

A role code on that team, such as support-agent, not a role id. Create it first if it does not exist; an unknown code is refused.

Lengthlength <= 255

Responses

201Createdapplication/json

201 with the invitation summary.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

The payload broke a rule, and error.fields maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with error.message saying why and no fields. On this endpoint: VALIDATION_FAILED: when the role code is not one of the team's, or the invitee is already in the team.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/teams/497f6eca-6276-4993-bfeb-53cbbbba6f08/members" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12" \  -H "Content-Type: application/json" \  -d '{    "email": "[email protected]",    "role": "string"  }'

{  "data": {    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",    "email": "[email protected]",    "role": "support-agent",    "status": "invited"  }}

Type definitions

The shapes above as types, ready to paste into your client.

Request

export interface InviteTeamMemberRequest {  email: string;  role: string;}

Response

export interface Response {  data: Data;}export interface Data {  team_id: string;  email: unknown;  role: unknown;  status: string;}

Get a team member

GET

curl https://api.subscriby.net/v1/teams/$TEAM_ID/members/$USER_ID \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

One collaborator, with their email, which this route always includes because it requires team-member:view by definition. 404 RESOURCE_NOT_FOUND if the user is not on the team or the team is not in the caller's visibility set.

role_id points at a Role row on the same team, or null for the owner pseudo-row.
is_owner is true only for the single team creator; the owner is returned alongside the members but bypasses the membership table entirely.

Requires ability

team-member:view

The token must hold this ability, or the call is refused with 403.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

team*string

The team, resolved by the route binder.

Formatuuid

member*string

The person's place on the team, resolved by the route binder.

Responses

200OKapplication/json

The membership.

data*

The response's payload.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/teams/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/string"

{  "data": {    "id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",    "name": "Priya Patel",    "email": "[email protected]",    "role_id": "d05e1a83-7c46-4f29-b613-8ae407c9d251",    "is_owner": false,    "joined_at": "2026-04-02T14:15:00Z"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: TeamMemberResource;}export interface TeamMemberResource {  id: string;  team_id: string;  name: string;  email?: string;  role_id: string | null;  is_owner: boolean;  joined_at: string | null;}

Remove a team member

DELETE

curl -X DELETE https://api.subscriby.net/v1/teams/$TEAM_ID/members/$USER_ID \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)"

Returns 204 No Content. They lose access to every project and setting scoped to the team immediately; their own Subscriby account is untouched. Not gated by tier. Emits team.member.removed.

Requires ability

team-member:remove

The token must hold this ability, or the call is refused with 403.

Fires one event

team.member.removed

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

remove_team_member

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

team*string

The team, resolved by the route binder.

Formatuuid

member*string

The membership, resolved by the route binder.

Header Parameters

Idempotency-Key*string

Formatuuid

Responses

204No content

No content

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred. On this endpoint: RESOURCE_NOT_FOUND: for the owner, who cannot be removed.

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X DELETE "https://example.com/v1/teams/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/string" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

No body on this response.

Change a team member's role

PATCH

curl -X PATCH https://api.subscriby.net/v1/teams/$TEAM_ID/members/$USER_ID/role \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{"role": "manager"}'

Moves a collaborator onto another of the team's roles. The team owner cannot be re-roled: ownership is not a membership row and carries everything unconditionally. Answers 200 with the membership and emits team.member.role_changed.

Changing a member's role has no dashboard equivalent: the settings page offers invite, remove and cancel-invitation only, so this endpoint is the only way to move someone between roles without removing and re-inviting them.

Requires ability

team-member:update-role

The token must hold this ability, or the call is refused with 403.

Fires one event

team.member.role_changed

Delivered to every endpoint subscribed to it once the change is made.

MCP tool

update_team_member_role

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

team*string

The team, resolved by the route binder.

Formatuuid

member*string

The membership, resolved by the route binder.

Header Parameters

Idempotency-Key*string

Formatuuid

Request body

JSONWhat the request carriesRequiredapplication/json

The role to move a collaborator onto.

role*string

A role code on the team, such as manager, not a role id. An unknown code is refused.

Lengthlength <= 255

Responses

200OKapplication/json

The membership after the change.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X PATCH "https://example.com/v1/teams/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/string/role" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12" \  -H "Content-Type: application/json" \  -d '{    "role": "string"  }'

{  "data": {    "id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",    "name": "Priya Patel",    "email": "[email protected]",    "role_id": "d05e1a83-7c46-4f29-b613-8ae407c9d251",    "is_owner": false,    "joined_at": "2026-04-02T14:15:00Z"  }}

Type definitions

The shapes above as types, ready to paste into your client.

Request

export interface UpdateTeamMemberRoleRequest {  role: string;}

Response

export interface Response {  data: TeamMemberResource;}export interface TeamMemberResource {  id: string;  team_id: string;  name: string;  email?: string;  role_id: string | null;  is_owner: boolean;  joined_at: string | null;}

Withdraw an invitation

DELETE

Requires team-member:remove, the same ability as removing a member, because withdrawing an invitation and removing a member revoke the same prospective access.

curl -X DELETE https://api.subscriby.net/v1/teams/$TEAM_ID/invitations/$INVITATION_ID \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)"

An invitee is not a member. Someone who has not accepted has no membership row to remove, only a pending invitation. That is why this is a separate route: removing a member and withdrawing an invitation fail on different things, and using the wrong one returns 404 rather than doing something surprising.

Returns 204 No Content and the invitation link stops working.

Requires ability

team-member:remove

The token must hold this ability, or the call is refused with 403.

MCP tool

cancel_team_invitation

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

team*string

The team, resolved by the route binder.

Formatuuid

invitation*string

The pending invitation, resolved within the team by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

Formatuuid

Responses

204No content

No content

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X DELETE "https://example.com/v1/teams/497f6eca-6276-4993-bfeb-53cbbbba6f08/invitations/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

No body on this response.

Roles APIA role is the permission set a collaborator holds on a team.Teams APITeams group creators, roles, and projects.Ability CatalogEvery ability string a Subscriby token can carry, what enforces it, and how to pick the right ones when minting.team.* eventsTeam creation, rename, deletion, and membership changes.

Team Members API

What the API refusesCopy Anchor Link

EndpointsCopy Anchor Link

List a team's membersCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Invite a team memberCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ResponsesCopy Anchor Link

Get a team memberCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Remove a team memberCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Change a team member's roleCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ResponsesCopy Anchor Link

Withdraw an invitationCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Related

On this page

What the API refuses

Endpoints

List a team's members

Authorization

Path Parameters

Responses

Invite a team member

Authorization

Path Parameters

Header Parameters

Request body

Responses

Get a team member

Authorization

Path Parameters

Responses

Remove a team member

Authorization

Path Parameters

Header Parameters

Responses

Change a team member's role

Authorization

Path Parameters

Header Parameters

Request body

Responses

Withdraw an invitation

Authorization

Path Parameters

Header Parameters

Responses