Tools · Resident companies

Resident companies through the assistant: register a company with its contract, edit, close, see your company, the team, invite by e-mail, follow, accept and decline invitations, mark the company admin and remove. There are 14 tools.

Each tool has a badge: Read-only changes nothing, Changes creates or changes something right away, and Asks to confirm only acts after your yes to a summary. See Money and confirmation.

#At a glance

The roles are the routes' roles: the assistant never does more than the connected person could do on screen. The owner and the admin see all 14; the moderator and finance, 10 (the two community-team reads and the eight open to any role); the member, 8 (get_my_resident_company, list_resident_company_members, invite_resident_company_member, remove_resident_company_member, list_resident_company_invitations, list_my_company_invitations, accept_company_invitation and decline_company_invitation).

Eight tools appear for any role because a company's admin is usually a regular member, and anyone can receive an invitation. The API decides by the link: the team is read only by the community team or the company's own people, and only the owner, the admin or that company's admin (while it is active) invites and removes. Everyone else gets "no permission".

The company admin's invite depends on acceptance. It never links right away, not even someone already in the community: the person receives the invitation by e-mail and joins the team only when they accept (accept_company_invitation). The community owner and admin still link directly.

The contract stays with management. The monthly value and the dates go to the owner, the admin and finance; the moderator reads companies without those keys, and get_my_resident_company never brings them. The monthly value is a record, not a charge.

Leaving the team suspends billing. When you remove someone or close the company with its team, the summary warns that billing for the removed person is suspended; the subscription stays on record until it is canceled, which you do in Subscriptions.

#list_resident_companies

Read-only

The resident companies, by name, with the residence type, the status (active, or ended when closed or past the exit date) and how many people are on the team. Companies are not members and never appear in member lists. The owner, the admin and finance also get the contract (monthly value, start, exit and closing date); the moderator does not. Minimum role: moderator (or finance).

Ask like this: "Which companies are resident today?"

#get_resident_company

Read-only

One company. With the contract for the owner, the admin and finance. A company from another community: "not found". A company admin uses get_my_resident_company. Minimum role: moderator (or finance).

Ask like this: "When does Acme's contract end?"

#get_my_resident_company

Read-only

Your company. The company the connected person is on (without the contract), whether they are its admin, the team, and canManageTeam, true for the admin of an active company (false once it is closed). With no company, returns company: null; pending invitations are in list_my_company_invitations. Minimum role: any.

No parameters.

Ask like this: "Who is on my company's team?"

#create_resident_company

Changes

Register a company with its contract. The company gets no login; people join with invite_resident_company_member. Minimum role: admin (owner or admin).

Ask like this: "Register Acme Tecnologia, private office, R$ 4,800 a month, since 11/1."

#update_resident_company

Changes

Edit. Only what you send: name, type, value, start or exit (ends_at: null clears the exit). To close now, use close_resident_company. Minimum role: admin (owner or admin).

Ask like this: "Acme leaves on 12/31. Update the contract."

#close_resident_company

Asks to confirm

End the residence now. The company stops accepting invites; the record and the contract stay on file. There is no reopening. With remove_members (default: true), everyone leaves the team, and whoever joined the community through the company and is still a member also leaves the community. The summary lists who leaves and warns that their billing is suspended and the subscription stays on record until it is canceled. An already closed company: refused. The first call returns the summary and the confirmation code. Minimum role: admin (owner or admin).

Ask like this: "Close Acme and take its team off."

#list_resident_company_members

Read-only

A company's team, admins first: name, job title, whether they are company admin, whether they joined through the company and, for the community team and the company admin, the e-mail. Readable by the community team or the company's own people. Minimum role: any (the API checks the link).

Ask like this: "Show Acme's team."

#invite_resident_company_member

Changes

Add to the team by e-mail. By the owner or admin, it links right away: someone already in the community only gets the link, with no e-mail (linked); anyone else joins the community as a member and receives the invite by e-mail (invited): the assistant says so first. By the company admin, it never links: the answer is always invited with pending: true and the invitation_id, whoever the person is, and the assistant says "Invitation sent. They join the team when they accept.", without claiming whether they were already in the community. Refused if the community is not accepting new members, if the person asked not to take part, if they are already on this team or if the company is closed; for the owner and the admin, also if they are already on another company. The owner, the admin and that company's admin (while it is active) invite; is_admin only the owner and the admin. The company admin sends up to 30 invitations an hour (beyond that, 429 with Retry-After); the owner and the admin have no such limit. Minimum role: any (the API checks the link).

Ask like this: "Invite [email protected] to my company's team."

#update_resident_company_member

Changes

Mark or unmark the company admin. The company admin invites and removes their own team. Minimum role: admin (owner or admin).

Ask like this: "Make Maria the admin of Acme."

#remove_resident_company_member

Asks to confirm

Take someone off the team. If they joined the community through the company and are still a member, they also leave the community and lose access; if they were already in the community, they only lose the link. The summary says which, and warns that billing for the removed person is suspended and the subscription stays on record until it is canceled. The owner, the admin and that company's admin (while it is active) remove. The first call returns the summary and the confirmation code. Minimum role: any (the API checks the link).

Ask like this: "Take João off Acme's team; he left the company."

#list_resident_company_invitations

Read-only

The company's pending invitations: the ones the company admin sent that nobody answered yet, newest first, with the e-mail typed and the date. It never says who the person is or whether they were already in the community. The owner's and the admin's invites link right away and do not show here. Readable by the community team and by that company's admin while it is active. Minimum role: any (the API checks the link).

Ask like this: "Who did I invite to my company that hasn't accepted yet?"

#list_my_company_invitations

Read-only

Your invitations. The connected person's pending invitations to join a team ("you were invited to company X"), newest first, with the company, who invited and the date. Only active companies of this community; with none, an empty list. Minimum role: any.

No parameters.

Ask like this: "Do I have any company invitation?"

#accept_company_invitation

Changes

Accept your invitation. The person joins the team (not as company admin). It does not ask for confirmation. Someone else's invitation, one already answered or from another community: "not found". A company closed after the invite, or a person already on another company's team: refused, with the API message. Minimum role: any (their own invitation).

Ask like this: "Accept the invitation from Acme."

#decline_company_invitation

Asks to confirm

Decline your invitation. No link is created and the invitation is gone for good: joining later needs a new invitation. The first call returns the summary and the confirmation code. Minimum role: any (their own invitation).

Ask like this: "Decline the invitation from Acme."

#Suggested recipes

• Register a company: register the company (create_resident_company), invite the person who will look after it (invite_resident_company_member) and mark them as company admin (update_resident_company_member, or is_admin right in the invite). Step by step in Recipes.
• The admin invites, the person accepts: the company admin invites the colleague (invite_resident_company_member) and follows it in list_resident_company_invitations; the colleague sees the invitation (list_my_company_invitations) and accepts it (accept_company_invitation). Step by step in Recipes.

#Related

• Resident companies
• Tools
• Tools · Members
• Money and confirmation
• Recipes