Replaces the legal entities a Company Manager is a billing contact for, among the
legal entities the caller can change (see below). After the call they receive Remote
invoices for the legal entities in billing_contact_for, each marked primary or not,
and stop being a billing contact for the other legal entities the caller can change.
Send an empty list to remove them from all of those (the company owner stays primary
where no one else is, see below).
- Making the manager primary replaces the legal entity's current primary contact.
Removing or demoting a primary contact is allowed: the company owner then receives
the invoices until someone else is made primary. - The company owner is the primary billing contact for every legal entity where no
one else is primary, whether or not they are listed. For the owner, listing such a
legal entity as primary changes nothing, and leaving it out does not remove them;
make someone else primary instead. Listing it as not primary adds the owner as a
regular contact there, and they stay primary until someone else is made primary. - The manager does not need permission to read billing, or a confirmed account, to be
added or made primary. - A newly added contact also receives contractor invoices, and removing a contact
stops both. - Contacts who only receive contractor invoices are not shown by this API and are
left unchanged, unless their legal entity is listed, in which case they also start
receiving Remote invoices. - Every listed legal entity must have an active billing account and appear only once.
A newly created legal entity's billing account may not be active yet; retry once it
is. Adding the manager to a legal entity that already has 15 invoice recipients,
counting ones this API doesn't show, also fails. Any of these returns 422 and
changes nothing. - The legal entities the caller can change are the ones the same caller's GET lists
that one of their roles with permission to update billing communications also
covers. Listing any other legal entity returns 404, and the call leaves the manager
as they are everywhere else, so sending back what GET returned never removes the
manager from a legal entity GET didn't show. If any of the caller's roles is
assigned to some legal entities only, the caller can change only those, even where
another of their roles covers the whole company. GET can still list legal entities
this call refuses: ones no role with permission to update billing communications
covers, and, on integrations that don't limit callers to the legal entities they
can access, any legal entity outside those roles or outside a role assigned to some
legal entities. A caller with no role that can read team members can change no
legal entity: an empty list changes nothing, and any other list returns 404.
Changing a deleted manager returns 404.
Deleting the manager is still refused while they are primary for any legal entity,
including ones the caller can't see. - The response lists the manager's billing contacts only on the legal entities the
caller can access, also on integrations that don't limit callers to those. So the
response can leave out legal entities the same caller's GET lists.
Requires permission to update billing communications. If your integration checks
callers' roles, it also requires permission to update team members.
Authentication
This endpoint accepts any one of the following token types:
- Company-scoped access token (
OAuth2AuthorizationCode) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See Authentication for partners. - Company-scoped access token (assertion) (
OAuth2CompanyManagerAssertion) — obtained through theurn:ietf:params:oauth:grant-type:jwt-bearergrant for a company manager. See OAuth Assertion. - Customer API token (
CustomerAPIToken) — generated by the customer on their Integration Settings page, with the scopes they choose there. See Authorization for customers.
Scopes
Any one of the scopes in a token type's row is enough. all:write works too.
| Token type | Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|---|
| Company-scoped access token | Manage company resources (company_admin) | - | Manage managers (company_manager:write) |
| Company-scoped access token (assertion) | Manage company resources (company_admin) | - | Manage managers (company_manager:write) |
| Customer API token | Manage company resources (company_admin) | - | Manage managers (company_manager:write) |
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||