DMP Segment Users

Warning

Deprecation Notice
The Marketing Version 202402 (Marketing February 2024) has been sunset. 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.

DMP Segment Users is a sub-resource of DMP segments that allows you to add users to a DMP Segment.

The use of this API is restricted to those developers approved by LinkedIn and subject to applicable data restrictions in their agreements.

Note

After creating a DMP segment, wait 5 seconds for it to become available before adding users.

Permissions

Permission	Description
rw_dmp_segments	Access an authenticated member's DMP Segments to read and manage audience DMP segments. This permission is part of the Audiences program and is not granted automatically under the LinkedIn Marketing API Program. Managing audiences is restricted to ad accounts where the authenticated member has a role other than VIEWER.

Rate Limits

Since October 31, 2022, we have introduced a 1 minute rate limit per user (member) for our DMP streaming APIs Users & Companies to prevent abuse, ensure service stability, and consistent API availability. These limits are enforced in addition to your existing daily limits per user and per app, which can be found in the Developer Portal > My Apps > App > Analytics > Quotas and usage.

For the /users endpoint, an application will have a 1 minute limit of 600 requests per user. This means an application can make up to 600 requests per user within a minute.

If your application calls /dmpSegments/users or /dmpSegments/companies too frequently, you may get an HTTP 429 response, indicating that you have exceeded the rate limits.

If your application performs a high volume of automated data pushes, frequent throttling may occur. While this could impact API call throughput, it will not affect the matched audience processing SLA.

To understand how to handle these rate limits see the FAQ

Schema

Field Name	Sub-Field	Type	Description
action		string	The action to take on this entity: ADD or REMOVE.
	idType	IdType	Type of this ID. All IDs of a given type must use the same format/encoding.
	idValue	string	An opaque ID in a type-specific format.
userIds		List[TypedId] (optional)	List of ID to match.
	idType	IdType	Type of this ID. All IDs of a given type must use the same format/encoding.
	idValue	string	An opaque ID in type-specific format.
firstName		String (optional)	A plain text string with a maximum length of 35 characters representing the first name of the contact to match, e.g., Mike.
lastName		String (optional)	A plain text string with a maximum length of 35 characters representing the last name of the contact to match, e.g., Smith.
title		String (optional)	A plain text string with a maximum length of 100 characters representing the title name of the contact to match, e.g., Software Engineer.
company		String (optional)	A plain text string with a maximum length of 50 characters representing the company name of the contact to match, e.g., Microsoft Corporation.
country		String (optional)	ISO-standardized two letter country code, e.g., US.

IdTypes

The following idType values are supported.

Symbol	Description
SHA256_EMAIL	A HEX encoded string with a maximum length of 64 characters. For example, 692682111bc191d915ac7009d118a78bc496cf7a2ba8c2d0134ade012ac1234
SHA512_EMAIL	A HEX encoded string with a maximum length of 128 characters. For example, 09d118a78b692682111bc15ac70c496cf7a9e0502ba8c2d016f2f496cf7a2ba8c1....
GOOGLE_AID	A plain text string with a maximum length of 32 characters and all in lower case. For example, cdda802e-fb9c-47ad-0794d394c912....

Email Hashing Guideline

The following guidelines must be followed for Email hashing:

1. Convert all email addresses to lowercase.
2. Remove any whitespace from the email address before generating the hash.

Input data requirements

An input request will be validated and will fail if the following validation rules are not met:

• All IDs provided in the userIds fields must have a supported type and valid value
• An input request must provide:
  • At least one valid ID Or
  • A valid firstName and lastName
• Raw plain text email addresses must not be included in the userIds field or in the firstName and lastName fields.

Add or Remove a User

Add or remove a single user from a DMP Segment. Send all available user identifiers to increase the match rates.

Sample Request

http

POST https://api.linkedin.com/rest/dmpSegments/10804/users

{
    "action": "ADD",
    "userIds": [
      {
        "idType": "SHA256_EMAIL",
        "idValue": "09d118a78b69261bc191d915ac70c496cf7a9e0502ba8c2d016f2f134ade"
      },
      {
        "idType": "GOOGLE_AID",
        "idValue": "cdda802e-fb9c-47ad-0794d394c912"
      }
    ],
    "firstName": "mike",
    "lastName": "smith",
    "title": "software engineer",
    "company": "microsoft",
    "country": "us"
}

curl

curl -X POST 'https://api.linkedin.com/rest/dmpSegments/10804/users' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' \ 
-H 'X-Restli-Protocol-Version: 2.0.0'
--data '{
    "action": "ADD",
    "userIds": [
      {
        "idType": "SHA256_EMAIL",
        "idValue": "09d118a78b69261bc191d915ac70c496cf7a9e0502ba8c2d016f2f134ade"
      },
      {
        "idType": "GOOGLE_AID",
        "idValue": "cdda802e-fb9c-47ad-0794d394c912"
      }
    ],
    "firstname": "mike",
    "lastname": "smith",
    "titleName": "software engineer",
    "companyName": "microsoft",
    "countryName": "us"
}'

A successful response returns a 201 Created HTTP status code.

Note

A 201 Created HTTP status code is returned if you add the same ID again or remove an already deleted ID. This is by design. A 400 Bad Request is returned if the request does not pass the validation check. Please check the error message to understand what validation failed

Add or Remove Multiple Users

Add or remove multiple users from a DMP Segment by passing the X-RestLi-Method: BATCH_CREATE header. This method is more efficient than sending multiple requests to add or remove users one at a time. You may stream up to 5000 users in a single batch request. If you see issues with your batch request responses, you may try to resubmit with smaller batch size.

Sample Request

http

POST https://api.linkedin.com/rest/dmpSegments/10804/users
-H 'X-RestLi-Method: BATCH_CREATE'

{
    "elements": [
        {
            "action": "ADD",
            "userIds": [
              {
                "idType": "SHA256_EMAIL",
                "idValue": "692682111bc191d915ac7009d118a78bc496cf7a2ba8c2d0134ade012ac1234"
              },
              {
                "idType": "GOOGLE_AID",
                "idValue": "cffg876e-gm9v-98de-0013d927s873"
              }
            ],
        },
        {
            "action": "ADD",
            "userIds": [
              {
                "idType": "SHA256_EMAIL",
                "idValue": "09d118a78b69261bc191d915ac70c496cf7a9e0502ba8c2d016f2f134ade"
              },
              {
                "idType": "GOOGLE_AID",
                "idValue": "cdda802e-12cd-fb9c-47ad-0794d394c912"
              }
            ],
            "firstname": "mike",
            "lastname": "smith"
        }
    ]
}

curl

curl -X POST 'https://api.linkedin.com/rest/dmpSegments/10804/users' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' \ 
-H 'X-Restli-Protocol-Version: 2.0.0'
--data '{
    "elements": [
        {
            "action": "ADD",
            "userIds": [
              {
                "idType": "SHA256_EMAIL",
                "idValue": "692682111bc191d915ac7009d118a78bc496cf7a2ba8c2d0134ade012ac1234"
              },
              {
                "idType": "GOOGLE_AID",
                "idValue": "cffg876e-gm9v-98de-0013d927s873"
              }
            ]
        },
        {
            "action": "ADD",
            "userIds": [
              {
                "idType": "SHA256_EMAIL",
                "idValue": "09d118a78b69261bc191d915ac70c496cf7a9e0502ba8c2d016f2f134ade"
              },
              {
                "idType": "GOOGLE_AID",
                "idValue": "cdda802e-12cd-fb9c-47ad-0794d394c912"
              }
            ],
            "firstname": "mike",
            "lastname": "smith"
        }
    ]
}'

A 400 Bad Request is returned if the request syntax is incorrect. For correct syntax, we return a batch response array with HTTP response status for each element in the batch, including 201 status for success and 400 status for error. If error, message contains a reference to batchIndex to specify the exact index of the invalid element in the array that caused the error.

{
  "serviceErrorCode": 10007,
  "message": "Validation failed because [{field=userIds, batchIndex=0, type=MISSING_REQUIRED_FIELD, message=ERROR :: /userIds/idType :: \"GOOGLE\" is not an enum symbol}]",
  "status": 400
}

{
"elements":
  [ 
    {"error":
      {"message":"Validation failed because [{reason=CONDITIONAL_INVALID_VALUE, field=/userIds, batchIndex=0, type=INVALID_VALUE, 
                  message=/idValue cannot be set to <REDACTED> if /idType is set to SHA256_EMAIL, 
                  parameters={reason=The provided id '' of type SHA256_EMAIL did not match the corresponding regex Optional[^[a-fA-F0-9=\\+\\_\\-]{64}$], 
                  field1=/idValue, value2=SHA256_EMAIL, value1=<REDACTED>, field2=/idType}}]",
        "status":400},
     "status":400
    },
    {"status":201}
  ]
}

{
"elements":
  [ 
    {
	    "status":201
    },
    {
      "status":201
    }
  ]
}