Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

On Behalf Of

API Overview

api-overview page anchor

Welcome to SendGrid's Web API v3! This API is RESTful, fully featured, easy to integrate with, and offers support in 7 different languages.

The On Behalf Of header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. Use this header to automate bulk updates or to administer a Subuser or account without changing the authentication in your code.



The on-behalf-of header does not work with the Mail Send API.

On Behalf Of generates the API call as if the Subuser or customer account is making the call. When authenticating and using the on-behalf-of header, you must use the parent account's API key credentials.

On Behalf Of accepts either a Subuser username or customer account ID, depending on which type of sub-account structure you are administering. Subusers function like separate SendGrid sub-accounts, and they're available to all customers on Pro and Premier plans(link takes you to an external page). Customer accounts also act as separate sub-accounts that are managed by a parent account; however, customer accounts are available only to companies that have a formal reseller partnership with Twilio SendGrid.

See Subusers for more information about working with Subusers. See the Account Provisioning API for more information about managing customer accounts.

When making a call on behalf of a customer account, the property value should be "account-id" followed by the customer account's ID.

on-behalf-of: account-id <account-id>

When making a call on behalf of a Subuser, the property value should be the Subuser's username.

on-behalf-of: <subuser-username>

On Behalf Of SubuserOn Behalf Of Customer Account

curl --request GET \
--url '' \
--header 'authorization: Bearer <SENDGRID_API_KEY>' \
--header 'on-behalf-of: <subuser-username>'

Rate this page: