openapi: 3.0.1
info:
  title: NamSor API v2
  description: >
    This is a generated connector for [NamSor API v2](https://v2.namsor.com/NamSorAPIv2/index.html) OpenAPI specification. 

    The NamSor API provides the capability to process personal names (gender, cultural origin or ethnicity) in all alphabets or languages.
  x-ballerina-init-description: >
    The connector initialization requires setting the API credentials.
    
    Create an [NamSor Account](https://v2.namsor.com/NamSorAPIv2/sign-in.html) and obtain tokens following [this guide](https://v2.namsor.com/NamSorAPIv2/apidoc.html).
  x-ballerina-display:
      label: NamSor
      iconPath: "icon.png"
  contact:
    name: Namsor SAS
    url: http://www.namsor.com/
    email: contact@namsor.com
  license:
    name: NamSorAPI_Lic_v0.0.7
    url: https://v2.namsor.com/NamSorAPIv2/assets/pdf/201803_NamSor_API_Terms_v007.pdf
  version: 2.0.15
externalDocs:
  description: NamSor API client SDKs v2 for Java, Python
  url: https://github.com/namsor
servers:
  - url: https://v2.namsor.com/NamSorAPIv2
    description: namsor_v2
    variables: {}
security:
  - api_key: []
tags:
  - name: personal
    description: 'Personal names (anthroponyms) : gender, country origin/ethnicity, diaspora, US ''race''/ethniciy'
  - name: social
    description: Social media and pseudonyms
  - name: chinese
    description: CHINESE special features
  - name: japanese
    description: JAPANESE special features
  - name: admin
    description: Administrative, system management.
paths:
  /api2/json/country/{personalNameFull}:
    get:
      tags:
        - personal
      summary: '[USES 10 UNITS PER NAME] Infer the likely country of residence of a personal full name, or one surname. Assumes names as they are in the country of residence OR the country of origin.'
      operationId: country
      parameters:
        - name: personalNameFull
          in: path
          required: true
          description: Personal full name
          schema:
            type: string
      responses:
        '200':
          description: A origined name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalNameGeoOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/nameType/{properNoun}:
    get:
      tags:
        - general
      summary: Infer the likely type of a proper noun (personal name, brand name, place name etc.)
      operationId: nameType
      parameters:
        - name: properNoun
          in: path
          required: true
          schema:
            type: string
          description: The proper noun
      responses:
        '200':
          description: A typed name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProperNounCategorizedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/disable/{source}/{disabled}:
    get:
      tags:
        - admin
      summary: Activate/deactivate an API Key.
      operationId: disable
      parameters:
        - name: source
          in: path
          description: The API Key to set as enabled/disabled.
          required: true
          schema:
            type: string
        - name: disabled
          in: path
          description: Disbled/Not disabled
          required: true
          schema:
            type: boolean
      responses:
        '200':
          description: Disabled the API Key.
        '401':
          description: Missing or incorrect API Key
  /api2/json/origin/{firstName}/{lastName}:
    get:
      tags:
        - personal
      summary: '[USES 10 UNITS PER NAME] Infer the likely country of origin of a personal name. Assumes names as they are in the country of origin. For US, CA, AU, NZ and other melting-pots : use ''diaspora'' instead.'
      operationId: origin
      parameters:
        - name: firstName
          in: path
          required: true
          schema:
            type: string
          description: First name
        - name: lastName
          in: path
          required: true
          schema:
            type: string
          description: Last name
      responses:
        '200':
          description: A origined name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirstLastNameOriginedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/softwareVersion:
    get:
      tags:
        - admin
      summary: Get the current software version
      operationId: softwareVersion
      responses:
        '200':
          description: The current software version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoftwareVersionOut'
        '401':
          description: Missing or incorrect token
  /api2/json/apiStatus:
    get:
      tags:
        - admin
      summary: Prints the current status of the classifiers. A classifier name in apiStatus corresponds to a service name in apiServices.
      operationId: apiStatus
      responses:
        '200':
          description: Available classifiers and status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIClassifiersStatusOut'
        '401':
          description: Missing or incorrect token
  /api2/json/apiServices:
    get:
      tags:
        - admin
      summary: List of classification services and usage cost in Units per classification (default is 1=ONE Unit). Some API endpoints (ex. Corridor) combine multiple classifiers.
      operationId: availableServices
      responses:
        '200':
          description: Available services
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIServicesOut'
        '401':
          description: Missing or incorrect token
  /api2/json/taxonomyClasses/{classifierName}:
    get:
      tags:
        - admin
      summary: Print the taxonomy classes valid for the given classifier.
      operationId: taxonomyClasses
      parameters:
        - name: classifierName
          in: path
          description: Name of the classifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Available plans
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIClassifierTaxonomyOut'
        '401':
          description: Missing or incorrect token
  /api2/json/apiUsage:
    get:
      tags:
        - admin
      summary: Print current API usage.
      operationId: apiUsage
      responses:
        '200':
          description: Print current API usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIPeriodUsageOut'
        '401':
          description: Missing or incorrect API Key
      security:
        - api_key: []
  /api2/json/apiUsageHistory:
    get:
      tags:
        - admin
      summary: Print historical API usage.
      operationId: apiUsageHistory
      responses:
        '200':
          description: Print historical API usage (NB. new output format form v2.0.15)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIUsageHistoryOut'
        '401':
          description: Missing or incorrect API Key
      security:
        - api_key: []
  /api2/json/apiUsageHistoryAggregate:
    get:
      tags:
        - admin
      summary: Print historical API usage (in an aggregated view, by service, by day/hour/min).
      operationId: apiUsageHistoryAggregate
      responses:
        '200':
          description: Print historical API usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIUsageAggregatedOut'
        '401':
          description: Missing or incorrect API Key
      security:
        - api_key: []
  /api2/json/learnable/{source}/{learnable}:
    get:
      tags:
        - admin
      summary: Activate/deactivate learning from a source.
      operationId: learnable
      parameters:
        - name: source
          in: path
          description: The API Key to set as learnable/non learnable.
          required: true
          schema:
            type: string
        - name: learnable
          in: path
          description: Learnable/non learnable.
          required: true
          schema:
            type: boolean
      responses:
        '200':
          description: Set learning from source.
        '401':
          description: Missing or incorrect API Key
  /api2/json/anonymize/{source}/{anonymized}:
    get:
      tags:
        - admin
      summary: Activate/deactivate anonymization for a source.
      operationId: anonymize
      parameters:
        - name: source
          in: path
          required: true
          description: The API Key to set as anonymized/non anonymized. 
          schema:
            type: string
        - name: anonymized
          in: path
          description: Anonymized/non anonymized. 
          required: true
          schema:
            type: boolean
      responses:
        '200':
          description: Anonymization of a source.
        '401':
          description: Missing or incorrect API Key
  /api2/json/nameTypeGeo/{properNoun}/{countryIso2}:
    get:
      tags:
        - general
      summary: Infer the likely type of a proper noun (personal name, brand name, place name etc.)
      operationId: nameTypeGeo
      parameters:
        - name: properNoun
          in: path
          required: true
          schema:
            type: string
          description: The proper noun
        - name: countryIso2
          in: path
          required: true
          schema:
            type: string
          description: ISO2 country code
      responses:
        '200':
          description: A typed name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProperNounCategorizedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/nameTypeBatch:
    post:
      tags:
        - general
      summary: Infer the likely common type of up to 100 proper nouns (personal name, brand name, place name etc.)
      operationId: nameTypeBatch
      requestBody:
        description: A list of proper names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchNameIn'
      responses:
        '200':
          description: A list of commonTypeized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchProperNounCategorizedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/nameTypeGeoBatch:
    post:
      tags:
        - general
      summary: Infer the likely common type of up to 100 proper nouns (personal name, brand name, place name etc.)
      operationId: nameTypeGeoBatch
      requestBody:
        description: A list of proper names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchNameGeoIn'
      responses:
        '200':
          description: A list of commonTypeized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchProperNounCategorizedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/corridor/{countryIso2From}/{firstNameFrom}/{lastNameFrom}/{countryIso2To}/{firstNameTo}/{lastNameTo}:
    get:
      tags:
        - personal
      summary: '[USES 20 UNITS PER NAME COUPLE] Infer several classifications for a cross border interaction between names (ex. remit, travel, intl com)'
      operationId: corridor
      parameters:
        - name: countryIso2From
          in: path
          required: true
          description: Start ISO2 country code to filter
          schema:
            type: string
        - name: firstNameFrom
          in: path
          required: true
          description: Start first name to filter
          schema:
            type: string
        - name: lastNameFrom
          in: path
          required: true
          description: Start last name to filter
          schema:
            type: string
        - name: countryIso2To
          in: path
          required: true
          description: End ISO2 country code to filter
          schema:
            type: string
        - name: firstNameTo
          in: path
          required: true
          description: End first name to filter
          schema:
            type: string
        - name: lastNameTo
          in: path
          required: true
          description: End last name to filter
          schema:
            type: string
      responses:
        '200':
          description: Two classified names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorridorOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/corridorBatch:
    post:
      tags:
        - personal
      summary: '[USES 20 UNITS PER NAME PAIR] Infer several classifications for up to 100 cross border interaction between names (ex. remit, travel, intl com)'
      operationId: corridorBatch
      requestBody:
        description: A list of name pairs, with country code (nameFrom -> nameTo).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCorridorIn'
      responses:
        '200':
          description: A list of classified name pairs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCorridorOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/gender/{firstName}/{lastName}:
    get:
      tags:
        - personal
      summary: Infer the likely gender of a name.
      operationId: gender
      parameters:
        - name: firstName
          in: path
          required: true
          schema:
            type: string
          description: First name
        - name: lastName
          in: path
          required: true
          schema:
            type: string
          description: Last name
      responses:
        '200':
          description: A genderized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirstLastNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderGeo/{firstName}/{lastName}/{countryIso2}:
    get:
      tags:
        - personal
      summary: Infer the likely gender of a name, given a local context (ISO2 country code).
      operationId: genderGeo
      parameters:
        - name: firstName
          in: path
          required: true
          schema:
            type: string
          description: First name
        - name: lastName
          in: path
          required: true
          schema:
            type: string
          description: Last name
        - name: countryIso2
          in: path
          required: true
          schema:
            type: string
          description: ISO2 country code
      responses:
        '200':
          description: A genderized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirstLastNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderGeoBatch:
    post:
      tags:
        - personal
      summary: Infer the likely gender of up to 100 names, each given a local context (ISO2 country code).
      operationId: genderGeoBatch
      requestBody:
        description: A list of names, with country code.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameGeoIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFirstLastNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderBatch:
    post:
      tags:
        - personal
      summary: Infer the likely gender of up to 100 names, detecting automatically the cultural context.
      operationId: genderBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFirstLastNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderFullGeo/{fullName}/{countryIso2}:
    get:
      tags:
        - personal
      summary: Infer the likely gender of a full name, given a local context (ISO2 country code).
      operationId: genderFullGeo
      parameters:
        - name: fullName
          in: path
          required: true
          schema:
            type: string
          description: Full name
        - name: countryIso2
          in: path
          required: true
          schema:
            type: string
          description: ISO2 country code
      responses:
        '200':
          description: A genderized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderFull/{fullName}:
    get:
      tags:
        - personal
      summary: Infer the likely gender of a full name, ex. John H. Smith
      operationId: genderFull
      parameters:
        - name: fullName
          in: path
          required: true
          schema:
            type: string
          description: Full name
      responses:
        '200':
          description: A genderized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderFullBatch:
    post:
      tags:
        - personal
      summary: Infer the likely gender of up to 100 full names, detecting automatically the cultural context.
      operationId: genderFullBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPersonalNameIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPersonalNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderFullGeoBatch:
    post:
      tags:
        - personal
      summary: Infer the likely gender of up to 100 full names, with a given cultural context (country ISO2 code).
      operationId: genderFullGeoBatch
      requestBody:
        description: A list of personal names, with a country ISO2 code
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPersonalNameGeoIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPersonalNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/originBatch:
    post:
      tags:
        - personal
      summary: '[USES 10 UNITS PER NAME] Infer the likely country of origin of up to 100 names, detecting automatically the cultural context.'
      operationId: originBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFirstLastNameOriginedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/countryBatch:
    post:
      tags:
        - personal
      summary: '[USES 10 UNITS PER NAME] Infer the likely country of residence of up to 100 personal full names, or surnames. Assumes names as they are in the country of residence OR the country of origin.'
      operationId: countryBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPersonalNameIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPersonalNameGeoOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/usRaceEthnicity/{firstName}/{lastName}:
    get:
      tags:
        - personal
      summary: '[USES 10 UNITS PER NAME] Infer a US resident''s likely race/ethnicity according to US Census taxonomy W_NL (white, non latino), HL (hispano latino),  A (asian, non latino), B_NL (black, non latino). Optionally add header X-OPTION-USRACEETHNICITY-TAXONOMY: USRACEETHNICITY-6CLASSES for two additional classes, AI_AN (American Indian or Alaskan Native) and PI (Pacific Islander).'
      operationId: usRaceEthnicity
      parameters:
        - name: firstName
          in: path
          required: true
          schema:
            type: string
          description: First name
        - name: lastName
          in: path
          required: true
          schema:
            type: string
          description: Last name
      responses:
        '200':
          description: 'a US resident''s likely race/ethnicity : W_NL (white, non latino), HL (hispano latino),  A (asian, non latino), B_NL (black, non latino), AI_AN (American Indian or Alaskan Native*) and PI (Pacific Islander*). *optionally'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirstLastNameUSRaceEthnicityOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/usRaceEthnicityZIP5/{firstName}/{lastName}/{zip5Code}:
    get:
      tags:
        - personal
      summary: '[USES 10 UNITS PER NAME] Infer a US resident''s likely race/ethnicity according to US Census taxonomy, using (optional) ZIP5 code info. Output is W_NL (white, non latino), HL (hispano latino),  A (asian, non latino), B_NL (black, non latino). Optionally add header X-OPTION-USRACEETHNICITY-TAXONOMY: USRACEETHNICITY-6CLASSES for two additional classes, AI_AN (American Indian or Alaskan Native) and PI (Pacific Islander).'
      operationId: usRaceEthnicityZIP5
      parameters:
        - name: firstName
          in: path
          required: true
          schema:
            type: string
          description: First name
        - name: lastName
          in: path
          required: true
          schema:
            type: string
          description: Last name
        - name: zip5Code
          in: path
          required: true
          description: 5-digit ZIP Code
          schema:
            type: string
      responses:
        '200':
          description: 'a US resident''s likely race/ethnicity : W_NL (white, non latino), HL (hispano latino),  A (asian, non latino), B_NL (black, non latino), AI_AN (American Indian or Alaskan Native*) and PI (Pacific Islander*). *optionally'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirstLastNameUSRaceEthnicityOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/usRaceEthnicityBatch:
    post:
      tags:
        - personal
      summary: '[USES 10 UNITS PER NAME] Infer up-to 100 US resident''s likely race/ethnicity according to US Census taxonomy. Output is W_NL (white, non latino), HL (hispano latino),  A (asian, non latino), B_NL (black, non latino). Optionally add header X-OPTION-USRACEETHNICITY-TAXONOMY: USRACEETHNICITY-6CLASSES for two additional classes, AI_AN (American Indian or Alaskan Native) and PI (Pacific Islander).'
      operationId: usRaceEthnicityBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameGeoIn'
      responses:
        '200':
          description: A list of US resident's likely race/ethnicity. W_NL (white, non latino), HL (hispano latino),  A (asian, non latino), B_NL (black, non latino), AI_AN (American Indian or Alaskan Native*) and PI (Pacific Islander*). *optionally
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFirstLastNameUSRaceEthnicityOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/usZipRaceEthnicityBatch:
    post:
      tags:
        - personal
      summary: '[USES 10 UNITS PER NAME] Infer up-to 100 US resident''s likely race/ethnicity according to US Census taxonomy, with (optional) ZIP code. Output is W_NL (white, non latino), HL (hispano latino),  A (asian, non latino), B_NL (black, non latino). Optionally add header X-OPTION-USRACEETHNICITY-TAXONOMY: USRACEETHNICITY-6CLASSES for two additional classes, AI_AN (American Indian or Alaskan Native) and PI (Pacific Islander).'
      operationId: usZipRaceEthnicityBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameGeoZippedIn'
      responses:
        '200':
          description: A list of US resident's likely race/ethnicity. W_NL (white, non latino), HL (hispano latino),  A (asian, non latino), B_NL (black, non latino), AI_AN (American Indian or Alaskan Native*) and PI (Pacific Islander*). *optionally
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFirstLastNameUSRaceEthnicityOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/diaspora/{countryIso2}/{firstName}/{lastName}:
    get:
      tags:
        - personal
      summary: '[USES 20 UNITS PER NAME] Infer the likely ethnicity/diaspora of a personal name, given a country of residence ISO2 code (ex. US, CA, AU, NZ etc.)'
      operationId: diaspora
      parameters:
        - name: countryIso2
          in: path
          required: true
          schema:
            type: string
          description: ISO2 country code
        - name: firstName
          in: path
          required: true
          schema:
            type: string
          description: First name
        - name: lastName
          in: path
          required: true
          schema:
            type: string
          description: Last name
      responses:
        '200':
          description: A diaspora / ethnicity for given name and geography.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirstLastNameDiasporaedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/diasporaBatch:
    post:
      tags:
        - personal
      summary: '[USES 20 UNITS PER NAME] Infer the likely ethnicity/diaspora of up to 100 personal names, given a country of residence ISO2 code (ex. US, CA, AU, NZ etc.)'
      operationId: diasporaBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameGeoIn'
      responses:
        '200':
          description: A list of diaspora / ethnicity given a name and residency.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFirstLastNameDiasporaedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/parseName/{nameFull}/{countryIso2}:
    get:
      tags:
        - personal
      summary: Infer the likely first/last name structure of a name, ex. John Smith or SMITH, John or SMITH; John. For better accuracy, provide a geographic context.
      operationId: parseNameGeo
      parameters:
        - name: nameFull
          in: path
          required: true
          description: Full name
          schema:
            type: string
        - name: countryIso2
          in: path
          required: true
          schema:
            type: string
          description: ISO2 country code
      responses:
        '200':
          description: A origined name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalNameParsedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/parseNameBatch:
    post:
      tags:
        - personal
      summary: Infer the likely first/last name structure of a name, ex. John Smith or SMITH, John or SMITH; John.
      operationId: parseNameBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPersonalNameIn'
      responses:
        '200':
          description: A list of parsed names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPersonalNameParsedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/parseNameGeoBatch:
    post:
      tags:
        - personal
      summary: 'Infer the likely first/last name structure of a name, ex. John Smith or SMITH, John or SMITH; John. Giving a local context improves precision. '
      operationId: parseNameGeoBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPersonalNameGeoIn'
      responses:
        '200':
          description: A list of parsed names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPersonalNameParsedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/parseChineseName/{chineseName}:
    get:
      tags:
        - chinese
      summary: Infer the likely first/last name structure of a name, ex. 王晓明 -> 王(surname) 晓明(given name)
      operationId: parseChineseName
      parameters:
        - name: chineseName
          in: path
          required: true
          description: Chinese name
          schema:
            type: string
      responses:
        '200':
          description: A origined name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalNameParsedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/parseChineseNameBatch:
    post:
      tags:
        - chinese
      summary: Infer the likely first/last name structure of a name, ex. 王晓明 -> 王(surname) 晓明(given name).
      operationId: parseChineseNameBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPersonalNameIn'
      responses:
        '200':
          description: A list of parsed names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPersonalNameParsedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/pinyinChineseName/{chineseName}:
    get:
      tags:
        - chinese
      summary: Romanize the Chinese name to Pinyin, ex. 王晓明 -> Wang (surname) Xiaoming (given name)
      operationId: pinyinChineseName
      parameters:
        - name: chineseName
          in: path
          required: true
          description: Chinese name
          schema:
            type: string
      responses:
        '200':
          description: A pinyin name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalNameParsedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/pinyinChineseNameBatch:
    post:
      tags:
        - chinese
      summary: Romanize a list of Chinese name to Pinyin, ex. 王晓明 -> Wang (surname) Xiaoming (given name).
      operationId: pinyinChineseNameBatch
      requestBody:
        description: A list of Chinese names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPersonalNameIn'
      responses:
        '200':
          description: A list of Pinyin names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPersonalNameParsedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/chineseNameMatch/{chineseSurnameLatin}/{chineseGivenNameLatin}/{chineseName}:
    get:
      tags:
        - chinese
      summary: Return a score for matching Chinese name ex. 王晓明 with a romanized name ex. Wang Xiaoming
      operationId: chineseNameMatch
      parameters:
        - name: chineseSurnameLatin
          in: path
          required: true
          description: Chinese sur name in latin
          schema:
            type: string
        - name: chineseGivenNameLatin
          in: path
          required: true
          description: Chinese given name in latin
          schema:
            type: string
        - name: chineseName
          in: path
          required: true
          description: Chinese name
          schema:
            type: string
      responses:
        '200':
          description: A romanized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameMatchedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/chineseNameMatchBatch:
    post:
      tags:
        - chinese
      summary: Identify Chinese name candidates, based on the romanized name (firstName = chineseGivenName; lastName=chineseSurname), ex. Wang Xiaoming
      operationId: chineseNameMatchBatch
      requestBody:
        description: A list of personal Chinese names in LATIN, firstName = chineseGivenName; lastName=chineseSurname
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchMatchPersonalFirstLastNameIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchNameMatchedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderChineseNamePinyin/{chineseSurnameLatin}/{chineseGivenNameLatin}:
    get:
      tags:
        - chinese
      summary: Infer the likely gender of a Chinese name in LATIN (Pinyin).
      operationId: genderChineseNamePinyin
      parameters:
        - name: chineseSurnameLatin
          in: path
          required: true
          description: Chinese sur name in latin
          schema:
            type: string
        - name: chineseGivenNameLatin
          in: path
          required: true
          description: Chinese given name in latin
          schema:
            type: string
      responses:
        '200':
          description: A genderized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirstLastNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderChineseNamePinyinBatch:
    post:
      tags:
        - chinese
      summary: Infer the likely gender of up to 100 Chinese names in LATIN (Pinyin).
      operationId: genderChineseNamePinyinBatch
      requestBody:
        description: A list of names, with country code.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFirstLastNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderChineseName/{chineseName}:
    get:
      tags:
        - chinese
      summary: Infer the likely gender of a Chinese full name ex. 王晓明
      operationId: genderChineseName
      parameters:
        - name: chineseName
          in: path
          required: true
          description: Chinese name
          schema:
            type: string
      responses:
        '200':
          description: A genderized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderChineseNameBatch:
    post:
      tags:
        - chinese
      summary: Infer the likely gender of up to 100 full names ex. 王晓明
      operationId: genderChineseNameBatch
      requestBody:
        description: A list of personal names, with a country ISO2 code
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPersonalNameIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPersonalNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/chineseNameCandidates/{chineseSurnameLatin}/{chineseGivenNameLatin}:
    get:
      tags:
        - chinese
      summary: Identify Chinese name candidates, based on the romanized name ex. Wang Xiaoming
      operationId: chineseNameCandidates
      parameters:
        - name: chineseSurnameLatin
          in: path
          required: true
          description: Chinese sur name in latin
          schema:
            type: string
        - name: chineseGivenNameLatin
          in: path
          required: true
          description: Chinese given name in latin
          schema:
            type: string
      responses:
        '200':
          description: A romanized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameMatchCandidatesOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/chineseNameCandidatesBatch:
    post:
      tags:
        - chinese
      summary: Identify Chinese name candidates, based on the romanized name (firstName = chineseGivenName; lastName=chineseSurname), ex. Wang Xiaoming
      operationId: chineseNameCandidatesBatch
      requestBody:
        description: A list of personal Chinese names in LATIN, firstName = chineseGivenName; lastName=chineseSurname
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchNameMatchCandidatesOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/chineseNameGenderCandidates/{chineseSurnameLatin}/{chineseGivenNameLatin}/{knownGender}:
    get:
      tags:
        - chinese
      summary: Identify Chinese name candidates, based on the romanized name ex. Wang Xiaoming - having a known gender ('male' or 'female')
      operationId: chineseNameGenderCandidates
      parameters:
        - name: chineseSurnameLatin
          in: path
          required: true
          description: Chinese sur name in latin
          schema:
            type: string
        - name: chineseGivenNameLatin
          in: path
          required: true
          description: Chinese given name in latin
          schema:
            type: string
        - name: knownGender
          in: path
          required: true
          description: Known gender
          schema:
            type: string
      responses:
        '200':
          description: A romanized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameMatchCandidatesOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/chineseNameCandidatesGenderBatch:
    post:
      tags:
        - chinese
      summary: Identify Chinese name candidates, based on the romanized name (firstName = chineseGivenName; lastName=chineseSurname) ex. Wang Xiaoming.
      operationId: chineseNameCandidatesGenderBatch
      requestBody:
        description: A list of personal Chinese names in LATIN, firstName = chineseGivenName; lastName=chineseSurname
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameGenderIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchNameMatchCandidatesOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/parseJapaneseName/{japaneseName}:
    get:
      tags:
        - japanese
      summary: Infer the likely first/last name structure of a name, ex. 山本 早苗 or Yamamoto Sanae
      operationId: parseJapaneseName
      parameters:
        - name: japaneseName
          in: path
          required: true
          description: Japanese name
          schema:
            type: string
      responses:
        '200':
          description: A origined name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalNameParsedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/parseJapaneseNameBatch:
    post:
      tags:
        - japanese
      summary: 'Infer the likely first/last name structure of a name, ex. 山本 早苗 or Yamamoto Sanae '
      operationId: parseJapaneseNameBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPersonalNameIn'
      responses:
        '200':
          description: A list of parsed names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPersonalNameParsedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/japaneseNameKanjiCandidates/{japaneseSurnameLatin}/{japaneseGivenNameLatin}/{knownGender}:
    get:
      tags:
        - japanese
      summary: Identify japanese name candidates in KANJI, based on the romanized name ex. Yamamoto Sanae - and a known gender.
      operationId: japaneseNameKanjiCandidates
      parameters:
        - name: japaneseSurnameLatin
          in: path
          required: true
          description: Japanese sur name in latin
          schema:
            type: string
        - name: japaneseGivenNameLatin
          in: path
          required: true
          description: Japanese given name in latin
          schema:
            type: string
        - name: knownGender
          in: path
          required: true
          description: Known gender
          schema:
            type: string
      responses:
        '200':
          description: A romanized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameMatchCandidatesOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/japaneseNameKanjiCandidates/{japaneseSurnameLatin}/{japaneseGivenNameLatin}:
    get:
      tags:
        - japanese
      summary: Identify japanese name candidates in KANJI, based on the romanized name ex. Yamamoto Sanae
      operationId: japaneseNameKanjiCandidates_1
      parameters:
        - name: japaneseSurnameLatin
          in: path
          required: true
          description: Japanese sur name in latin
          schema:
            type: string
        - name: japaneseGivenNameLatin
          in: path
          required: true
          description: Japanese given name in latin
          schema:
            type: string
      responses:
        '200':
          description: A romanized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameMatchCandidatesOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/japaneseNameLatinCandidates/{japaneseSurnameKanji}/{japaneseGivenNameKanji}:
    get:
      tags:
        - japanese
      summary: Romanize japanese name, based on the name in Kanji.
      operationId: japaneseNameLatinCandidates
      parameters:
        - name: japaneseSurnameKanji
          in: path
          required: true
          description: Japanese sur name in kanji
          schema:
            type: string
        - name: japaneseGivenNameKanji
          in: path
          required: true
          description: Japanese given name in kanji
          schema:
            type: string
      responses:
        '200':
          description: A romanized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameMatchCandidatesOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/japaneseNameKanjiCandidatesBatch:
    post:
      tags:
        - japanese
      summary: Identify japanese name candidates in KANJI, based on the romanized name (firstName = japaneseGivenName; lastName=japaneseSurname), ex. Yamamoto Sanae
      operationId: japaneseNameKanjiCandidatesBatch
      requestBody:
        description: A list of personal japanese names in LATIN, firstName = japaneseGivenName; lastName=japaneseSurname
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchNameMatchCandidatesOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/japaneseNameGenderKanjiCandidatesBatch:
    post:
      tags:
        - japanese
      summary: Identify japanese name candidates in KANJI, based on the romanized name (firstName = japaneseGivenName; lastName=japaneseSurname) with KNOWN gender, ex. Yamamoto Sanae
      operationId: japaneseNameGenderKanjiCandidatesBatch
      requestBody:
        description: A list of personal japanese names in LATIN, firstName = japaneseGivenName; lastName=japaneseSurname and known gender
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameGenderIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchNameMatchCandidatesOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/japaneseNameLatinCandidatesBatch:
    post:
      tags:
        - japanese
      summary: Romanize japanese names, based on the name in KANJI
      operationId: japaneseNameLatinCandidatesBatch
      requestBody:
        description: A list of personal japanese names in KANJI, firstName = japaneseGivenName; lastName=japaneseSurname
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchNameMatchCandidatesOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/japaneseNameMatch/{japaneseSurnameLatin}/{japaneseGivenNameLatin}/{japaneseName}:
    get:
      tags:
        - japanese
      summary: Return a score for matching Japanese name in KANJI ex. 山本 早苗 with a romanized name ex. Yamamoto Sanae
      operationId: japaneseNameMatch
      parameters:
        - name: japaneseSurnameLatin
          in: path
          required: true
          description: Japanese sur name in latin
          schema:
            type: string
        - name: japaneseGivenNameLatin
          in: path
          required: true
          description: Japanese given name in latin
          schema:
            type: string
        - name: japaneseName
          in: path
          required: true
          description: Japanese name
          schema:
            type: string
      responses:
        '200':
          description: A romanized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameMatchedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/japaneseNameMatchFeedbackLoop/{japaneseSurnameLatin}/{japaneseGivenNameLatin}/{japaneseName}:
    get:
      tags:
        - japanese
      summary: '[CREDITS 1 UNIT] Feedback loop to better perform matching Japanese name in KANJI ex. 山本 早苗 with a romanized name ex. Yamamoto Sanae'
      operationId: japaneseNameMatchFeedbackLoop
      parameters:
        - name: japaneseSurnameLatin
          in: path
          required: true
          description: Japanese sur name in latin
          schema:
            type: string
        - name: japaneseGivenNameLatin
          in: path
          required: true
          description: Japanese given name in latin
          schema:
            type: string
        - name: japaneseName
          in: path
          required: true
          description: Japanese name
          schema:
            type: string
      responses:
        '200':
          description: A romanized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackLoopOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/japaneseNameMatchBatch:
    post:
      tags:
        - japanese
      summary: Return a score for matching a list of Japanese names in KANJI ex. 山本 早苗 with romanized names ex. Yamamoto Sanae
      operationId: japaneseNameMatchBatch
      requestBody:
        description: A list of personal Japanese names in LATIN, firstName = japaneseGivenName; lastName=japaneseSurname
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchMatchPersonalFirstLastNameIn'
      responses:
        '200':
          description: A list of matched names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchNameMatchedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderJapaneseName/{japaneseSurname}/{japaneseGivenName}:
    get:
      tags:
        - japanese
      summary: Infer the likely gender of a Japanese name in LATIN (Pinyin).
      operationId: genderJapaneseNamePinyin
      parameters:
        - name: japaneseSurname
          in: path
          required: true
          description: Japanese sur name
          schema:
            type: string
        - name: japaneseGivenName
          in: path
          required: true
          description: Japanese given name
          schema:
            type: string
      responses:
        '200':
          description: A genderized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirstLastNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderJapaneseNameBatch:
    post:
      tags:
        - japanese
      summary: Infer the likely gender of up to 100 Japanese names in LATIN (Pinyin).
      operationId: genderJapaneseNamePinyinBatch
      requestBody:
        description: A list of names, with country code.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNameIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFirstLastNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderJapaneseNameFull/{japaneseName}:
    get:
      tags:
        - japanese
      summary: Infer the likely gender of a Japanese full name ex. 王晓明
      operationId: genderJapaneseNameFull
      parameters:
        - name: japaneseName
          in: path
          required: true
          description: Japanese name
          schema:
            type: string
      responses:
        '200':
          description: A genderized name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/genderJapaneseNameFullBatch:
    post:
      tags:
        - japanese
      summary: Infer the likely gender of up to 100 full names
      operationId: genderJapaneseNameFullBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPersonalNameIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPersonalNameGenderedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/phoneCode/{firstName}/{lastName}/{phoneNumber}:
    get:
      tags:
        - social
      summary: '[USES 11 UNITS PER NAME] Infer the likely country and phone prefix, given a personal name and formatted / unformatted phone number.'
      operationId: phoneCode
      parameters:
        - name: firstName
          in: path
          required: true
          schema:
            type: string
          description: First name
        - name: lastName
          in: path
          required: true
          schema:
            type: string
          description: Last name
        - name: phoneNumber
          in: path
          required: true
          schema:
            type: string
          description: Phone number
      responses:
        '200':
          description: A name with country and phone code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirstLastNamePhoneCodedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/phoneCodeGeo/{firstName}/{lastName}/{phoneNumber}/{countryIso2}:
    get:
      tags:
        - social
      summary: '[USES 11 UNITS PER NAME] Infer the likely phone prefix, given a personal name and formatted / unformatted phone number, with a local context (ISO2 country of residence).'
      operationId: phoneCodeGeo
      parameters:
        - name: firstName
          in: path
          required: true
          schema:
            type: string
          description: First name
        - name: lastName
          in: path
          required: true
          schema:
            type: string
          description: Last name
        - name: phoneNumber
          in: path
          required: true
          schema:
            type: string
          description: Phone number
        - name: countryIso2
          in: path
          required: true
          schema:
            type: string
          description: ISO2 country code
      responses:
        '200':
          description: A name with country and phone code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirstLastNamePhoneCodedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/phoneCodeGeoFeedbackLoop/{firstName}/{lastName}/{phoneNumber}/{phoneNumberE164}/{countryIso2}:
    get:
      tags:
        - social
      summary: '[CREDITS 1 UNIT] Feedback loop to better infer the likely phone prefix, given a personal name and formatted / unformatted phone number, with a local context (ISO2 country of residence).'
      operationId: phoneCodeGeoFeedbackLoop
      parameters:
        - name: firstName
          in: path
          required: true
          schema:
            type: string
          description: First name
        - name: lastName
          in: path
          required: true
          schema:
            type: string
          description: Last name
        - name: phoneNumber
          in: path
          required: true
          schema:
            type: string
          description: Phone number
        - name: phoneNumberE164
          in: path
          required: true
          schema:
            type: string
          description: Phone number in E164 standard
        - name: countryIso2
          in: path
          required: true
          schema:
            type: string
          description: ISO2 country code
      responses:
        '200':
          description: A name with country and phone code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirstLastNamePhoneCodedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/phoneCodeBatch:
    post:
      tags:
        - social
      summary: '[USES 11 UNITS PER NAME] Infer the likely country and phone prefix, of up to 100 personal names, detecting automatically the local context given a name and formatted / unformatted phone number.'
      operationId: phoneCodeBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNamePhoneNumberIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFirstLastNamePhoneCodedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/phoneCodeGeoBatch:
    post:
      tags:
        - social
      summary: '[USES 11 UNITS PER NAME] Infer the likely country and phone prefix, of up to 100 personal names, with a local context (ISO2 country of residence).'
      operationId: phoneCodeGeoBatch
      requestBody:
        description: A list of personal names
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchFirstLastNamePhoneNumberGeoIn'
      responses:
        '200':
          description: A list of genderized names.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchFirstLastNamePhoneCodedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
  /api2/json/parseName/{nameFull}:
    get:
      tags:
        - personal
      summary: 'Infer the likely first/last name structure of a name, ex. John Smith or SMITH, John or SMITH; John. '
      operationId: parseName
      parameters:
        - name: nameFull
          in: path
          required: true
          schema:
            type: string
          description: Full name to infer
      responses:
        '200':
          description: A origined name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalNameParsedOut'
        '401':
          description: Missing or incorrect API Key
        '403':
          description: API Limit Reached or API Key Disabled
      security:
        - api_key: []
components:
  schemas:
    BatchFirstLastNameGenderedOut:
      type: object
      properties:
        personalNames:
          type: array
          description: Classified genderized names
          items:
            $ref: '#/components/schemas/FirstLastNameGenderedOut'
      description: Represents the output of inferring the LIKELY gender from a list of personal names.
      xml:
        name: BatchFirstLastNameGenderedOut
    FirstLastNamePhoneNumberIn:
      type: object
      properties:
        id:
          type: string
          xml:
            attribute: true
        firstName:
          type: string
          xml:
            attribute: true
        lastName:
          type: string
          xml:
            attribute: true
        phoneNumber:
          type: string
        FirstLastNameOriginedOut:
          $ref: '#/components/schemas/FirstLastNameOriginedOut'
      xml:
        name: FirstLastNamePhoneNumberIn
    APICounterV2Out:
      type: object
      properties:
        apiKey:
          $ref: '#/components/schemas/APIKeyOut'
        apiService:
          type: string
          description: The apiService corresponds to the classifier name.
        createdDateTime:
          type: integer
          description: The create datetime of the counter.
          format: int64
        totalUsage:
          type: integer
          description: The usage of the counter.
          format: int64
        lastFlushedDateTime:
          type: integer
          description: The flush datetime of the counter.
          format: int64
        lastUsedDateTime:
          type: integer
          description: The last usage datetime of the counter.
          format: int64
        serviceFeaturesUsage:
          type: object
          additionalProperties:
            type: integer
            description: Usage of special features, such as Chinese, Japanese.
            format: int64
          description: Usage of special features, such as Chinese, Japanese.
      description: Detailed usage as reported by the deduplicating API counter.
      xml:
        name: APICallStatOut
    NameMatchCandidatesOut:
      type: object
      properties:
        script:
          type: string
          description: Script
        id:
          type: string
          description: Id
        firstName:
          type: string
          description: The first name (also known as given name)
        lastName:
          type: string
          description: The last name (also known as family name, or surname)
        orderOption:
          type: string
          description: The option for ordering
        matchCandidates:
          type: array
          description: The ordered list of name matching candidates
          items:
            $ref: '#/components/schemas/NameMatchCandidateOut'
      description: Classified matched names
      xml:
        name: NameMatchCandidatesOut
    SoftwareVersionOut:
      type: object
      properties:
        softwareNameAndVersion:
          type: string
          description: The software version
        softwareVersion:
          type: array
          description: The software version major minor build
          items:
            type: integer
            description: The software version major minor build
            format: int32
      description: The software version.
      xml:
        name: SoftwareVersionOut
    APIClassifierOut:
      type: object
      properties:
        classifierName:
          type: string
          description: The classifier name
        serving:
          type: boolean
          description: True if the classifier is serving requests (has reached minimal learning, is not shutting down)
        learning:
          type: boolean
          description: True if the classifier is learning
        shuttingDown:
          type: boolean
          description: True if the classifier is shutting down
        probabilityCalibrated:
          type: boolean
          description: True if the classifier has finished the initial learning and calibrated probabilities (meanwhile, during initial learning, probabilities will be equal to -1)
      description: The list of classifiers and versions.
      xml:
        name: APIClassifierOut
    NameIn:
      type: object
      properties:
        id:
          type: string
          xml:
            attribute: true
        name:
          type: string
          xml:
            attribute: true
      xml:
        name: NameIn
    APIPlanSubscriptionOut:
      type: object
      properties:
        apiKey:
          type: string
          description: User API Key.
        planStarted:
          type: integer
          description: Datetime when the user subscribed to the current plan.
          format: int64
        priorPlanStarted:
          type: integer
          description: Datetime when the user subscribed to the prior plan.
          format: int64
        planEnded:
          type: integer
          description: Datetime when the user ended the plan.
          format: int64
        taxRate:
          type: number
          description: Applicable tax rate for the plan.
          format: double
        planName:
          type: string
          description: Current plan name.
        planBaseFeesKey:
          type: string
          description: Current plan key (as in Stripe product).
        planStatus:
          type: string
          description: Plan status.
        planQuota:
          type: integer
          description: 'Current plan quota in quantity of units (NB: some API use several units per name).'
          format: int64
        priceUSD:
          type: number
          description: Current plan monthly price expressed in USD (includes a free quota).
          format: double
        priceOverageUSD:
          type: number
          description: Current plan price for overages expressed in USD (extra price per unit above the free quota).
          format: double
        price:
          type: number
          description: Current plan price for overages expressed in Currency (extra price per unit above the free quota).
          format: double
        priceOverage:
          type: number
          description: Current plan price for overages expressed in Currency (extra price per unit above the free quota).
          format: double
        currency:
          type: string
          description: Current plan Currency for prices.
        currencyFactor:
          type: number
          description: For USD, GBP, EUR - the factor is 1.
          format: double
        stripeCustomerId:
          type: string
          description: Stripe customer identifier.
        stripeStatus:
          type: string
          description: Stripe status ex active.
        stripeSubscription:
          type: string
          description: Stripe subscription identifier.
        userId:
          type: string
          description: Internal user identifier.
      description: The API Plan governing the subscription.
      xml:
        name: APIPlanSubscriptionOut
    FirstLastNameGenderIn:
      type: object
      properties:
        id:
          type: string
          xml:
            attribute: true
        firstName:
          type: string
          xml:
            attribute: true
        lastName:
          type: string
          xml:
            attribute: true
        gender:
          type: string
          description: The known gender of the name
          xml:
            attribute: true
      xml:
        name: FirstLastName
    FirstLastNameGeoIn:
      description:  First name related to transnational interaction
      type: object
      properties:
        id:
          type: string
          description:  Id
          xml:
            attribute: true
        firstName:
          type: string
          description:  First name
          xml:
            attribute: true
        lastName:
          type: string
          description:  Last name
          xml:
            attribute: true
        countryIso2:
          type: string
          description:  ISO2 country code
          xml:
            attribute: true
      xml:
        name: FirstLastNameGeoIn
    FirstLastNameGenderedOut:
      type: object
      properties:
        script:
          type: string
          description: Script
        id:
          type: string
          description: Id
        firstName:
          type: string
          description: The first name (also known as given name)
        lastName:
          type: string
          description: The last name (also known as family name, or surname)
        likelyGender:
          type: string
          description: Most likely gender
          enum:
            - male
            - female
            - unknown
        genderScale:
          type: number
          description: Compatibility to NamSor_v1 Gender Scale M[-1..U..+1]F value
          format: double
        score:
          maximum: 100
          minimum: 0
          type: number
          description: 'Compatibility to NamSor_v1 Gender score value. Higher score is better, but score is not normalized. Use calibratedProbability if available. '
          format: double
        probabilityCalibrated:
          type: number
          description: The calibrated probability for inferred gender to have been guessed correctly.
          format: double
      description: Represents the output of inferring the LIKELY gender from a personal name.
      xml:
        name: FirstLastNameGenderedOut
    APIKeyOut:
      type: object
      properties:
        apiKey:
          type: string
          description: The user API Key.
          xml:
            name: api_key
        userId:
          type: string
          description: The user identifier.
        admin:
          type: boolean
          description: The API Key has admin role.
        vetted:
          type: boolean
          description: The API Key is vetted (assumed truthful) for machine learning.
        learnable:
          type: boolean
          description: The API Key is learnable (without assuming truthfulness) for machine learning. Set learnable=false and anonymized=true for highest privacy (ie. to forget data as it's processed).
        anonymized:
          type: boolean
          description: The API Key is anonymized (using SHA-252 digest for logging). Set learnable=false and anonymized=true for highest privacy (ie. to forget data as it's processed).
        partner:
          type: boolean
          description: The API Key has partner role.
        striped:
          type: boolean
          description: The API Key is associated to a valid Stripe account.
        corporate:
          type: boolean
          description: The API Key has role corporate (ex SWIFT payments instead of Stripe payments).
        disabled:
          type: boolean
          description: The API Key is temporarily or permanently disabled.
      description: The API Key.
      xml:
        name: APIKeyOut
    BatchFirstLastNameDiasporaedOut:
      type: object
      properties:
        personalNames:
          type: array
          description: Classified diaspora names
          items:
            $ref: '#/components/schemas/FirstLastNameDiasporaedOut'
      description: Represents the output of inferring the LIKELY ethnicity from a personal name, given an country of residence.
      xml:
        name: BatchFirstLastNameDiasporaedOut
    BatchPersonalNameGeoOut:
      type: object
      properties:
        personalNames:
          type: array
          description: Classified geo names
          items:
            $ref: '#/components/schemas/PersonalNameGeoOut'
      xml:
        name: BatchPersonalNameGeoOut
    APIClassifiersStatusOut:
      type: object
      properties:
        softwareVersion:
          $ref: '#/components/schemas/SoftwareVersionOut'
        classifiers:
          type: array
          description: The list of classifiers and versions.
          items:
            $ref: '#/components/schemas/APIClassifierOut'
      xml:
        name: APIClassifiersStatusOut
    ProperNounCategorizedOut:
      type: object
      properties:
        script:
          type: string
          description: Script
        id:
          type: string
          description: Id
        name:
          type: string
          description: The input name
        commonType:
          type: string
          description: The most likely common name type
        commonTypeAlt:
          type: string
          description: 'Best alternative for : The most likely common name type'
        score:
          maximum: 100
          minimum: 0
          type: number
          description: 'Higher score is better, but score is not normalized. Use calibratedProbability if available. '
          format: double
      description: Classified typed proper names
      xml:
        name: ProperNounCategorizedOut
    PersonalNameGenderedOut:
      type: object
      properties:
        script:
          type: string
          description: Script
        id:
          type: string
          description: Id
        name:
          type: string
          description: The input name
        likelyGender:
          type: string
          description: Most likely gender
          enum:
            - male
            - female
            - unknown
        genderScale:
          type: number
          description: Compatibility to NamSor_v1 Gender Scale M[-1..U..+1]F value
          format: double
        score:
          maximum: 100
          minimum: 0
          type: number
          description: 'Compatibility to NamSor_v1 Gender score value. Higher score is better, but score is not normalized. Use calibratedProbability if available. '
          format: double
        probabilityCalibrated:
          type: number
          description: The calibrated probability for inferred gender to have been guessed correctly.
          format: double
      description: Classified genderized names
      xml:
        name: PersonalNameGenderedOut
    FirstLastNameOriginedOut:
      type: object
      properties:
        script:
          type: string
          description: Script
        id:
          type: string
          description: Id
        firstName:
          type: string
          description: The first name (also known as given name)
        lastName:
          type: string
          description: The last name (also known as family name, or surname)
        countryOrigin:
          type: string
          description: Most likely country of Origin
        countryOriginAlt:
          type: string
          description: 'Second best alternative : country of Origin'
        countriesOriginTop:
          type: array
          description: List countries of Origin (top 10)
          items:
            type: string
            description: List countries of Origin (top 10)
        score:
          maximum: 100
          minimum: 0
          type: number
          description: 'Compatibility to NamSor_v1 Origin score value. Higher score is better, but score is not normalized. Use calibratedProbability if available. '
          format: double
        regionOrigin:
          type: string
          description: Most likely region of Origin (based on countryOrigin ISO2 code)
        topRegionOrigin:
          type: string
          description: Most likely top region of Origin (based on countryOrigin ISO2 code)
        subRegionOrigin:
          type: string
          description: Most likely sub region of Origin (based on countryOrigin ISO2 code)
        probabilityCalibrated:
          type: number
          description: The calibrated probability for countryOrigin to have been guessed correctly.
          format: double
        probabilityAltCalibrated:
          type: number
          description: The calibrated probability for countryOrigin OR countryOriginAlt to have been guessed correctly.
          format: double
      description: Represents the output of inferring the LIKELY country of Origin from a personal name.
      xml:
        name: FirstLastNameOriginedOut
    BatchNameGeoIn:
      type: object
      properties:
        properNouns:
          type: array
          items:
            $ref: '#/components/schemas/NameGeoIn'
      xml:
        name: BatchNameGeoIn
    BatchFirstLastNameGenderIn:
      type: object
      properties:
        personalNames:
          type: array
          items:
            $ref: '#/components/schemas/FirstLastNameGenderIn'
      xml:
        name: BatchFirstLastNameGenderIn
    CorridorOut:
      type: object
      properties:
        id:
          type: string
          description: Id
          xml:
            attribute: true
        FirstLastNameGenderedOut:
          $ref: '#/components/schemas/FirstLastNameGenderedOut'
        FirstLastNameOriginedOut:
          $ref: '#/components/schemas/FirstLastNameOriginedOut'
        FirstLastNameDiasporaedOut:
          $ref: '#/components/schemas/FirstLastNameDiasporaedOut'
        script:
          type: string
          description: Script
      description: Represent multiple classifications for corridor sender and receiver (gender, country, origin, diaspora)
      xml:
        name: CorridorOut
    BatchNameMatchedOut:
      type: object
      properties:
        matchedNames:
          type: array
          description: Classified matched names
          items:
            $ref: '#/components/schemas/NameMatchedOut'
      xml:
        name: BatchNameMatchedOut
    BatchNameMatchCandidatesOut:
      type: object
      properties:
        namesAndMatchCandidates:
          type: array
          description: Classified matched names
          items:
            $ref: '#/components/schemas/NameMatchCandidatesOut'
      xml:
        name: BatchNameMatchCandidatesOut
    BatchPersonalNameParsedOut:
      type: object
      properties:
        personalNames:
          type: array
          description: Classified parsed names
          items:
            $ref: '#/components/schemas/PersonalNameParsedOut'
      xml:
        name: BatchPersonalNameParsedOut
    FirstLastNameDiasporaedOut:
      type: object
      properties:
        script:
          type: string
          description: Script
        id:
          type: string
          description: Id
        firstName:
          type: string
          description: The first name (also known as given name)
        lastName:
          type: string
          description: The last name (also known as family name, or surname)
        score:
          maximum: 100
          minimum: 0
          type: number
          description: 'Compatibility to NamSor_v1 Diaspora score value. Higher score is better, but score is not normalized. Use calibratedProbability if available. '
          format: double
        ethnicityAlt:
          type: string
          description: The second best alternative ethnicity
          example: Japanese
          xml:
            attribute: true
        ethnicity:
          type: string
          description: The most likely ethnicity
          example: Chinese
          xml:
            attribute: true
        lifted:
          type: boolean
          description: Indicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule. Let us know if you believe ethnicity is incorrect on a specific case where lifted is true.
          xml:
            attribute: true
        countryIso2:
          type: string
          description: From input data, the countryIso2 of geographic context (US,CA etc.)
          xml:
            attribute: true
        ethnicitiesTop:
          type: array
          description: List most likely ethnicities (top 10)
          items:
            type: string
            description: List most likely ethnicities (top 10)
      description: Represents the output of inferring the LIKELY ethnicity from a personal name, given an country of residence.
      xml:
        name: FirstLastNameDiasporaedOut
    BatchPersonalNameGenderedOut:
      type: object
      properties:
        personalNames:
          type: array
          description: Classified genderized names
          items:
            $ref: '#/components/schemas/PersonalNameGenderedOut'
      xml:
        name: BatchPersonalNameGenderedOut
    FeedbackLoopOut:
      type: object
      properties:
        feedbackCredits:
          type: integer
          description: Number of units recredited as per feedback loop successful classification
          format: int64
      xml:
        name: FeedbackLoopOut
    APIBillingPeriodUsageOut:
      type: object
      properties:
        apiKey:
          type: string
          description: User API Key.
        subscriptionStarted:
          type: integer
          description: Datetime when the user subscribed to the plan.
          format: int64
        periodStarted:
          type: integer
          description: Datetime when the the plan's current period started.
          format: int64
        periodEnded:
          type: integer
          description: Datetime when the the plan's current period endend.
          format: int64
        stripeCurrentPeriodEnd:
          type: integer
          description: Datetime when the the plan's current period endend (in Stripe). Internal and Stripe periodicity should ~coincide.
          format: int64
        stripeCurrentPeriodStart:
          type: integer
          description: Datetime when the the plan's current period started (in Stripe). Internal and Stripe periodicity should ~coincide.
          format: int64
        billingStatus:
          type: string
          description: Current period billing status ex OPEN.
        usage:
          type: integer
          description: Current period usage in units (NB some API endpoints use more than one unit).
          format: int64
        softLimit:
          type: integer
          description: Current period soft limit (reaching the limit sends an email notification).
          format: int64
        hardLimit:
          type: integer
          description: Current period hard limit (reaching the limit sends an email notification and blocks the API Key).
          format: int64
      description: The current billing period.
      xml:
        name: APIBillingPeriodUsageOut
    APIPeriodUsageOut:
      type: object
      properties:
        subscription:
          $ref: '#/components/schemas/APIPlanSubscriptionOut'
        billingPeriod:
          $ref: '#/components/schemas/APIBillingPeriodUsageOut'
        overageExclTax:
          type: number
          description: Overage amount including any tax.
          format: double
        overageInclTax:
          type: number
          description: Overage amount including tax (if applicable).
          format: double
        overageCurrency:
          type: string
          description: Currency of the overage amount.
        overageQuantity:
          type: integer
          description: Quantity above monthly quota of the current subscritpion, in units.
          format: int64
      xml:
        name: APICurrentUsageOut
    PersonalNameIn:
      type: object
      properties:
        id:
          type: string
          xml:
            attribute: true
        name:
          type: string
          xml:
            attribute: true
      xml:
        name: PersonalNameIn
    BatchCorridorIn:
      type: object
      properties:
        corridorFromTo:
          type: array
          items:
            $ref: '#/components/schemas/CorridorIn'
      xml:
        name: BatchCorridorIn
    APIUsageAggregatedOut:
      type: object
      properties:
        timeUnit:
          type: string
          description: Time unit is DAY, WEEK or MONTH depending on prior usage
        periodStart:
          type: integer
          description: Start datetime of the reporting period
          format: int64
        periodEnd:
          type: integer
          description: End datetime of the reporting period
          format: int64
        totalUsage:
          type: integer
          description: Total usage in the current period
          format: int64
        historyTruncated:
          type: boolean
          description: If the history was truncaded due to data limit
        data:
          type: array
          description: 'Data points : usage per DAY, WEEK or MONTH and per apiService'
          items:
            type: array
            description: 'Data points : usage per DAY, WEEK or MONTH and per apiService'
            items:
              type: integer
              description: 'Data points : usage per DAY, WEEK or MONTH and per apiService'
              format: int32
        colHeaders:
          type: array
          description: 'apiServices as column headers '
          items:
            type: string
            description: 'apiServices as column headers '
        rowHeaders:
          type: array
          description: 'dates as row headers '
          items:
            type: string
            description: 'dates as row headers '
      xml:
        name: APIUsageAggregatedOut
    APIServicesOut:
      type: object
      properties:
        apiServices:
          type: array
          description: List of API Services
          items:
            $ref: '#/components/schemas/APIServiceOut'
      xml:
        name: APIServicesOut
    BatchNameIn:
      type: object
      properties:
        properNouns:
          type: array
          items:
            $ref: '#/components/schemas/NameIn'
      xml:
        name: BatchNameIn
    FirstLastNameOut:
      type: object
      properties:
        script:
          type: string
          description: Script
        id:
          type: string
          description: Id
        firstName:
          type: string
          description: The first name (also known as given name)
        lastName:
          type: string
          description: The last name (also known as family name, or surname)
      description: First / last name structure corresponding to the most likely parsing.
      xml:
        name: FirstLastNameOut
    BatchFirstLastNameUSRaceEthnicityOut:
      type: object
      properties:
        personalNames:
          type: array
          description: Classified US 'race'/ethnicized names
          items:
            $ref: '#/components/schemas/FirstLastNameUSRaceEthnicityOut'
      description: Represents the output of inferring the LIKELY US 'race/ethnicity' from a personal name, given US country of residence and (optionally) a ZIP5 code.
      xml:
        name: BatchFirstLastNameUSRaceEthnicityOut
    BatchPersonalNameIn:
      type: object
      properties:
        personalNames:
          type: array
          items:
            $ref: '#/components/schemas/PersonalNameIn'
      xml:
        name: BatchPersonalNameIn
    BatchFirstLastNamePhoneNumberIn:
      type: object
      properties:
        personalNamesWithPhoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/FirstLastNamePhoneNumberIn'
      xml:
        name: BatchFirstLastNamePhoneNumberIn
    NameGeoIn:
      type: object
      properties:
        id:
          type: string
          xml:
            attribute: true
        name:
          type: string
          xml:
            attribute: true
        countryIso2:
          type: string
          xml:
            attribute: true
      xml:
        name: NameGeoIn
    FirstLastNamePhoneCodedOut:
      type: object
      properties:
        script:
          type: string
          description: Script
        id:
          type: string
          description: Id
        firstName:
          type: string
          description: The first name (also known as given name)
        lastName:
          type: string
          description: The last name (also known as family name, or surname)
        internationalPhoneNumberVerified:
          type: string
          description: The normalized phone number, verified using libphonenumber.
        phoneCountryIso2Verified:
          type: string
          description: The phone ISO2 country code, verified using libphonenumber.
        phoneCountryCode:
          type: integer
          description: The phone country code of the phone number, verified using libphonenumber.
          format: int32
        phoneCountryCodeAlt:
          type: integer
          description: The best alternative phone country code of the phone number.
          format: int32
        phoneCountryIso2:
          type: string
          description: The likely country of the phone number.
        phoneCountryIso2Alt:
          type: string
          description: The best alternative country of the phone number.
        originCountryIso2:
          type: string
          description: The likely country of origin of the name.
        originCountryIso2Alt:
          type: string
          description: The best alternative country of origin of the name.
        phoneNumber:
          type: string
          description: The input phone number.
        verified:
          type: boolean
          description: Indicates if the phone number could be positively verified using libphonenumber.
        score:
          maximum: 100
          minimum: 0
          type: number
          description: 'Higher score is better, but score is not normalized. Use calibratedProbability if available. '
          format: double
        countryIso2:
          type: string
          description: ISO2 country code
      description: Represents the output of inferring the LIKELY country and phone code from a personal name and phone number.
      xml:
        name: FirstLastNamePhoneCodedOut
    MatchPersonalFirstLastNameIn:
      type: object
      properties:
        id:
          type: string
          xml:
            attribute: true
        name1:
          $ref: '#/components/schemas/FirstLastNameIn'
        name2:
          $ref: '#/components/schemas/PersonalNameIn'
      xml:
        name: MatchPersonalFirstLastNameIn
    PersonalNameParsedOut:
      type: object
      properties:
        script:
          type: string
          description: Script
        id:
          type: string
          description: Id
        name:
          type: string
          description: The input name
        nameParserType:
          type: string
          description: Name parsing is addressed as a classification problem, for example FN1LN1 means a first then last name order.
        nameParserTypeAlt:
          type: string
          description: Second best alternative parsing. Name parsing is addressed as a classification problem, for example FN1LN1 means a first then last name order.
        firstLastName:
          $ref: '#/components/schemas/FirstLastNameOut'
        score:
          maximum: 100
          minimum: 0
          type: number
          description: 'Higher score is better, but score is not normalized. Use calibratedProbability if available. '
          format: double
      xml:
        name: PersonalNameParsedOut
    BatchFirstLastNameGeoZippedIn:
      type: object
      properties:
        personalNames:
          type: array
          items:
            $ref: '#/components/schemas/FirstLastNameGeoZippedIn'
      xml:
        name: BatchFirstLastNameGeoZippedIn
    BatchFirstLastNameOriginedOut:
      type: object
      properties:
        personalNames:
          type: array
          description: Classified origined names
          items:
            $ref: '#/components/schemas/FirstLastNameOriginedOut'
      description: Represents the output of inferring the LIKELY origin from a list of personal names.
      xml:
        name: BatchFirstLastNameOriginedOut
    FirstLastNameGeoZippedIn:
      type: object
      properties:
        id:
          type: string
          xml:
            attribute: true
        firstName:
          type: string
          xml:
            attribute: true
        lastName:
          type: string
          xml:
            attribute: true
        countryIso2:
          type: string
          xml:
            attribute: true
        zipCode:
          type: string
          xml:
            attribute: true
      xml:
        name: FirstLastNameGeoZippedIn
    CorridorIn:
      type: object
      properties:
        id:
          type: string
          description: Id
          xml:
            attribute: true
        firstLastNameGeoFrom:
          $ref: '#/components/schemas/FirstLastNameGeoIn'
        firstLastNameGeoTo:
          $ref: '#/components/schemas/FirstLastNameGeoIn'
      description: Represent any transnational interaction between names (ex. remittance, communication, cross-border investment, airline travel
      xml:
        name: CorridorIn
    BatchCorridorOut:
      type: object
      properties:
        corridorFromTo:
          type: array
          description: Classified corridors
          items:
            $ref: '#/components/schemas/CorridorOut'
      xml:
        name: BatchCorridorOut
    BatchPersonalNameGeoIn:
      type: object
      properties:
        personalNames:
          type: array
          items:
            $ref: '#/components/schemas/PersonalNameGeoIn'
      xml:
        name: BatchPersonalNameGeoIn
    FirstLastNameIn:
      type: object
      properties:
        id:
          type: string
          xml:
            attribute: true
        firstName:
          type: string
          xml:
            attribute: true
        lastName:
          type: string
          xml:
            attribute: true
      xml:
        name: FirstLastName
    APIClassifierTaxonomyOut:
      type: object
      properties:
        classifierName:
          type: string
          description: Name of the classifier as per apiStatus (corresponds also to the name of the service in apiServices)
        taxonomyClasses:
          type: array
          description: The taxonomy classes this classifier classifies to
          items:
            type: string
            description: The taxonomy classes this classifier classifies to
      xml:
        name: APIClassifierTaxonomyOut
    NameMatchCandidateOut:
      type: object
      properties:
        candidateName:
          type: string
          description: The name matching candidate name
        probability:
          type: number
          description: The name matching estimated probability.
          format: double
        predScoreGivenName:
          type: number
          description: The given name prediction score.
          format: double
        predScoreFamilyName:
          type: number
          description: The family name prediction score.
          format: double
      description: The ordered list of name matching candidates
      xml:
        name: NameMatchCandidateOut
    APIUsageHistoryOut:
      type: object
      properties:
        detailedUsage:
          type: array
          description: Detailed usage as reported by the deduplicating API counter.
          items:
            $ref: '#/components/schemas/APICounterV2Out'
      xml:
        name: APIUsageHistoryOut
    BatchFirstLastNamePhoneCodedOut:
      type: object
      properties:
        personalNamesWithPhoneNumbers:
          type: array
          description: Classified phone-coded names
          items:
            $ref: '#/components/schemas/FirstLastNamePhoneCodedOut'
      description: Represents the output of inferring the LIKELY country and phone code of personal names+phones.
      xml:
        name: BatchFirstLastNamePhoneCodedOut
    FirstLastNameUSRaceEthnicityOut:
      type: object
      properties:
        script:
          type: string
          description: Script
        id:
          type: string
          description: Id
        firstName:
          type: string
          description: The first name (also known as given name)
        lastName:
          type: string
          description: The last name (also known as family name, or surname)
        raceEthnicityAlt:
          type: string
          description: Second most likely US 'race'/ethnicity
          xml:
            attribute: true
          enum:
            - W_NL
            - HL
            - A
            - B_NL
            - AI_AN
            - PI
        raceEthnicity:
          type: string
          description: Most likely US 'race'/ethnicity
          xml:
            attribute: true
          enum:
            - W_NL
            - HL
            - A
            - B_NL
            - AI_AN
            - PI
        score:
          maximum: 100
          minimum: 0
          type: number
          description: 'Higher score is better, but score is not normalized. Use calibratedProbability if available. '
          format: double
        raceEthnicitiesTop:
          type: array
          description: List 'race'/ethnicities
          items:
            type: string
            description: List 'race'/ethnicities
        probabilityCalibrated:
          type: number
          description: The calibrated probability for raceEthnicity to have been guessed correctly.
          format: double
        probabilityAltCalibrated:
          type: number
          description: The calibrated probability for raceEthnicity OR raceEthnicityAlt to have been guessed correctly.
          format: double
      description: Represents the output of inferring the LIKELY US 'race/ethnicity' from a personal name, given US country of residence and (optionally) a ZIP5 code.
      xml:
        name: FirstLastNameUSRaceEthnicityOut
    BatchFirstLastNamePhoneNumberGeoIn:
      type: object
      properties:
        personalNamesWithPhoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/FirstLastNamePhoneNumberGeoIn'
      xml:
        name: BatchFirstLastNamePhoneNumberGeoIn
    PersonalNameGeoIn:
      type: object
      properties:
        id:
          type: string
          xml:
            attribute: true
        name:
          type: string
          xml:
            attribute: true
        countryIso2:
          type: string
          xml:
            attribute: true
      xml:
        name: PersonalNameGeoIn
    APIServiceOut:
      type: object
      properties:
        serviceName:
          type: string
          description: A service name corresponds to classifier name in apiStatus (ex. personalname_gender or personalfullname_gender)
        serviceGroup:
          type: string
          description: Groups together classifiers providing a similar service (ex. gender groups personalname_gender and personalfullname_gender)
        costInUnits:
          type: integer
          description: Indicates how many units per call this service costs (ex. the number of units per name)
          format: int32
      description: List of API Services
      xml:
        name: APIServiceOut
    BatchProperNounCategorizedOut:
      type: object
      properties:
        properNouns:
          type: array
          description: Classified typed proper names
          items:
            $ref: '#/components/schemas/ProperNounCategorizedOut'
      description: Represents the output of inferring the common type (anthroponym, toponym, brand, etc.) from a list of proper names.
      xml:
        name: BatchProperNounCategorizedOut
    BatchFirstLastNameIn:
      type: object
      properties:
        personalNames:
          type: array
          items:
            $ref: '#/components/schemas/FirstLastNameIn'
      xml:
        name: BatchFirstLastNameIn
    NameMatchedOut:
      type: object
      properties:
        script:
          type: string
          description: Script
        id:
          type: string
          description: Id
        matchStatus:
          type: string
          description: The name matching status.
        score:
          type: number
          format: double
          description: Score.
      description: Classified matched names
      xml:
        name: NameMatchedOut
    BatchMatchPersonalFirstLastNameIn:
      type: object
      properties:
        personalNames:
          type: array
          items:
            $ref: '#/components/schemas/MatchPersonalFirstLastNameIn'
      xml:
        name: BatchMatchPersonalFirstLastNameIn
    FirstLastNamePhoneNumberGeoIn:
      type: object
      properties:
        id:
          type: string
          xml:
            attribute: true
        firstName:
          type: string
          xml:
            attribute: true
        lastName:
          type: string
          xml:
            attribute: true
        phoneNumber:
          type: string
        FirstLastNameOriginedOut:
          $ref: '#/components/schemas/FirstLastNameOriginedOut'
        countryIso2:
          type: string
        countryIso2Alt:
          type: string
      xml:
        name: FirstLastNamePhoneNumberGeoIn
    PersonalNameGeoOut:
      type: object
      properties:
        script:
          type: string
          description: Script
        id:
          type: string
          description: Id
        name:
          type: string
          description: The input name.
        score:
          maximum: 100
          minimum: 0
          type: number
          description: 'Higher score is better, but score is not normalized. Use calibratedProbability if available. '
          format: double
        country:
          type: string
          description: 'Most likely country '
        countryAlt:
          type: string
          description: 'Second best alternative : country '
        region:
          type: string
          description: Most likely region (based on country ISO2 code)
        topRegion:
          type: string
          description: Most likely top region (based on country ISO2 code)
        subRegion:
          type: string
          description: Most likely sub region (based on country ISO2 code)
        countriesTop:
          type: array
          description: List countries (top 10)
          items:
            type: string
            description: List countries (top 10)
        probabilityCalibrated:
          type: number
          description: The calibrated probability for country to have been guessed correctly.
          format: double
        probabilityAltCalibrated:
          type: number
          description: The calibrated probability for country OR countryAlt to have been guessed correctly.
          format: double
      description: Classified geo names
      xml:
        name: PersonalNameGeoOut
    BatchFirstLastNameGeoIn:
      type: object
      properties:
        personalNames:
          type: array
          items:
            $ref: '#/components/schemas/FirstLastNameGeoIn'
      xml:
        name: BatchFirstLastNameGeoIn
  securitySchemes:
    api_key:
      type: apiKey
      description: All requests on the NamSor API needs to include an API key. The API key can be provided as part of the query string or as a request header. The name of the API key needs to be `X-API-KEY`
      name: X-API-KEY
      in: header

