{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/datacircle/main/json-schema/datacircle-up2-data-enrich-response-schema.json",
  "title": "Up2DataEnrichResponse",
  "description": "Up2Data's own response to `POST /v1/profiles/enrich`, plus `datacircle_meta`",
  "x-generated": "2026-10-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/datacircle-up2data-api-openapi.yml#/components/schemas/Up2DataEnrichResponse",
  "type": "object",
  "required": [
    "data",
    "meta",
    "datacircle_meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/$defs/Up2DataProfile"
    },
    "meta": {
      "$ref": "#/$defs/Up2DataMeta"
    },
    "datacircle_meta": {
      "$ref": "#/$defs/DatacircleMeta"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "DatacircleMeta": {
      "type": "object",
      "description": "Datacircle's only addition to the provider's answer",
      "required": [
        "provider",
        "cost_usd",
        "balance_usd"
      ],
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "up2data",
            "harvestapi",
            "fetchin"
          ],
          "description": "Which provider answered"
        },
        "cost_usd": {
          "type": "number",
          "description": "What this call cost, in dollars: the provider's price, no markup"
        },
        "balance_usd": {
          "type": "number",
          "description": "Your balance after this call, in dollars (`balance_usd` in `GET /balance/`)"
        }
      },
      "additionalProperties": false
    },
    "Up2DataMeta": {
      "type": "object",
      "description": "Up2Data's billing metadata, minus `creditsRemaining`, `requestId` and `latencyMs` (our account with Up2Data, not yours)",
      "properties": {
        "creditsUsed": {
          "type": "integer",
          "description": "Up2Data credits this call used (1 per profile found). What it costs you is `datacircle_meta.cost_usd`: $0.002375 per Up2Data credit"
        },
        "billed": {
          "type": "boolean",
          "description": "Whether Up2Data billed this call (`false`: it didn't, and you weren't charged). What this call costs you is `datacircle_meta.cost_usd`"
        },
        "reason": {
          "type": "string",
          "description": "Why Up2Data billed this call or not, in its words, e.g. `profile_found`."
        }
      },
      "additionalProperties": false
    },
    "Up2DataProfile": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "Canonical profile URL."
        },
        "public_identifier": {
          "type": "string",
          "description": "The profile's slug: linkedin.com/in/<public_identifier>."
        },
        "linkedin_id": {
          "type": "string",
          "description": "Numeric LinkedIn member ID."
        },
        "full_name": {
          "type": "string",
          "description": "The member's full name."
        },
        "first_name": {
          "type": "string",
          "description": "The member's first name."
        },
        "last_name": {
          "type": "string",
          "description": "The member's last name."
        },
        "headline": {
          "type": "string",
          "description": "The line under the member's name on the profile."
        },
        "location": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City."
            },
            "region": {
              "type": "string",
              "description": "State or region."
            },
            "country": {
              "type": "string",
              "description": "Country name (e.g. `United States`)."
            },
            "raw": {
              "type": "string",
              "description": "The location exactly as LinkedIn shows it (e.g. \"Greater Seattle Area\"), before parsing."
            }
          },
          "additionalProperties": false,
          "description": "Where the member is: `raw` as LinkedIn shows it, parsed into `city`, `region` and `country`."
        },
        "current_company": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "The company's name."
            },
            "url": {
              "type": "string",
              "description": "The company's LinkedIn page URL."
            },
            "title": {
              "type": "string",
              "description": "The member's title there."
            },
            "started_at": {
              "type": "string",
              "description": "When the role started, `YYYY-MM` or `YYYY`."
            },
            "linkedin_id": {
              "type": "string",
              "description": "Numeric LinkedIn organization ID."
            },
            "logo_url": {
              "type": "string",
              "description": "The company's logo (a LinkedIn CDN link, which expires)."
            },
            "industry": {
              "type": "string",
              "description": "The company's LinkedIn industry."
            },
            "headcount": {
              "type": "string",
              "description": "The company's size band on LinkedIn, e.g. `10001+`."
            }
          },
          "additionalProperties": false,
          "description": "The member's current role and its company."
        },
        "positions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "description": "The member's title in this role."
              },
              "company": {
                "type": "string",
                "description": "The company's name."
              },
              "company_url": {
                "type": "string",
                "description": "The company's LinkedIn page URL."
              },
              "linkedin_id": {
                "type": "string",
                "description": "Numeric LinkedIn organization ID for this role's company."
              },
              "position_id": {
                "type": "string",
                "description": "LinkedIn's id of this role (`urn:li:fsd_profilePosition:...`)."
              },
              "started_at": {
                "type": "string",
                "description": "When the role started, `YYYY-MM` or `YYYY`."
              },
              "ended_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "When the role ended, `YYYY-MM` or `YYYY`. `null` for a current role."
              },
              "description": {
                "type": "string",
                "description": "The role's description."
              },
              "skills": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Skills the member tied to this role."
              },
              "company_industry": {
                "type": "string",
                "description": "The company's LinkedIn industry."
              },
              "company_headcount": {
                "type": "string",
                "description": "The company's size band on LinkedIn, e.g. `10001+`."
              },
              "company_logo_url": {
                "type": "string",
                "description": "The company's logo (a LinkedIn CDN link, which expires)."
              }
            },
            "additionalProperties": false
          },
          "description": "Full experience history, current roles included."
        },
        "education": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "school": {
                "type": "string",
                "description": "The school's name."
              },
              "degree": {
                "type": "string",
                "description": "The degree."
              },
              "field": {
                "type": "string",
                "description": "The field of study."
              },
              "activities": {
                "type": "string",
                "description": "Activities and societies."
              },
              "education_id": {
                "type": "string",
                "description": "LinkedIn's id of this entry (`urn:li:fsd_profileEducation:...`)."
              },
              "school_logo_url": {
                "type": "string",
                "description": "The school's logo (a LinkedIn CDN link, which expires)."
              },
              "description": {
                "type": "string",
                "description": "The entry's description."
              },
              "started_at": {
                "type": "string",
                "description": "When it started, `YYYY-MM` or `YYYY`."
              },
              "ended_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "When it ended, `YYYY-MM` or `YYYY`. `null` when ongoing."
              }
            },
            "additionalProperties": false
          },
          "description": "Education history."
        },
        "skills": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Capped at the first 20 unless with_full_skills_and_endorsements is true, in which case every skill LinkedIn exposes is returned (up to LinkedIn's own 50-skill cap).\n"
        },
        "skill_endorsements": {
          "type": "array",
          "description": "Present when with_full_skills_and_endorsements is true (or listed in fields).",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "The skill."
              },
              "endorsement_count": {
                "type": "integer",
                "description": "How many members endorsed it."
              }
            },
            "additionalProperties": false
          }
        },
        "about": {
          "type": "string",
          "description": "The profile's About section."
        },
        "urn": {
          "type": "string",
          "description": "`urn:li:member:{id}` on enrich.\n"
        },
        "profile_urn": {
          "type": "string",
          "description": "`urn:li:fsd_profile:{ACo…}`, the profile id Sales Navigator and LinkedIn messaging use.\n"
        },
        "languages": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Language names listed on the profile. Omitted when none are listed."
        },
        "language_proficiencies": {
          "type": "array",
          "description": "The same languages as `languages`, with the proficiency the member chose, when they chose one.",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "The language."
              },
              "proficiency": {
                "type": "string",
                "enum": [
                  "NATIVE_OR_BILINGUAL",
                  "FULL_PROFESSIONAL",
                  "PROFESSIONAL_WORKING",
                  "LIMITED_WORKING",
                  "ELEMENTARY"
                ],
                "description": "The proficiency the member chose. Omitted when they chose none."
              }
            },
            "additionalProperties": false
          }
        },
        "certifications": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "The certification's name."
              },
              "authority": {
                "type": "string",
                "description": "Who issued it."
              },
              "issued_at": {
                "type": "string",
                "description": "When it was issued, `YYYY-MM` or `YYYY`."
              },
              "expires_at": {
                "type": "string",
                "description": "When it expires, `YYYY-MM` or `YYYY`."
              },
              "url": {
                "type": "string",
                "description": "The credential's URL."
              },
              "linkedin_id": {
                "type": "string",
                "description": "Numeric LinkedIn company id of the issuing organization, when listed."
              },
              "license_number": {
                "type": "string",
                "description": "License or credential number, when listed on the certificate."
              }
            },
            "additionalProperties": false
          },
          "description": "Licenses and certifications on the profile."
        },
        "publications": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "description": "The publication's title."
              },
              "publisher": {
                "type": "string",
                "description": "Its publisher."
              },
              "published_at": {
                "type": "string",
                "description": "When it was published, `YYYY-MM` or `YYYY`."
              },
              "url": {
                "type": "string",
                "description": "Its URL."
              },
              "description": {
                "type": "string",
                "description": "Its description."
              },
              "authors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A person credited on a publication or patent.",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "The person's name."
                    },
                    "public_identifier": {
                      "type": "string",
                      "description": "Their profile's slug (linkedin.com/in/<public_identifier>), when they are on LinkedIn."
                    },
                    "headline": {
                      "type": "string",
                      "description": "Their profile's headline, when they are on LinkedIn."
                    }
                  },
                  "additionalProperties": false
                },
                "description": "Its authors."
              }
            },
            "additionalProperties": false
          },
          "description": "Publications on the profile."
        },
        "patents": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "description": "The patent's title."
              },
              "number": {
                "type": "string",
                "description": "The patent or application number (e.g. `10,127,086`)."
              },
              "issuer": {
                "type": "string",
                "description": "Patent office country code as LinkedIn lists it (e.g. \"us\")."
              },
              "issued_at": {
                "type": "string",
                "description": "When it was issued, `YYYY-MM` or `YYYY`."
              },
              "description": {
                "type": "string",
                "description": "Its description."
              },
              "inventors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A person credited on a publication or patent.",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "The person's name."
                    },
                    "public_identifier": {
                      "type": "string",
                      "description": "Their profile's slug (linkedin.com/in/<public_identifier>), when they are on LinkedIn."
                    },
                    "headline": {
                      "type": "string",
                      "description": "Their profile's headline, when they are on LinkedIn."
                    }
                  },
                  "additionalProperties": false
                },
                "description": "Its inventors."
              }
            },
            "additionalProperties": false
          },
          "description": "Patents on the profile."
        },
        "awards": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "description": "The award's title."
              },
              "issuer": {
                "type": "string",
                "description": "Who gave it."
              },
              "issued_at": {
                "type": "string",
                "description": "When it was received, `YYYY-MM` or `YYYY`."
              },
              "description": {
                "type": "string",
                "description": "Its description."
              }
            },
            "additionalProperties": false
          },
          "description": "Honors and awards on the profile."
        },
        "primary_locale": {
          "type": "string",
          "description": "LinkedIn primary locale as language_COUNTRY, e.g. en_US."
        },
        "is_premium": {
          "type": "boolean",
          "description": "`true` when the member has LinkedIn Premium."
        },
        "is_open_to_work": {
          "type": "boolean",
          "description": "`true` when the member shows they are open to work."
        },
        "connections_count": {
          "type": "integer",
          "description": "Included when with_followers_and_connections is true (or listed in fields)."
        },
        "followers_count": {
          "type": "integer",
          "description": "Included when with_followers_and_connections is true (or listed in fields)."
        },
        "scraped_at": {
          "type": "string",
          "format": "date-time",
          "description": "When Up2Data scraped this profile from LinkedIn (ISO 8601)."
        },
        "profile_picture_url": {
          "type": "string",
          "description": "LinkedIn headshot CDN URL."
        }
      },
      "additionalProperties": false,
      "description": "Up2Data's profile record, every field as Up2Data documents it (docs.up2data.ai). `fields` in the request restricts it to the fields listed."
    }
  }
}