openapi: 3.1.0
info:
  title: Minerva API
  version: 1.0.0
  description: >
    # Overview

    Minerva specializes in **people data enrichment**, offering access to
    detailed and accurate information including granular demographics, property
    information, professional data, and contact details (emails and phone
    numbers).

    ## Getting Started

    Our API is secured using Bearer tokens. Follow these steps to authenticate
    and begin accessing data:


    1. **Obtain a Token**  
       Use the `/auth/get-token` endpoint to acquire a Bearer token. Tokens are valid for **12 hours**, after which a new token must be requested.
       <br /><br />
    2. **Access Data**  
       Once authenticated, you can:
       - Use the `/v1/resolve` endpoint to generate a persistent identifier for your internal records, using provided customer records.
       - Use the `/v1/enrich` endpoint to retrieve **complete user profiles** with all available data fields.  
       - Use the `/v1/get_li_contact_info` endpoint to enhance user LinkedIn usernames to retreive contact details for that individual using our propietary b2b2c identity graph
    <br /><br />
servers:
  - url: https://api.minerva.io
paths:
  /auth/get-token:
    post:
      operationId: obtainAuthToken
      summary: Obtain authentication token
      description: >
        Authenticates the user with username and password.  

        Returns an `IdToken` on success.

        `IdToken` is the Bearer token used for authenticating all of Minerva's
        services that are whitelisted for the user.
      tags:
        - Authentication
      parameters:
        - in: header
          name: X-Amz-Target
          required: true
          schema:
            type: string
            enum:
              - AWSCognitoIdentityProviderService.InitiateAuth
          example: AWSCognitoIdentityProviderService.InitiateAuth
        - in: header
          name: Content-Type
          required: true
          schema:
            type: string
            enum:
              - application/x-amz-json-1.1
          example: application/x-amz-json-1.1
      requestBody:
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/InitiateAuthRequest'
            example:
              AuthParameters:
                USERNAME: your_username_here
                PASSWORD: your_password_here
              AuthFlow: USER_PASSWORD_AUTH
              ClientId: your_clientid_here
      responses:
        '200':
          description: Successfully authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  AuthenticationResult:
                    type: object
                    properties:
                      AccessToken:
                        type: string
                        description: Cognito access token
                        example: eyJr...jjPGA
                      ExpiresIn:
                        type: integer
                        example: 86400
                      RefreshToken:
                        type: string
                        description: Cognito refresh token
                        example: dyJr...jjPFA
                      IdToken:
                        type: string
                        description: >-
                          The returned ID token. This token is what is used for
                          authentication for all Minerva endpoints.
                        example: yJsd3ft...s80pk2mcq
                  ChallengeParameters:
                    type: object
                    description: Challenge parameters returned
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
      x-codeSamples:
        - lang: Bash
          label: cURL
          source: |
            curl -i -X POST \
              https://api.minerva.io/auth/get-token \
              -H 'Content-Type: application/x-amz-json-1.1' \
              -H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
              -d '{
                "AuthParameters": {
                  "USERNAME": "myUsername",
                  "PASSWORD": "mySecretPassword"
                },
                "AuthFlow": "USER_PASSWORD_AUTH",
                "ClientId": "your_client_id_here"
              }'
        - lang: Python
          label: Python
          source: |
            import requests

            url = "https://api.minerva.io/auth/get-token"
            headers = {
                "Content-Type": "application/x-amz-json-1.1",
                "X-Amz-Target": "AWSCognitoIdentityProviderService.InitiateAuth"
            }
            payload = {
                "AuthParameters": {
                    "USERNAME": "myUsername",
                    "PASSWORD": "mySecretPassword"
                },
                "AuthFlow": "USER_PASSWORD_AUTH",
                "ClientId": "your_client_id_here"
            }

            response = requests.post(url, headers=headers, json=payload)
            if response.status_code == 200:
                data = response.json()
                print("ID Token:", data["AuthenticationResult"]["IdToken"])
            else:
                print(f"Failed with status code {response.status_code}")
  /v1/resolve:
    post:
      operationId: resolveRecords
      summary: Batch resolve identities
      description: >
        **Resolve identities for a batch of records**.  

        Each record must include:

        - record_id (your unique identifier to track results)

        - first_name

        - last_name

        - phones (array of strings)

        - emails (array of strings)


        **At least one** phone or email is required.  


        Though we return results in the order requested, we recommend using your
        `record_id` to correlate with your original inputs.
      tags:
        - Resolve
      parameters:
        - in: header
          name: Authorization
          description: Bearer token containing the previously obtained IdToken.
          required: true
          schema:
            type: string
            example: Bearer your_id_token_here
        - in: header
          name: Content-Type
          required: true
          schema:
            type: string
            enum:
              - application/json
          example: application/json
        - in: header
          name: Accept-Encoding
          required: false
          schema:
            type: string
            enum:
              - gzip
              - deflate
              - br
          example: gzip
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichmentRequest'
            example:
              records:
                - record_id: 11111111-1111-1111-1111-111111111111
                  first_name: John
                  last_name: Sample
                  phones:
                    - (000) 000-0000
                  emails:
                    - john@example.com
                - record_id: 22222222-2222-2222-2222-222222222222
                  first_name: Jane
                  last_name: Placeholder
                  phones: []
                  emails:
                    - jane@placeholder.org
      responses:
        '200':
          description: Resolution results
          content:
            application/json:
              schema:
                type: object
                required:
                  - api_request_id
                  - results
                  - request_completed_at
                properties:
                  api_request_id:
                    type: string
                    format: uuid
                    description: Unique identifier for this API request
                    example: 0222508f-45e2-4c09-a79e-b411576aac49
                  results:
                    type: array
                    items:
                      type: object
                      required:
                        - record_id
                        - is_match
                        - minerva_pid
                        - match_score
                        - is_resolvable_record
                      properties:
                        record_id:
                          type: string
                          description: Your provided record identifier
                          example: c786fb93-1f3b-dc11-8670-000bdba91a39
                        is_match:
                          type: boolean
                          description: Indicates if a match was found
                          example: true
                        minerva_pid:
                          type: string
                          description: Minerva's consistent person identifier
                          example: p-ceef1fd768e389abd4d33fdd901a5964
                        match_score:
                          type: number
                          format: float
                          description: >-
                            Confidence score of the match. Scores above 60
                            indicate a match, above 100 indicate high confidence
                          example: 122.5
                        is_resolvable_record:
                          type: boolean
                          description: >-
                            Indicates if the input was resolvable and passed
                            validation checks
                          example: true
                        validation_errors:
                          type: string
                          description: Any validation errors encountered with the input
                          example: None
                  request_completed_at:
                    type: string
                    format: date-time
                    description: Timestamp when the request was completed
                    example: '2025-01-18T02:40:14.496887+00:00'
              example:
                api_request_id: 0222508f-45e2-4c09-a79e-b411576aac49
                results:
                  - record_id: c786fb93-1f3b-dc11-8670-000bdba91a39
                    is_match: true
                    minerva_pid: p-ceef1fd768e389abd4d33fdd901a5964
                    match_score: 122.5
                    is_resolvable_record: true
                    validation_errors: None
                request_completed_at: '2025-01-18T02:40:14.496887+00:00'
        '400':
          description: Bad request (missing fields, invalid JSON, etc.)
        '401':
          description: Unauthorized (invalid or missing token)
      x-codeSamples:
        - lang: Bash
          label: cURL
          source: |
            curl -i -X POST \
              https://api.minerva.io/v1/resolve \
              -H "Authorization: Bearer <REPLACE_WITH_ID_TOKEN>" \
              -H "Content-Type: application/json" \
              -H "Accept-Encoding: gzip, deflate, br" \
              -d '{
                "records": [
                  {
                    "record_id": "03c59496-7d74-4b77-bb5d-c6c9325435fb",
                    "first_name": "Mathew",
                    "last_name": "Joseph",
                    "phones": ["(914) 483-9999"],
                    "emails": ["mj@minerva.io"]
                  },
                  {
                    "record_id": "05998f8f-73e8-4aec-b267-916b41b806d3",
                    "first_name": "Alexander",
                    "last_name": "Wilde",
                    "phones": ["(949) 943-6243"],
                    "emails": ["alex@minerva.io"]
                  }
                ]
              }'
        - lang: Python
          label: Python
          source: |
            import requests

            token_id = "<REPLACE_WITH_ID_TOKEN>"
            auth_header = f"Bearer {token_id}".strip()

            headers = {
                "Authorization": auth_header,
                "Content-Type": "application/json",
                "Accept-Encoding": "gzip, deflate, br"
            }

            data = {
                "records": [
                  {
                    "record_id": "03c59496-7d74-4b77-bb5d-c6c9325435fb",
                    "first_name": "Mathew",
                    "last_name": "Joseph",
                    "phones": ["(914) 483-9999"],
                    "emails": ["mj@minerva.io"]
                  },
                  {
                    "record_id": "05998f8f-73e8-4aec-b267-916b41b806d3",
                    "first_name": "Alexander",
                    "last_name": "Wilde",
                    "phones": ["(949) 943-6243"],
                    "emails": ["alex@minerva.io"]
                  }
                ]
            }

            url = "https://api.minerva.io/v1/resolve"
            response = requests.post(url, headers=headers, json=data)

            if response.status_code == 200:
                results = response.json()
                print("Resolution results:", results)
            else:
                print(f"Failed with status code {response.status_code}")
  /v1/enrich:
    post:
      operationId: enrichRecords
      summary: Batch enrich data
      description: >
        **Enrich a batch of records**.  

        Each record must include:

        - record_id (your unique identifier to track results)

        - first_name

        - last_name

        - phones (array of strings)

        - emails (array of strings)


        **At least one** phone or email is required.  


        Though we return results in the order requested, we recommend using your
        `record_id` to correlate with your original inputs.
      tags:
        - Full Person Enrichment
      parameters:
        - in: header
          name: Authorization
          description: Bearer token containing the previously obtained IdToken.
          required: true
          schema:
            type: string
            example: Bearer your_id_token_here
        - in: header
          name: Content-Type
          required: true
          schema:
            type: string
            enum:
              - application/json
          example: application/json
        - in: header
          name: Accept-Encoding
          required: false
          schema:
            type: string
            enum:
              - gzip
              - deflate
              - br
          example: gzip
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichmentRequest'
            example:
              records:
                - record_id: 11111111-1111-1111-1111-111111111111
                  first_name: John
                  last_name: Sample
                  phones:
                    - (000) 000-0000
                  emails:
                    - john@example.com
                - record_id: 22222222-2222-2222-2222-222222222222
                  first_name: Jane
                  last_name: Placeholder
                  phones: []
                  emails:
                    - jane@placeholder.org
      responses:
        '200':
          description: Enrichment results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentResponse'
              example:
                api_request_id: abcd1234-5678-xyz
                results:
                  - record_id: 11111111-1111-1111-1111-111111111111
                    is_match: true
                    minerva_pid: p-000abc123
                    full_name: JOHN M SAMPLE
                    first_name: JOHN
                    middle_name: M
                    last_name: SAMPLE
                    name_suffix: JR
                    gender: M
                    dob: '1985-01-01'
                    age: 38
                    marital_status: S
                    minerva_household_id: h-111xyz
                    minerva_spouse_pid: 23498234-2349
                    number_of_children: 0
                    is_retired: false
                    estimated_income_range: $50K - $100K
                    estimated_wealth_range: $500K-$1M
                    home_ownership_status: Renter
                    linkedin_url: https://www.linkedin.com/in/john-sample
                    linkedin_title: Engineer
                    linkedin_industry: Placeholder Industry
                    is_likely_remote_worker: false
                    facebook_url: facebook.com/mathewtjoseph
                    twitter_url: x.com/mj
                    has_bankruptcy_records: false
                    has_judgment_records: false
                    address_history:
                      - address_rank: 1
                        minerva_address_id: a-000xyz
                        address_line_1: 123 Example St
                        address_line_2: Apt 2
                        address_city: Sample City
                        address_state: AA
                        address_zipcode: '00000'
                        address_zipcode4: '1234'
                        ownership_status: Rented
                        is_current_owner: true
                        purchase_date: '2015-01-01'
                        purchase_price: 1000000
                        estimated_current_value: 500000
                        estimated_rental_value: 500
                        home_current_tax_liability: 10000
                        outstanding_loan_principal: 100000
                        current_property_equity_amount: 500
                        sqft: 2350
                        num_beds: 2
                        num_baths: 1
                        first_seen_date: '2010-01-01'
                        last_seen_date: '2020-12-31'
                    education_experience:
                      - experience_rank: 1
                        minerva_experience_id: e-900fab2703639dd860b143fd24ca1737
                        institution_name: University of California, Berkeley
                        institution_linkedin_url: https://www.linkedin.com/school/uc-berkeley
                        education_information: Bachelor of Arts (B.A.), Economics
                        education_level: Bachelors
                        education_majors:
                          - Arts
                          - Economics
                        education_minors: []
                        education_start_date: '2013-08-15'
                        education_end_date: '2017-05-31'
                    work_experience:
                      - experience_rank: 1
                        minerva_experience_id: w-144c54582d2363c28ba7af352d04412d
                        work_company_name: Stealth
                        work_company_linkedin_url: https://www.linkedin.com/company/warmstealth
                        work_company_website: https://warmstealth.xyz
                        work_company_industry: Software Development
                        work_company_naics_code: '561990'
                        work_company_naics_description: All Other Support Services
                        work_company_sic_code: '8699'
                        work_company_sic_description: Membership organizations, nec
                        work_title: Co-Founder
                        standard_work_title: Co-Founder
                        work_seniority_level: Executive
                        work_department: Executive
                        work_employment_type: Full-Time
                        work_status: current
                        work_start_date: '2023-05-01'
                        work_end_date: '2023-06-01'
                        work_city: New York City
                        work_state: NY
                        work_country: US
                    personal_emails:
                      - email_rank: 1
                        email_address: jsample@personal.example
                    professional_emails:
                      - email_rank: 1
                        email_address: john.sample@work.example
                    phones:
                      - phone_rank: 1
                        phone_type: Mobile
                        phone_number: (000) 000-0000
                    match_score: 88.5
                    validation_errors: ''
                request_completed_at: '2025-01-13T12:34:56Z'
        '400':
          description: Bad request (missing fields, invalid JSON, etc.)
        '401':
          description: Unauthorized (invalid or missing token)
      x-codeSamples:
        - lang: Bash
          label: cURL
          source: |
            curl -i -X POST \
              https://api.minerva.io/v1/enrich \
              -H "Authorization: Bearer <REPLACE_WITH_ID_TOKEN>" \
              -H "Content-Type: application/json" \
              -H "Accept-Encoding: gzip, deflate, br" \
              -d '{
                "records": [
                  {
                    "record_id": "03c59496-7d74-4b77-bb5d-c6c9325435fb",
                    "first_name": "Mathew",
                    "last_name": "Joseph",
                    "phones": ["(914) 483-9999"],
                    "emails": ["mj@minerva.io"]
                  },
                  {
                    "record_id": "05998f8f-73e8-4aec-b267-916b41b806d3",
                    "first_name": "Alexander",
                    "last_name": "Wilde",
                    "phones": ["(949) 943-6243"],
                    "emails": ["alex@minerva.io"]
                  }
                ]
              }'
        - lang: Python
          label: Python
          source: |
            import requests

            token_id = "<REPLACE_WITH_ID_TOKEN>"
            auth_header = f"Bearer {token_id}".strip()

            headers = {
                "Authorization": auth_header,
                "Content-Type": "application/json",
                "Accept-Encoding": "gzip, deflate, br"
            }

            data = {
                "records": [
                  {
                    "record_id": "03c59496-7d74-4b77-bb5d-c6c9325435fb",
                    "first_name": "Mathew",
                    "last_name": "Joseph",
                    "phones": ["(914) 483-9999"],
                    "emails": ["mj@minerva.io"]
                  },
                  {
                    "record_id": "05998f8f-73e8-4aec-b267-916b41b806d3",
                    "first_name": "Alexander",
                    "last_name": "Wilde",
                    "phones": ["(949) 943-6243"],
                    "emails": ["alex@minerva.io"]
                  }
                ]
            }

            url = "https://api.minerva.io/v1/enrich"
            response = requests.post(url, headers=headers, json=data)

            if response.status_code == 200:
                results = response.json()
                print("Enrichment results:", results)
            else:
                print(f"Failed with status code {response.status_code}")
  /v1/get_li_contact_info:
    post:
      operationId: contactEnrichment
      summary: Contact enrichment using b2b2c graph
      description: >
        **Retrieve contact details** (emails, phone numbers) by posting a **list
        of LinkedIn usernames**.  

        The request body is a JSON array of strings, each being a single
        LinkedIn handle or username.


        Where each **result** corresponds to one LinkedIn username in the
        request, returning `is_match`, `first_name`, `last_name`,
        `personal_emails`, `professional_emails`, and so on.
      tags:
        - Contact Info from LinkedIn
      parameters:
        - in: header
          name: Authorization
          description: Bearer token containing the previously obtained IdToken.
          required: true
          schema:
            type: string
            example: Bearer <YOUR_ID_TOKEN>
        - in: header
          name: Content-Type
          required: true
          schema:
            type: string
            enum:
              - application/json
          example: application/json
        - in: header
          name: Accept-Encoding
          required: false
          schema:
            type: string
            enum:
              - gzip
              - deflate
              - br
          example: gzip
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              description: A list of LinkedIn usernames (strings).
              items:
                type: string
                description: A single LinkedIn username
              minItems: 1
            example:
              - jane-doe-123
              - john-smith-abc
              - some-other-profile
      responses:
        '200':
          description: Contact enrichment results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactEnrichmentResponse'
              example:
                - linkedin_username: profile-anon-123
                  is_match: true
                  first_name: JOHN
                  middle_name: A
                  last_name: DOE
                  name_suffix: JR
                  phones:
                    - phone_rank: 1
                      phone_type: Mobile
                      phone_number: (123) 456-7890
                    - phone_rank: 2
                      phone_type: Landline/Services
                      phone_number: (123) 555-6789
                  personal_emails:
                    - email_rank: 1
                      email_address: john.doe@example.com
                    - email_rank: 2
                      email_address: john.doe123@example.net
                  professional_emails:
                    - email_rank: 1
                      email_address: john.doe@company.com
                  request_completed_at: '2025-01-13T23:18:05.263953+00:00'
                - linkedin_username: profile-anon-456
                  is_match: false
                  first_name: ANON
                  middle_name: M
                  last_name: ANONYMOUSE
                  name_suffix: JR
                  phones: []
                  personal_emails: []
                  professional_emails: []
                  request_completed_at: '2025-01-13T23:20:10.000000+00:00'
        '400':
          description: Bad request (missing fields, invalid JSON, etc.)
        '401':
          description: Unauthorized (invalid or missing token)
      x-codeSamples:
        - lang: Bash
          label: cURL
          source: |
            curl -i -X POST \
              https://api.minerva.io/get_contacts_by_li \
              -H "Authorization: Bearer <REPLACE_WITH_ID_TOKEN>" \
              -H "Content-Type: application/json" \
              -H "Accept-Encoding: gzip, deflate, br" \
              -d '[
                "jane-doe-123",
                "john-smith-abc"
              ]'
        - lang: Python
          label: Python
          source: |
            import requests

            token_id = "<REPLACE_WITH_ID_TOKEN>"
            auth_header = f"Bearer {token_id}"

            headers = {
              "Authorization": auth_header,
              "Content-Type": "application/json",
              "Accept-Encoding": "gzip, deflate, br"
            }

            data = [
              "jane-doe-123",
              "john-smith-abc"
            ]

            url = "https://api.minerva.io/get_contacts_by_li"
            response = requests.post(url, headers=headers, json=data)

            if response.status_code == 200:
                res = response.json()
                print("Contact enrichment results:", res)
            else:
                print(f"Failed with status code {response.status_code}")
components:
  schemas:
    InitiateAuthRequest:
      type: object
      description: AWS Cognito InitiateAuth request body
      required:
        - AuthParameters
        - AuthFlow
        - ClientId
      properties:
        AuthParameters:
          type: object
          required:
            - USERNAME
            - PASSWORD
          properties:
            USERNAME:
              type: string
              example: mj@minerva.io
            PASSWORD:
              type: string
              example: 53489asASdf4539
        AuthFlow:
          type: string
          description: AWS Cognito AuthFlow (e.g., USER_PASSWORD_AUTH)
          example: USER_PASSWORD_AUTH
        ClientId:
          type: string
          description: AWS Cognito App Client ID
          example: 3238asdftt2d80pk2mcq
    EnrichmentRequest:
      type: object
      required:
        - records
      properties:
        records:
          type: array
          description: A list of record objects to enrich.
          items:
            $ref: '#/components/schemas/EnrichmentRecord'
    EnrichmentRecord:
      type: object
      description: PII data for a single record needing enrichment
      required:
        - record_id
        - first_name
        - last_name
      properties:
        record_id:
          type: string
          description: >-
            Your persistent internal ID for this record. We recommend using an
            ID from your internal database, CRM, etc.
          example: 03c59496-7d74-4b77-bb5d-c6c9325435fb
        first_name:
          type: string
          description: The user's first name
          example: Mathew
        last_name:
          type: string
          description: The user's last name
          example: Joseph
        phones:
          type: array
          description: List of U.S. phone numbers (at least 1 if no emails)
          items:
            type: string
          example:
            - (914) 483-9999
        emails:
          type: array
          description: List of personal or professional emails (at least 1 if no phones)
          items:
            type: string
          example:
            - mj@minerva.io
    EnrichmentResponse:
      type: object
      required:
        - api_request_id
        - results
        - request_completed_at
      properties:
        api_request_id:
          type: string
          description: Request ID for tracking
          example: abcd1234-5678-xyz
        results:
          type: array
          description: A list of enriched records matching the request
          items:
            $ref: '#/components/schemas/EnrichmentResult'
        request_completed_at:
          type: string
          format: date-time
          description: Timestamp when the request was received/processed
          example: '2025-01-13T12:34:56Z'
    EnrichmentResult:
      type: object
      properties:
        record_id:
          type: string
          description: Unique identifier from the request
          example: 239480-asdfas
        is_match:
          type: boolean
          example: true
        minerva_pid:
          type: string
          description: Internal Minerva person ID
          example: m-923402349d
        full_name:
          type: string
          example: MARK T EXAMPLE JR
        first_name:
          type: string
          example: MARK
        middle_name:
          type: string
          example: T
        last_name:
          type: string
          example: EXAMPLE
        name_suffix:
          type: string
          example: JR
        gender:
          type: string
          example: M
        dob:
          type: string
          format: date
          description: e.g., "YYYY-MM-DD"
          example: '1995-10-22'
        age:
          type: integer
          example: 29
        marital_status:
          type: string
          example: S
        minerva_household_id:
          type: string
          example: md-2349028345adsfasdf
        minerva_spouse_pid:
          type: string
          example: md-23dasfda8902340d
        number_of_children:
          type: integer
          example: 2
        is_retired:
          type: boolean
          example: true
        estimated_income_range:
          type: string
          example: '>$1M'
        estimated_wealth_range:
          type: string
          example: $5M-$10M
        home_ownership_status:
          type: string
          example: Owned
        linkedin_url:
          type: string
          format: uri
          example: https://linkedin.com/in/mathewtjoseph
        linkedin_title:
          type: string
          example: CTO & Co-Founder
        linkedin_industry:
          type: string
          example: Software
        is_likely_remote_worker:
          type: boolean
          example: false
        facebook_url:
          type: string
          example: https://facebook.com/example
          format: uri
        twitter_url:
          type: string
          format: uri
          example: https://x.com/matt
        has_bankruptcy_records:
          type: boolean
          example: false
        has_judgment_records:
          type: boolean
          example: false
        address_history:
          type: array
          items:
            $ref: '#/components/schemas/AddressHistoryItem'
        education_experience:
          type: array
          description: A list of educational experiences
          items:
            $ref: '#/components/schemas/EducationExperienceItem'
        work_experience:
          type: array
          description: A list of work experiences
          items:
            $ref: '#/components/schemas/WorkExperienceItem'
        personal_emails:
          type: array
          items:
            $ref: '#/components/schemas/EmailItem'
        professional_emails:
          type: array
          items:
            $ref: '#/components/schemas/EmailItem'
        phones:
          type: array
          items:
            $ref: '#/components/schemas/PhoneItem'
        match_score:
          type: number
          format: float
          example: 100
        validation_errors:
          type: string
          example: ''
    AddressHistoryItem:
      type: object
      properties:
        address_rank:
          type: integer
          example: 1
        minerva_address_id:
          type: string
          example: abcd1234-5678-xyz
        address_line_1:
          type: string
          example: 300 Kent Ave
        address_line_2:
          type: string
          example: Suite 305
        address_city:
          type: string
          example: Brooklyn
        address_state:
          type: string
          example: NY
        address_zipcode:
          type: string
          example: '11249'
        address_zipcode4:
          type: string
          example: '2049'
        ownership_status:
          type: string
          example: Owned
        is_current_owner:
          type: boolean
          example: true
        purchase_date:
          type: string
          format: date
          example: '2024-01-01'
        purchase_price:
          type: number
          example: 1000000
        estimated_current_value:
          type: number
          example: 1000000
        estimated_rental_value:
          type: number
          example: 2000
        home_current_tax_liability:
          type: number
          example: 10000
        outstanding_loan_principal:
          type: number
          example: 500000
        current_property_equity_amount:
          type: number
          example: 500000
        sqft:
          type: number
          example: 2349
        num_beds:
          type: number
          example: 3
        num_baths:
          type: number
          example: 2
        first_seen_date:
          type: string
          format: date
          example: ''
        last_seen_date:
          type: string
          format: date
          example: ''
    EmailItem:
      type: object
      properties:
        email_rank:
          type: integer
          example: 1
        email_address:
          type: string
          format: email
          example: mj@minerva.io
    PhoneItem:
      type: object
      properties:
        phone_rank:
          type: integer
          example: 1
        phone_type:
          type: string
          example: ''
        phone_number:
          type: string
          example: ''
    ContactEnrichmentResponse:
      type: array
      description: A list of contact enrichment results
      items:
        $ref: '#/components/schemas/ContactEnrichmentResult'
    ContactEnrichmentResult:
      type: object
      description: Response format for contact enrichment API
      properties:
        linkedin_username:
          type: string
          description: The LinkedIn username that was requested
          example: profile-anon-123
        is_match:
          type: boolean
          description: Whether a match was found in the system
          example: true
        first_name:
          type: string
          description: First name of the person
          example: JOHN
        middle_name:
          type: string
          description: Middle name of the person (if available)
          example: A
        last_name:
          type: string
          description: Last name of the person
          example: DOE
        name_suffix:
          type: string
          description: Name suffix (e.g., Jr., III)
          example: JR
        phones:
          type: array
          description: List of phone numbers
          items:
            $ref: '#/components/schemas/PhoneItem'
        personal_emails:
          type: array
          description: List of personal emails
          items:
            $ref: '#/components/schemas/EmailItem'
        professional_emails:
          type: array
          description: List of professional emails
          items:
            $ref: '#/components/schemas/EmailItem'
        request_completed_at:
          type: string
          format: date-time
          description: Timestamp when the request was completed
          example: '2025-01-13T23:18:05.263953+00:00'
    EducationExperienceItem:
      type: object
      description: Single record of a person's educational experience
      properties:
        experience_rank:
          type: integer
          example: 1
          description: Rank or order of the experience
        minerva_experience_id:
          type: string
          example: e-900fab2703639dd860b143fd24ca1737
        institution_name:
          type: string
          example: University of California, Berkeley
        institution_linkedin_url:
          type: string
          format: uri
          example: https://www.linkedin.com/school/uc-berkeley
        education_information:
          type: string
          example: Bachelor of Arts (B.A.), Economics
        education_level:
          type: string
          example: Bachelors
        education_majors:
          type: array
          items:
            type: string
          example:
            - Arts
            - Economics
        education_minors:
          type: array
          items:
            type: string
          example: []
        education_start_date:
          type: string
          format: date
          description: Date the education began
          example: '2013-08-15'
        education_end_date:
          type: string
          format: date
          description: Date the education ended
          example: '2017-05-31'
    WorkExperienceItem:
      type: object
      description: Single record of a person's work experience
      properties:
        experience_rank:
          type: integer
          example: 1
        minerva_experience_id:
          type: string
          example: w-144c54582d2363c28ba7af352d04412d
        work_company_name:
          type: string
          example: Stealth
        work_company_linkedin_url:
          type: string
          format: uri
          example: https://www.linkedin.com/company/warmstealth
        work_company_website:
          type: string
          format: uri
          example: https://warmstealth.xyz
        work_company_industry:
          type: string
          example: Software Development
        work_company_naics_code:
          type: string
          example: '561990'
        work_company_naics_description:
          type: string
          example: All Other Support Services
        work_company_sic_code:
          type: string
          example: '8699'
        work_company_sic_description:
          type: string
          example: Membership organizations, nec
        work_title:
          type: string
          example: Co-Founder
        standard_work_title:
          type: string
          example: Co-Founder
        work_seniority_level:
          type: string
          example: Executive
        work_department:
          type: string
          example: Executive
        work_employment_type:
          type: string
          example: Full-Time
        work_status:
          type: string
          example: current
        work_start_date:
          type: string
          format: date
          description: Date the work position began
          example: '2023-05-01'
        work_end_date:
          type: string
          format: date
          description: Date the work position ended (if any)
          example: '2023-06-01'
        work_city:
          type: string
          example: New York City
        work_state:
          type: string
          example: NY
        work_country:
          type: string
          example: US
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-tagGroups:
  - name: Authentication
    tags:
      - Authentication
    expanded: true
  - name: Identity Resolution
    tags:
      - Resolve
    expanded: true
  - name: Enrichment
    tags:
      - Full Person Enrichment
      - Contact Info from LinkedIn
    expanded: true
tags:
  - name: Authentication
    description: >-
      Authentication is required to access any of Minerva's enrichment
      endpoints. Minerva uses
      [Bearer](https://oauth.net/2/bearer-tokens/#:~:text=Bearer%20Tokens%20are%20the%20predominant,such%20as%20JSON%20Web%20Tokens)
      tokens for Auth - these expire 12 hours after generation, and an active
      token must be provided to access services. A token may be generated  at
      any time by submitting a verified username, password, and client id.
    x-expand-by-default: true
  - name: Resolve
    description: >-
      Minerva's identity resolution endpoint allows customers to resolve records
      in database to a persistent ID. We can provide a persistent identifier
      using a full name (first and last), and a phone number or email.
    x-expand-by-default: true
  - name: Full Person Enrichment
    description: >-
      Enrichment data consists of full demographics (income/wealth), property
      records (ownership, valuation, address information), granular employment &
      work histories, contact information, and more. To get started, provide a
      batch of up to **500** records as defined below.
    x-expand-by-default: true
  - name: Contact Info from LinkedIn
    description: >-
      Minerva has a propietary B2B2C identity graph with over 75 million
      professional profiles (via linkedin) mapped to contact information. Append
      contact information for linkedin usernames. We currently support enriching
      500 handles at a time.
    x-expand-by-default: true
security: []
