api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "results": {
          "description": "Per-URL profile lookup results.",
          "items": {
            "description": "LinkedIn profile lookup result for one requested URL.",
            "properties": {
              "activity": {
                "description": "Recent public activities from the profile when available.",
                "items": {
                  "description": "A recent public activity item from the profile.",
                  "properties": {
                    "id": {
                      "description": "Stable activity id for this item when available.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "interactionType": {
                      "description": "Interaction label when available.",
                      "nullable": true,
                      "type": "string"
                    },
                    "publishedAt": {
                      "description": "Publication timestamp in ISO-8601 format when provided by the source.",
                      "nullable": true,
                      "type": "string"
                    },
                    "thumbnailUrl": {
                      "description": "Thumbnail image URL when available.",
                      "nullable": true,
                      "type": "string"
                    },
                    "title": {
                      "description": "Primary text or headline for the activity.",
                      "nullable": true,
                      "type": "string"
                    },
                    "url": {
                      "description": "Public URL for this activity.",
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "url",
                    "title",
                    "interactionType",
                    "thumbnailUrl",
                    "publishedAt"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "error": {
                "description": "Error details when `lookupStatus` is `error`.",
                "nullable": true,
                "properties": {
                  "message": {
                    "description": "Short customer-safe reason this profile could not be returned.",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "message"
                ],
                "type": "object"
              },
              "lookupStatus": {
                "description": "Whether this profile was resolved.",
                "enum": [
                  "found",
                  "not_found",
                  "error"
                ],
                "type": "string"
              },
              "metrics": {
                "description": "Profile metrics when available.",
                "nullable": true,
                "properties": {
                  "connections": {
                    "description": "Connection count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "followers": {
                    "description": "Follower count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  },
                  "recommendationsCount": {
                    "description": "Recommendation count when available.",
                    "minimum": 0,
                    "nullable": true,
                    "type": "integer"
                  }
                },
                "required": [
                  "followers",
                  "connections",
                  "recommendationsCount"
                ],
                "type": "object"
              },
              "posts": {
                "description": "Authored posts from the profile when available.",
                "items": {
                  "description": "An authored LinkedIn post from the profile.",
                  "properties": {
                    "excerpt": {
                      "description": "Post excerpt when available.",
                      "nullable": true,
                      "type": "string"
                    },
                    "id": {
                      "description": "Stable post id when available.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "interaction": {
                      "description": "Engagement summary when available.",
                      "nullable": true,
                      "type": "string"
                    },
                    "publishedAt": {
                      "description": "Publication timestamp when available.",
                      "nullable": true,
                      "type": "string"
                    },
                    "title": {
                      "description": "Post title when available.",
                      "nullable": true,
                      "type": "string"
                    },
                    "url": {
                      "description": "Public URL for this authored post.",
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "url",
                    "title",
                    "excerpt",
                    "publishedAt",
                    "interaction"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "profile": {
                "description": "Profile details when available.",
                "nullable": true,
                "properties": {
                  "avatarUrl": {
                    "description": "Best available square avatar image URL when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "bannerUrl": {
                    "description": "Profile banner image URL when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "bio": {
                    "description": "Profile summary or about text when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "certifications": {
                    "description": "Certification entries when available.",
                    "items": {
                      "description": "Generic titled profile entry.",
                      "properties": {
                        "meta": {
                          "description": "Additional metadata when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "subtitle": {
                          "description": "Secondary label when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "title": {
                          "description": "Entry title.",
                          "minLength": 1,
                          "type": "string"
                        }
                      },
                      "required": [
                        "title",
                        "subtitle",
                        "meta"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "city": {
                    "description": "City label when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "countryCode": {
                    "description": "ISO country code when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "courses": {
                    "description": "Course entries when available.",
                    "items": {
                      "description": "Generic titled profile entry.",
                      "properties": {
                        "meta": {
                          "description": "Additional metadata when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "subtitle": {
                          "description": "Secondary label when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "title": {
                          "description": "Entry title.",
                          "minLength": 1,
                          "type": "string"
                        }
                      },
                      "required": [
                        "title",
                        "subtitle",
                        "meta"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "currentCompany": {
                    "description": "Current company details when available.",
                    "nullable": true,
                    "properties": {
                      "companyId": {
                        "description": "LinkedIn company slug when available.",
                        "nullable": true,
                        "type": "string"
                      },
                      "location": {
                        "description": "Current company location label when available.",
                        "nullable": true,
                        "type": "string"
                      },
                      "name": {
                        "description": "Current company name when available.",
                        "nullable": true,
                        "type": "string"
                      },
                      "title": {
                        "description": "Current role title at the company when available.",
                        "nullable": true,
                        "type": "string"
                      },
                      "url": {
                        "description": "LinkedIn company URL when available.",
                        "nullable": true,
                        "type": "string"
                      }
                    },
                    "required": [
                      "name",
                      "companyId",
                      "title",
                      "url",
                      "location"
                    ],
                    "type": "object"
                  },
                  "defaultAvatar": {
                    "description": "Whether the avatar is LinkedIn's default placeholder.",
                    "nullable": true,
                    "type": "boolean"
                  },
                  "displayName": {
                    "description": "Public display name on the profile when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "education": {
                    "description": "Education entries when available.",
                    "items": {
                      "description": "One education entry.",
                      "properties": {
                        "description": {
                          "description": "Education description when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "endYear": {
                          "description": "End year when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "startYear": {
                          "description": "Start year when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "title": {
                          "description": "School or program name when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "url": {
                          "description": "School URL when available.",
                          "nullable": true,
                          "type": "string"
                        }
                      },
                      "required": [
                        "title",
                        "url",
                        "startYear",
                        "endYear",
                        "description"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "experience": {
                    "description": "Work experience entries when available.",
                    "items": {
                      "description": "One work experience entry.",
                      "properties": {
                        "company": {
                          "description": "Company name when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "companyLogoUrl": {
                          "description": "Company logo URL when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "description": {
                          "description": "Role description when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "endDate": {
                          "description": "End date label when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "startDate": {
                          "description": "Start date label when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "title": {
                          "description": "Role title when available.",
                          "nullable": true,
                          "type": "string"
                        }
                      },
                      "required": [
                        "title",
                        "company",
                        "companyLogoUrl",
                        "description",
                        "startDate",
                        "endDate"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "firstName": {
                    "description": "First name when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "handle": {
                    "description": "LinkedIn public profile handle without the leading @.",
                    "type": "string"
                  },
                  "headline": {
                    "description": "Profile headline or position line when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "honorsAndAwards": {
                    "description": "Honors and awards text entries when available.",
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "influencer": {
                    "description": "Whether LinkedIn marks this profile as an influencer.",
                    "nullable": true,
                    "type": "boolean"
                  },
                  "languages": {
                    "description": "Language entries when available.",
                    "items": {
                      "description": "One language entry.",
                      "properties": {
                        "name": {
                          "description": "Language name.",
                          "minLength": 1,
                          "type": "string"
                        },
                        "proficiency": {
                          "description": "Proficiency label when available.",
                          "nullable": true,
                          "type": "string"
                        }
                      },
                      "required": [
                        "name",
                        "proficiency"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "lastName": {
                    "description": "Last name when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "location": {
                    "description": "Location label when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "memorialized": {
                    "description": "Whether this is a memorialized account.",
                    "nullable": true,
                    "type": "boolean"
                  },
                  "numericId": {
                    "description": "LinkedIn numeric profile id when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "organizations": {
                    "description": "Organization memberships when available.",
                    "items": {
                      "description": "One organization membership entry.",
                      "properties": {
                        "endDate": {
                          "description": "End date when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "membershipType": {
                          "description": "Membership type or role when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "startDate": {
                          "description": "Start date when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "title": {
                          "description": "Organization name.",
                          "minLength": 1,
                          "type": "string"
                        }
                      },
                      "required": [
                        "title",
                        "membershipType",
                        "startDate",
                        "endDate"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "platform": {
                    "description": "Social platform for this profile.",
                    "enum": [
                      "linkedin"
                    ],
                    "type": "string"
                  },
                  "profileUrl": {
                    "description": "Canonical public LinkedIn profile URL for this handle.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "projects": {
                    "description": "Project entries when available.",
                    "items": {
                      "description": "One project entry.",
                      "properties": {
                        "description": {
                          "description": "Project description when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "startDate": {
                          "description": "Start date when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "title": {
                          "description": "Project title.",
                          "minLength": 1,
                          "type": "string"
                        }
                      },
                      "required": [
                        "title",
                        "startDate",
                        "description"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "publications": {
                    "description": "Publication entries when available.",
                    "items": {
                      "description": "One publication entry.",
                      "properties": {
                        "date": {
                          "description": "Publication date when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "publisher": {
                          "description": "Publisher when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "title": {
                          "description": "Publication title.",
                          "minLength": 1,
                          "type": "string"
                        }
                      },
                      "required": [
                        "title",
                        "publisher",
                        "date"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "recommendations": {
                    "description": "Recommendation text entries when available.",
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "volunteerExperience": {
                    "description": "Volunteer experience entries when available.",
                    "items": {
                      "description": "Generic titled profile entry.",
                      "properties": {
                        "meta": {
                          "description": "Additional metadata when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "subtitle": {
                          "description": "Secondary label when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "title": {
                          "description": "Entry title.",
                          "minLength": 1,
                          "type": "string"
                        }
                      },
                      "required": [
                        "title",
                        "subtitle",
                        "meta"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "websites": {
                    "description": "External websites linked from the profile.",
                    "items": {
                      "description": "External website linked from the profile.",
                      "properties": {
                        "title": {
                          "description": "Website label when available.",
                          "nullable": true,
                          "type": "string"
                        },
                        "url": {
                          "description": "External website URL.",
                          "minLength": 1,
                          "type": "string"
                        }
                      },
                      "required": [
                        "title",
                        "url"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "platform",
                  "handle",
                  "numericId",
                  "displayName",
                  "firstName",
                  "lastName",
                  "headline",
                  "bio",
                  "avatarUrl",
                  "bannerUrl",
                  "profileUrl",
                  "location",
                  "city",
                  "countryCode",
                  "influencer",
                  "memorialized",
                  "defaultAvatar",
                  "currentCompany",
                  "websites",
                  "experience",
                  "education",
                  "languages",
                  "organizations",
                  "publications",
                  "projects",
                  "honorsAndAwards",
                  "recommendations",
                  "certifications",
                  "courses",
                  "volunteerExperience"
                ],
                "type": "object"
              },
              "relatedProfiles": {
                "description": "Related profile suggestions when available.",
                "items": {
                  "description": "A related profile suggestion.",
                  "properties": {
                    "headline": {
                      "description": "Related profile headline when available.",
                      "nullable": true,
                      "type": "string"
                    },
                    "location": {
                      "description": "Related profile location when available.",
                      "nullable": true,
                      "type": "string"
                    },
                    "name": {
                      "description": "Related profile display name.",
                      "minLength": 1,
                      "type": "string"
                    },
                    "url": {
                      "description": "Related profile URL.",
                      "minLength": 1,
                      "type": "string"
                    }
                  },
                  "required": [
                    "url",
                    "name",
                    "headline",
                    "location"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "url": {
                "description": "Requested profile URL echoed for this result.",
                "minLength": 1,
                "type": "string"
              }
            },
            "required": [
              "url",
              "lookupStatus",
              "error",
              "profile",
              "metrics",
              "activity",
              "posts",
              "relatedProfiles"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "summary": {
          "description": "Summary counts for the profile batch.",
          "properties": {
            "errored": {
              "description": "Number of profiles that failed to resolve.",
              "minimum": 0,
              "type": "integer"
            },
            "found": {
              "description": "Number of profiles successfully found.",
              "minimum": 0,
              "type": "integer"
            },
            "notFound": {
              "description": "Number of profiles that were not found.",
              "minimum": 0,
              "type": "integer"
            },
            "requestedUrls": {
              "description": "Number of profile URLs requested in this batch.",
              "minimum": 0,
              "type": "integer"
            }
          },
          "required": [
            "requestedUrls",
            "found",
            "notFound",
            "errored"
          ],
          "type": "object"
        }
      },
      "required": [
        "results",
        "summary"
      ],
      "type": "object"
    },
    "meta": {
      "description": "Metadata describing the request and billing outcome.",
      "properties": {
        "cached": {
          "description": "True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.",
          "type": "boolean"
        },
        "creditsCharged": {
          "description": "Credits charged for this request.",
          "minimum": 0,
          "type": "integer"
        },
        "requestId": {
          "description": "Unique request identifier for tracing this API call.",
          "minLength": 1,
          "type": "string"
        },
        "version": {
          "description": "Public API version that served the response.",
          "enum": [
            "v1"
          ],
          "type": "string"
        }
      },
      "required": [
        "requestId",
        "creditsCharged",
        "version"
      ],
      "type": "object"
    }
  },
  "required": [
    "data",
    "meta"
  ],
  "type": "object"
}