DMP Segment Users
Warning
Deprecation Notice
The Marketing Version 202310 (Marketing October 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will 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.
DMP Segment Users is a sub-resource of DMP segments and lets you 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 you create a DMP segment, you must wait 5 seconds for the segment to be available to add users.
Permissions
| Permission | Description |
|---|---|
| rw_dmp_segments | Access an authenticated member's DMP Segments. Can manage and read audience DMP segments. This permission belongs to the Audiences program and is not granted automatically as part of the LinkedIn Marketing API Program. Managing audiences is restricted to ad accounts in which the authenticated member has a role other than VIEWER. |
Rate Limits
Starting October 31, 2022, we will be introducing 1 minute per user (a.k.a member) rate limits for our DMP streaming APIs (Users & Companies to prevent abuse, ensure service stability, and consistent API availability. These limits will be enforced in addition to your current daily limits, which can be found through Developer Portal > My Apps > App > Analytics > Quotas and usage.
For the /users endpoint, an application will have a 1 minute limit of 500 requests per user. This means, that at any given minute, an application can make up to 500 requests on behalf of a single user.
If your application calls /dmpSegments/users or /dmpSegments/companies, you may get an HTTP 429 response if calling the endpoints too frequently, indicating that you are exceeding the rate limits.
If your application makes a large amount of automated data pushes, you can expect frequent throttling. While this might affect the throughput of your API calls, you will not see any differences in the matched audience processing SLA.
To understand how to handle these rate limits see the FAQ
Add or Remove a User
Add or remove a single user from a DMP Segment.
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 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 max length 35 characters representing the first name of the contact to match e.g. Mike | |
| lastName | String (optional) | A plain text string with max length 35 characters representing the last name of the contact to match e.g. Smith | |
| title | String (optional) | A plain text string with max length 100 characters representing the title name of the contact to match e.g. Software Engineer | |
| company | String (optional) | A plain text string with max length 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:
- Convert all the Email addresses to lowercase.
- Remove any whitespace in the Email address and then generate hash.
Input data requirements
An input request will be validated and it will fail if the following validation rules are not met:
- All IDs provided by 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
- All userIds provided must not contain raw email address in plain text format (including in firstName and lastName)
Sample Request
Sample Request
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"
}
POST https://api.linkedin.com/v2/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"
}
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.
Sample Request
POST https://api.linkedin.com/rest/dmpSegments/10804/users
{
"elements": [
{
"action": "ADD",
"userIds": [
{
"idType": "SHA256_EMAIL",
"idValue": "692682111bc191d915ac7009d118a78bc496cf7a2ba8c2d0134ade012ac1234"
}
]
},
{
"action": "ADD",
"userIds": [
{
"idType": "SHA256_EMAIL",
"idValue": "09d118a78b692682111bc15ac70c496cf7a9e0502ba8c2d016f2f1f7a2ba8c2"
}
]
}
]
}
POST https://api.linkedin.com/rest/dmpSegments/10804/users
{
"elements": [
{
"action": "ADD",
"userIds": [
{
"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"
}
]
}
POST https://api.linkedin.com/v2/dmpSegments/10804/users
{
"elements": [
{
"action": "ADD",
"userIds": [
{
"idType": "SHA256_EMAIL",
"idValue": "692682111bc191d915ac7009d118a78bc496cf7a2ba8c2d0134ade012ac1234"
}
]
},
{
"action": "ADD",
"userIds": [
{
"idType": "SHA256_EMAIL",
"idValue": "09d118a78b692682111bc15ac70c496cf7a9e0502ba8c2d016f2f1f7a2ba8c2"
}
]
}
]
}
POST https://api.linkedin.com/v2/dmpSegments/10804/users
{
"elements": [
{
"action": "ADD",
"userIds": [
{
"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 is incorrect. The error message contains a reference to batchIndex, with the index of the element that caused the error.
{
"serviceErrorCode": 10007,
"message": "Validation failed because [{field=userIds, batchIndex=1, type=MISSING_REQUIRED_FIELD, message=ERROR :: /userIds/idType :: \"GOOGLE\" is not an enum symbol}]",
"status": 400
}