Update a Company Manager's billing contact assignment

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 the urn:ietf:params:oauth:grant-type:jwt-bearer grant 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 typeCategoryRead only ScopeWrite only Scope (read access implicit)
Company-scoped access tokenManage 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 tokenManage company resources (company_admin)-Manage managers (company_manager:write)
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

User ID

Body Params

Company Manager billing contact params

billing_contact_for
array of objects
required

Every legal entity this manager should be a billing contact for. Each must be listed by the caller's GET and covered by one of their roles with permission to update billing communications, or the call returns 404. A role assigned to some legal entities only limits the caller to those, even where another role covers the whole company. Legal entities left out that the caller can change stop having this manager as a billing contact.

billing_contact_for*
Responses

Callback
Language
Credentials
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json