Share via

Validation Status API (/validationStatus)

The Validation Status API (/validationStatus) allows enterprise partners to retrieve the current validation status of LinkedIn members at scale. This API is optimized for bulk or single-member checks and provides validation results across three categories.

Important

Plus Tier Only: This API is exclusively available to Plus tier partners.

Tier Availability: Development ❌ | Lite ❌ | Plus ✅

Overview

Key Features:

  • Check validation status for up to 500 members per request
  • No member consent required (2-legged OAuth)
  • Get identity, workplace, and profile information status
  • OAuth: 2-legged (application-level authorization)
  • Version: 202510

Validation Categories

Category Description Possible Values
identity Government ID verification status VALID, INVALID, VALID_WITH_UPDATES
workplace Work affiliation verification status VALID, INVALID, VALID_WITH_UPDATES
profileInformationStatus Profile data validation status VALID, INVALID

Important

This API uses 2-legged OAuth and does NOT require member interaction or consent. You can call this endpoint directly to validate existing member data at scale.

Key Differences from Other APIs

Feature /validationStatus /verificationReport /identityMe
OAuth Type 2-legged (application) 3-legged (member) 3-legged (member)
Member Consent ❌ Not required ✅ Required ✅ Required
Use Case Bulk validation checks Individual verification details Individual profile details
Batch Support ✅ Up to 500 members ❌ Single member ❌ Single member
Returns Validation status Detailed verification metadata Profile information
Token Lifetime 30 minutes 60 days 60 days

Tip

Use Case: Use this API to check if any of your members' profile or verification information has changed. This allows you to efficiently identify which members need data refreshes, then pull only the changed member data using /verificationReport and /identityMe.

See the Data Freshness Guide for complete implementation patterns.

Prerequisites

Before using this API, ensure you're using the latest versions of related APIs to get the required id field:

  • /identityMe – Version 202510.03 or later
  • /verificationReport – Version 202510 or later

Warning

The id field returned by these endpoints is required for validation checks. Without upgrading to these versions, you cannot use the Validation Status API.

Authentication: 2-Legged OAuth

This API requires an application-level access token obtained through OAuth 2.0 Client Credentials flow.

Key Characteristics

  • No member consent required – Application acts on its own behalf
  • Scope: r_validation_status
  • Token validity: 30 minutes
  • No refresh token issued – Request new token after expiry

Get Access Token

curl -X POST 'https://www.linkedin.com/oauth/v2/accessToken' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
  --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
  --data-urlencode 'scope=r_validation_status'

Sample Response:

{
  "access_token": "AQVjYwl_Z-PJW2bChvx9ewKy3hrkQtJuM70LOj17...",
  "expires_in": 1799
}

Tip

Request a new access token every 25 minutes to avoid expiry during API calls. Implement token caching and refresh logic in your application.

For complete OAuth details, see the Client Credentials Flow Guide.

Rate Limits

Limit Type Default Description
Application-level 5,000 requests/day Maximum API calls per day
Member-level 500 requests/day Maximum checks per individual member per day

Note

Rate limits may be customized based on your partnership agreement. Contact your LinkedIn Partner Solutions Engineer for details.

Endpoint Details

POST https://api.linkedin.com/rest/validationStatus?action=retrieve

Required Headers

Header Value Description
Authorization Bearer {ACCESS_TOKEN} 2-legged OAuth access token
LinkedIn-Version 202510 API version
Content-Type application/json Request body format

Request Body

{
  "validationQueries": [
    {
      "id": "string"
    }
  ]
}
Field Type Required Description
validationQueries array Yes Array of validation requests (max 500)
validationQueries[].id string Yes Member identifier from /identityMe or /verificationReport

Important

  • Maximum 500 queries per request
  • Use the id field from /identityMe or /verificationReport responses
  • Each unique member ID counts toward member-level rate limits

Example Request and Response

Single Member Validation

Request:

curl -X POST 'https://api.linkedin.com/rest/validationStatus?action=retrieve' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'LinkedIn-Version: 202510' \
  -H 'Content-Type: application/json' \
  -d '{
    "validationQueries": [
      {"id": "abc123"}
    ]
  }'

Response:

{
  "value": [
    {
      "id": "abc123",
      "verificationStatus": {
        "identity": "VALID",
        "workplace": "VALID"
      },
      "profileInformationStatus": "VALID"
    }
  ]
}

Bulk Member Validation

Request:

curl -X POST 'https://api.linkedin.com/rest/validationStatus?action=retrieve' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'LinkedIn-Version: 202510' \
  -H 'Content-Type: application/json' \
  -d '{
    "validationQueries": [
      {"id": "abc123"},
      {"id": "def456"},
      {"id": "ghi789"}
    ]
  }'

Response:

{
  "value": [
    {
      "id": "abc123",
      "verificationStatus": {
        "identity": "VALID",
        "workplace": "VALID_WITH_UPDATES"
      },
      "profileInformationStatus": "VALID"
    },
    {
      "id": "def456",
      "verificationStatus": {
        "identity": "INVALID",
        "workplace": "VALID"
      },
      "profileInformationStatus": "INVALID"
    },
    {
      "id": "ghi789",
      "verificationStatus": {
        "identity": "VALID",
        "workplace": "VALID"
      },
      "profileInformationStatus": "VALID"
    }
  ]
}

Response Schema

Top-Level Fields

Field Type Description
value array of objects List of validation results (one per member)

Validation Result Object

Field Type Description
id string Member identifier (same as submitted in request)
verificationStatus object Identity and workplace verification status
profileInformationStatus string Profile data validation status

verificationStatus Object

Field Type Description
identity string Identity verification status: VALID, INVALID, or VALID_WITH_UPDATES
workplace string Workplace verification status: VALID, INVALID, or VALID_WITH_UPDATES

Status Values Explained

Value Applies To Description Action Required
VALID All fields Information is current and valid No action needed
INVALID All fields Information is no longer valid (verification removed or expired) Fetch fresh data via /verificationReport and /identityMe
VALID_WITH_UPDATES identity, workplace Information is valid, but updates are available (new verifications added or existing re-verified) Fetch updated data if you need the latest verification details

Decision Logic

// Example: Determine which members need data refresh
results.value.forEach(member => {
  const { id, verificationStatus, profileInformationStatus } = member;
  
  // Check if any verification changed
  if (verificationStatus.identity === 'INVALID' || 
      verificationStatus.identity === 'VALID_WITH_UPDATES' ||
      verificationStatus.workplace === 'INVALID' ||
      verificationStatus.workplace === 'VALID_WITH_UPDATES') {
    // Fetch fresh verification data
    refreshVerificationData(id);
  }
  
  // Check if profile changed
  if (profileInformationStatus === 'INVALID') {
    // Fetch fresh profile data
    refreshProfileData(id);
  }
});

Best Practices

Token Management

✅ Cache tokens - Don't request new tokens for every API call
✅ Refresh proactively - Get new token at 25 minutes (before 30-minute expiry)
✅ Handle 401 errors gracefully - Automatically retry with fresh token

Batching Strategy

✅ Batch up to 500 members - Maximize efficiency by filling each request
✅ Parallel requests - Send multiple batches in parallel for large datasets
✅ Respect rate limits - Track daily and per-member limits

Data Freshness Workflow

  1. Daily validation - Run bulk validation once per day for all members
  2. Identify changes - Filter members with INVALID or VALID_WITH_UPDATES status
  3. Fetch fresh data - Call /verificationReport and /identityMe only for changed members
  4. Update database - Store latest verification and profile data

Tip

This approach reduces 3-legged OAuth API calls by 95% compared to polling all members daily.

Error Handling

✅ Validate id format before sending requests
✅ Handle partial failures gracefully (some IDs may be invalid)
✅ Implement exponential backoff for 500 errors
✅ Log failed IDs for investigation

Error Handling

API-Specific Errors

HTTP Status Error Code Error Message Cause Solution
400 S_400_BAD_REQUEST "Validation status request array cannot be null or empty" Empty validationQueries array Include at least one validation query
400 S_400_BAD_REQUEST "Validation status request array size ({size}) exceeds maximum limit of 500" Request exceeds 500 items Split into multiple requests with max 500 queries each
400 S_400_BAD_REQUEST "Invalid personId: {personId}" Invalid or malformed member ID Use valid id from /identityMe or /verificationReport
400 S_400_BAD_REQUEST "API version is not available in the request" Missing or invalid LinkedIn-Version header Include LinkedIn-Version: 202510 header
401 - Unauthorized Invalid or expired 2-legged token Request new token using client credentials flow
403 - Access denied r_validation_status permission not enabled Contact LinkedIn Partner Solutions Engineer
429 - Too Many Requests Rate limit exceeded Retry after delay; check Retry-After header
500 S_500_INTERNAL_SERVER_ERROR "Failed to get validation status response" Downstream service failure Retry with exponential backoff; contact support if persists

For additional error handling guidance, see the LinkedIn API Error Handling Guide.

Note

If you receive a 403 "access denied" error, contact your LinkedIn Partner Solutions Engineer to enable the r_validation_status permission for your application.

Common Use Cases

1. Daily Data Freshness Check

Validate all members once per day to identify who needs data refresh:

// Step 1: Get all member IDs from your database
const allMemberIds = await db.getAllMemberIds();

// Step 2: Batch into groups of 500
const batches = chunk(allMemberIds, 500);

// Step 3: Validate each batch
const validationResults = await Promise.all(
  batches.map(batch => validateMembers(batch))
);

// Step 4: Identify members needing refresh
const membersToRefresh = validationResults
  .flat()
  .filter(m => 
    m.verificationStatus.identity !== 'VALID' ||
    m.verificationStatus.workplace !== 'VALID' ||
    m.profileInformationStatus === 'INVALID'
  );

// Step 5: Refresh only changed members
await refreshMemberData(membersToRefresh);

2. Pre-Transaction Validation

Validate member data before critical transactions:

// Before processing payment or granting access
const validation = await validateMember(memberId);

if (validation.verificationStatus.identity === 'INVALID') {
  // Identity no longer valid - require re-verification
  return redirectToReVerification(memberId);
}

if (validation.verificationStatus.workplace === 'INVALID') {
  // Workplace verification removed - update member status
  await updateMemberWorkplaceStatus(memberId, 'unverified');
}

// Proceed with transaction

3. Compliance Audit Trail

Track verification status changes over time:

// Daily compliance check
const results = await bulkValidateMembers(allMemberIds);

// Store validation results with timestamp
await db.saveValidationSnapshot({
  timestamp: Date.now(),
  results: results,
  summary: {
    totalMembers: results.length,
    validMembers: results.filter(r => r.verificationStatus.identity === 'VALID').length,
    invalidMembers: results.filter(r => r.verificationStatus.identity === 'INVALID').length,
    updatedMembers: results.filter(r => r.verificationStatus.identity === 'VALID_WITH_UPDATES').length
  }
});

APIs

Guides

Other Resources

  • Last updated on