Share via

Sender Permissions (Legacy)

  • Article

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

As a LinkedIn Ad Account manager, you can manage senders for a Message Ad or Conversation Ad Campaign you've created.

Note:

  • Message Ads can be from LinkedIn members or companies.
  • The Company Senders functionality is currently only available to beta advertisers. The API only allows retrieval of pre-approved company senders through the Find Sender Permissions by Account finder.
  • For member senders, you can make sender permission requests for Message Ad Campaigns to your 1st degree connections.
  • Once a sender request for Message Ad Campaign is sent, you can't cancel it. However, you can remove senders. See removing and changing Message Ad Senders.
  • When sender permission requests are sent, senders are granted access to the associated Message Ad campaign and account. If the senders are not already a part of your account, they are added with the VIEWER role.
  • Account Managers, Campaign Managers, and Creative Managers can add Message Ad senders. Users with the role VIEWER cannot.

For more information, see:

Permissions

Permission Description
rw_ads Manage and read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
    		•
    r_ads Read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
  • VIEWER
    		•

    See Account Access Controls for more information on ad account roles.

    Schema

    Sender Permissions Schema

    Field Type Description
    account SponsoredAccountUrn The account for the permission. For example, urn:li:sponsoredAccount:5869457.
    member PersonUrn The member for the permission. For example, urn:li:person:K1RwyVNukt.
    state State The actual permission value of the account/member pair. Possible values are:
  • REQUESTED - The assignment has been requested to be approved.
  • APPROVED - The assignment has been approved and is valid until it expires or forever if there is no expiration.
  • REVOKED - The assignment (which was once approved) has now been revoked.
  • REJECTED - A request for the assignment to be approved was rejected.
    		•

    Managing Sender Permissions

    Create Sender Permissions

    The following items are validated before the creation of sender permissions:

    • The requester calling the API should be a first degree connection to the requested member (recipient).
    • The requester calling the API should have write access to the request Ad Account.

    Update Sender Permissions

    If an existing sender permission does not exist, an UPDATE request creates one.

    The following items are validated before updating sender permissions:

    • The requester must have write access to the Ad Account.
    • If the member is the one who has been requested the "sender permissions" (recipient), then that member can change the state to APPROVED or REJECTED.

    If the member updates this endpoint to request to the sender, a response is returned with a 304 Not Modified status.

    Allowed State Transitions

    The requester can request access by setting the state to REQUESTED.

    When a recipient is deleted from the Ad Accounts using AdAccountUsersV2, the state for that Sender Permission is changed from REQUESTED to REVOKED.

    Similarly, when the recipient is given access to the Ad Account, the sender permission state changes from REVOKED to REQUESTED.

    ![Requester sender permissions]Requester sender permissions

    The recipient can change a state from:

    • REQUESTED to APPROVED
    • REQUESTED to REJECTED
    • APPROVED to REJECTED
    • REJECTED to APPROVED

    ![Recipient sender permissions]Recipient sender permissions

    PUT https://api.linkedin.com/v2/adInMailMemberSenderPermissions/account={encoded SponsoredAccounturn}&member={encoded person urn}

    {
    "account": "{sponsoredAccount urn}",
    "member": "{person urn}",
    "state": "{state}"
}

    Sample Request

    PUT https://api.linkedin.com/v2/adInMailMemberSenderPermissions/account=urn%3Ali%3AsponsoredAccount%3A516986977&member=urn%3Ali%3Aperson%3A_mVMF2Kp8p

    {
    "account": "{sponsoredAccount urn}",
    "member": "{person urn}",
    "state": "{state}"
}

    A successful response returns a 200 OK HTTP status code.

    A failed response returns a 400 Bad Request status code and one of the following error responses:

    • MISSING_READ_ACCESS - When the recipient does not have account read access
    • INVALID_STATE_TRANSITION - When an invalid state transition is made. For example, setting state from "APPROVED" to "REQUESTED".
    • UNAUTHORIZED_STATE_TRANSITION - When a member who is trying to update doesn't have permission. For example, if a requester updating state to "APPROVED" for a sender or recipient is trying to change the state for a sender permission that does not exist.

    Find Member Sender Permissions by Account

    All Member Sender Permissions granted for an Ad Account can be fetched using the following API. This API takes in a sponsoredAccount URN in the account parameter. Note that the member you're making this call on behalf of must have at least read access to the requested Ad Account.

    GET https://api.linkedin.com/v2/adInMailMemberSenderPermissions/account={Encoded SponsoredAccount urn}?q=account

    Sample Response

    {
    "elements": [
        {
            "account": "urn:li:sponsoredAccount:516986977",
            "member": "urn:li:person:LBSWch4wcA",
            "state": "APPROVED"
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

    A 400 Bad Request with reason=NO_PERMISSION_ON_ENTITY is returned if the requesting member does not have access to the requested Ad Account.

    Find Company Senders by Account

    All company sender permissions granted to an Ad Account can be fetched using the Company Senders Find By Account API. This API takes in a sponsoredAccount URN in the account parameter.

    Note that the member you are making this call on behalf of must have at least read access to the requested ad account.

    GET https://api.linkedin.com/v2/adInMailCompanySenderPermissions/account=urn%3Ali%3AsponsoredAccount%3A12342222?q=account

    Sample Response

    { 
   "elements":[ 
      { 
         "account":"urn:li:sponsoredAccount:12342222",
         "company":"urn:li:organization:2222",
         "state":"APPROVED"
      },
      { 
         "account":"urn:li:sponsoredAccount:12342222",
         "company":"urn:li:organization:3333",
         "state":"APPROVED"
      }
   ],
   "paging":{ 
      "count":10,
      "links":[ 

      ],
      "start":0
   }
}

    A 400 Bad Request is returned if the viewer is not present or does not have a minimum of read access to the account.

    Find Sender Permissions by Member

    The following API allows a member to fetch all Sender Permissions they have across multiple Ad Accounts. This API takes in a person URN in the member parameter.

    GET https://api.linkedin.com/v2/adInMailMemberSenderPermissions/member={encoded person urn}?q=member

    GET https://api.linkedin.com//v2/adInMailMemberSenderPermissions/member=urn%3Ali%3Aperson%3AK1RwyVNukt?q=member

    Sample Response

    {
    "elements": [
        {
            "account": "urn:li:sponsoredAccount:516413367",
            "member": "urn:li:person:K1RwyVNukt",
            "state": "APPROVED"
        },
        {
            "account": "urn:li:sponsoredAccount:516986977",
            "member": "urn:li:person:K1RwyVNukt",
            "state": "APPROVED"
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

    A 400 Bad Request with reason=NO_PERMISSION_ON_ENTITY is returned if the requesting member does not have access to view another member's sender permissions across all accounts. This leads to an Access Permission error response due to NO_PERMISSION_ON_ENTITY message.

    For more details, refer to the following documentation: