{
  "openapi": "3.0.1",
  "info": {
    "title": "Name Parsing API",
    "description": "The Name Parsing API accomplishes the following:\n- Determines the type of a name to describe the function that the name performs. Name entity types are divided into two major groups: personal names and business names. Within each of these major groups are subgroups.\n- Determines the form of a name to understand which syntax the parser should follow for parsing. Personal names usually take on a natural (signature) or reverse order. Business names are usually ordered hierarchically.\n- Determines and labels the component parts of a name so that the syntactical relationship of each name part to the entire name is identified. The personal name syntax includes prefixes, first, middle, and last name parts, suffixes, and account description terms, among other personal name parts. The business name syntax includes the firm name and suffix terms.\n- Parses conjoined personal and business names and either retains them as one record or splits them into multiple records. Examples of conjoined names include \"Mr. and Mrs. John Smith\" and \"Baltimore Gas & Electric dba Constellation Energy\".\n- Assigns a parsing score that reflects the degree of confidence that the parsing is correct.\n\n<details>\n    <summary>Error Codes</summary>\n\nAPIs will return the following error codes in case of any error:\n\n\n| Error Code                 | Description\n|----------------------------|-------------------------------------------------------\n| DIS-1001                   | Unauthorized, Invalid token\n| DIS-1002                   | Not Authorized to access this API\n| DIS-1003                   | Issue with internal services\n| DIS-1004                   | Workspace Id is missing from Bearer Token\n| DIS-1005                   | Rate limit exceeded\n| DIS-1006                   | Unauthorized, Invalid key/secret\n| DIS-1007                   | API quota has been permanently exhausted. No further requests are allowed for trial user\n| DIS-1008                   | Invalid request ID, maximum allowed length is 38 characters\n| DIS-1009                   | Access blocked due to too many failed attempts. Please try again after sometime\n| DIS-1010                   | Workspace has been expired\n| DIS-NP-1018                | Request Body is not valid\n</details>\n",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.cloud.precisely.com"
    }
  ],
  "tags": [
    {
      "name": "Parsing",
      "description": "Operations related to Parser Service"
    }
  ],
  "paths": {
    "/v1/names/parse": {
      "post": {
        "tags": [
          "Parsing"
        ],
        "summary": "Parse the personal and business names",
        "description": "This endpoint will parse the personal and business names and other terms in the name data field into their component parts. These parsed name elements are then subsequently available to other automated operations such as name matching, name standardization, or multiple-record name consolidation.",
        "operationId": "parseName",
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "description": "The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.",
            "schema": {
              "type": "string"
            },
            "example": "123e4567-e89b-12d3-a456-426614174001"
          }
        ],
        "requestBody": {
          "description": "Request body for name parser",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InputData"
              },
              "examples": {
                "example": {
                  "value": {
                    "name": "Jack and Daniel Smith"
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Parsed Successfully!",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NameParserResponse"
                },
                "examples": {
                  "example": {
                    "value": {
                      "response": {
                        "status": "OK",
                        "result": {
                          "parsedAs": "Personal",
                          "firstName": "JACK",
                          "isParsed": "true",
                          "lastName": "SMITH",
                          "name": "Jack and Daniel Smith",
                          "parsingScore": "100",
                          "conjunction2": "AND",
                          "firstName2": "DANIEL"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "example": {
                    "value": {
                      "id": "b5afe60e-e83c-4f7e-9854-67d13f638ad7",
                      "errors": [
                        {
                          "code": "DIS-NP-1018",
                          "detail": "Request Body is not valid"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid Token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "example": {
                    "value": {
                      "id": "753a0288-490e-4035-9aa7-bc35f20ddc5c",
                      "errors": [
                        {
                          "code": "DIS-1001",
                          "detail": "Unauthorized"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "example": {
                    "value": {
                      "id": "b5afe60e-e83c-4f7e-4598-67d13f638ad7",
                      "errors": [
                        {
                          "code": "DIS-1002",
                          "detail": "You do not have permission to access this API"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "example": {
                    "value": {
                      "id": "b5afe60e-e83c-4f7e-4598-67d13f683ad7",
                      "errors": [
                        {
                          "code": "DIS-1005",
                          "detail": "Rate limit exceeded"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "example": {
                    "value": {
                      "id": "753a0288-59b7-4736-b642-8d351df9b7f5",
                      "errors": [
                        {
                          "code": "DIS-1003",
                          "detail": "Issue with internal services. Please try again after sometime"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "example": {
                    "value": {
                      "id": "b5afe60e-e83c-4f7e-9845-67d13f638ad7",
                      "errors": [
                        {
                          "code": "DIS-1003",
                          "detail": "Issue with internal services. Please try again after sometime"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorDetail": {
        "required": [
          "detail"
        ],
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "A unique code representing the specific error.",
            "example": "DIS-1001"
          },
          "detail": {
            "type": "string",
            "description": "A detailed message describing the error.",
            "example": "Unauthorized"
          }
        },
        "description": "Error details."
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the error.",
            "example": "ad45c1aded938181a05f256e5a1b594d"
          },
          "errors": {
            "type": "array",
            "description": "List of errors ",
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            }
          }
        },
        "description": "Error response."
      },
      "InputData": {
        "required": [
          "name"
        ],
        "type": "object",
        "properties": {
          "name": {
            "minLength": 1,
            "type": "string",
            "description": "The full name that needs to be parsed. It cannot be null or blank.",
            "example": "Mr. Jack Lauren & Daniel Smith"
          },
          "options": {
            "description": "Optional configurations to customize name parsing behavior.",
            "allOf": [
              {
                "$ref": "#/components/schemas/Options"
              }
            ]
          }
        },
        "description": "Input data for the Name Parser API, containing the name to be parsed and optional parsing configurations."
      },
      "NameParserResponse": {
        "required": [
          "response"
        ],
        "type": "object",
        "properties": {
          "response": {
            "description": "The detailed response containing status and parsed name information.",
            "allOf": [
              {
                "$ref": "#/components/schemas/Response"
              }
            ]
          }
        },
        "description": "Response object for the Name Parser API containing the parsing results."
      },
      "Options": {
        "type": "object",
        "properties": {
          "parseNaturalOrderPersonalNames": {
            "type": "boolean",
            "description": "Specifies whether to parse names where the name is in the order Title, First Name, Middle Name, Last Name, and Suffix",
            "example": true,
            "default": true
          },
          "parseReverseOrderPersonalNames": {
            "type": "boolean",
            "description": "Specifies whether to parse names where the last name is specified first.",
            "example": false,
            "default": true
          },
          "parseConjoinedNames": {
            "type": "boolean",
            "description": "Specifies whether to parse conjoined names or separate names containing more than one individual into multiple records, for example, Bill & Sally Smith",
            "example": false,
            "default": true
          },
          "parseBusinessNames": {
            "type": "boolean",
            "description": "Specifies whether to parse business names.",
            "example": false,
            "default": true
          }
        },
        "description": "Options are required only if parsing results need to be changed according to the data."
      },
      "ParsedName": {
        "required": [
          "isParsed",
          "name",
          "parsingScore"
        ],
        "type": "object",
        "properties": {
          "accountDescription": {
            "type": "string",
            "description": "Account description related to the name.",
            "example": "Business Account"
          },
          "names": {
            "type": "string",
            "description": "Full name in the input.",
            "example": "Mr. John Smith"
          },
          "parsedAs": {
            "type": "string",
            "description": "Specifies how the input name was parsed (e.g., 'personal' or 'firm').",
            "example": "personal"
          },
          "firmConjunction": {
            "type": "string",
            "description": "Conjunction for firm names (if any).",
            "example": "&"
          },
          "firmName": {
            "type": "string",
            "description": "Identified firm name.",
            "example": "Acme Corporation"
          },
          "firmSuffix": {
            "type": "string",
            "description": "Corporate suffix for the firm (e.g., Inc., LLC).",
            "example": "LLC"
          },
          "isFirm": {
            "type": "string",
            "description": "Indicates if the input name was parsed as a firm.",
            "example": "true"
          },
          "conjunction": {
            "type": "string",
            "description": "Conjunction for personal names",
            "example": "and"
          },
          "cultureCode": {
            "type": "string",
            "description": "Culture code",
            "example": "en-US"
          },
          "cultureCodeUsedToParse": {
            "type": "string",
            "description": "Culture code used to parse the name.",
            "example": "EN-US"
          },
          "firstName": {
            "type": "string",
            "description": "The first name identified for a person in the input.",
            "example": "Jane"
          },
          "generalSuffix": {
            "type": "string",
            "description": "General suffix",
            "example": "Sr."
          },
          "isParsed": {
            "minLength": 1,
            "type": "string",
            "description": "Flag indicating whether the name was parsed.",
            "example": "true"
          },
          "isPersonal": {
            "type": "string",
            "description": "Specifies if the input name was parsed as a person.",
            "example": "true"
          },
          "isReverseOrder": {
            "type": "string",
            "description": "Indicates if the name is in reverse order (e.g., Last Name, First Name).",
            "example": "false"
          },
          "lastName": {
            "type": "string",
            "description": "Last name identified for a person in the input.",
            "example": "Smith"
          },
          "leadingData": {
            "type": "string",
            "description": "Leading data",
            "example": "Mr."
          },
          "maturitySuffix": {
            "type": "string",
            "description": "Suffix for the person (e.g., Jr., Sr.).",
            "example": "Jr."
          },
          "middleName": {
            "type": "string",
            "description": "Middle name identified for a person in the input.",
            "example": "M."
          },
          "name": {
            "minLength": 1,
            "type": "string",
            "description": "Full name in the input.",
            "example": "Mr. John Smith"
          },
          "parsingScore": {
            "minLength": 1,
            "type": "string",
            "description": "Confidence score for name parsing (0-100).",
            "example": "95"
          },
          "secondaryLastName": {
            "type": "string",
            "description": "Secondary last name if identified.",
            "example": "Doe"
          },
          "titleOfRespect": {
            "type": "string",
            "description": "Honorific title identified for the person.",
            "example": "Mr."
          },
          "trailingData": {
            "type": "string",
            "description": "Trailing data in the input.",
            "example": "PhD"
          },
          "conjunction2": {
            "type": "string",
            "description": "Conjunction between the second and third name.",
            "example": "&"
          },
          "conjunction3": {
            "type": "string",
            "description": "Conjunction between the third and fourth name.",
            "example": "&"
          },
          "firmName2": {
            "type": "string",
            "description": "Name of the second firm in conjoined names",
            "example": "Acme Corporation"
          },
          "firmSuffix2": {
            "type": "string",
            "description": "Suffix for the second firm in conjoined names",
            "example": "LLC"
          },
          "firstName2": {
            "type": "string",
            "description": "First name for the second individual in conjoined names",
            "example": "John"
          },
          "firstName3": {
            "type": "string",
            "description": "First name for the third individual in conjoined names",
            "example": "Sarah"
          },
          "generalSuffix2": {
            "type": "string",
            "description": "General suffix for the second individual in conjoined names",
            "example": "Jr."
          },
          "generalSuffix3": {
            "type": "string",
            "description": "General suffix for the third individual in conjoined names",
            "example": "Sr."
          },
          "isConjoined": {
            "type": "string",
            "description": "Indicates if the input name is a conjoined name",
            "example": "true"
          },
          "lastName2": {
            "type": "string",
            "description": "Last name for the second individual in conjoined names",
            "example": "Smith"
          },
          "lastName3": {
            "type": "string",
            "description": "Last name for the third individual in conjoined names",
            "example": "Doe"
          },
          "maturitySuffix2": {
            "type": "string",
            "description": "Maturity suffix for the second individual in conjoined names",
            "example": "II"
          },
          "maturitySuffix3": {
            "type": "string",
            "description": "Maturity suffix for the third individual in conjoined names",
            "example": "III"
          },
          "middleName2": {
            "type": "string",
            "description": "Middle name for the second individual in conjoined names",
            "example": "Allen"
          },
          "middleName3": {
            "type": "string",
            "description": "Middle name for the third individual in conjoined names",
            "example": "Grace"
          },
          "titleOfRespect2": {
            "type": "string",
            "description": "Title of respect for the second individual in conjoined names",
            "example": "Dr."
          },
          "titleOfRespect3": {
            "type": "string",
            "description": "Title of respect for the third individual in conjoined names",
            "example": "Mrs."
          }
        },
        "description": "Parsed name information containing personal and firm name details."
      },
      "Response": {
        "required": [
          "status"
        ],
        "type": "object",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "result": {
            "description": "Detailed result of the parsed name, including all identified components.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ParsedName"
              }
            ]
          }
        },
        "description": "Response object containing the status of the request and the parsed name result."
      },
      "Status": {
        "type": "string",
        "description": "Represents the status of a response",
        "example": "OK",
        "enum": [
          "OK",
          "ZERO_RESULTS"
        ]
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "description": "Pass the value in the following format: Apikey <base64(api_key:api_secret)>.",
        "name": "Authorization",
        "in": "header"
      },
      "bearerAuth": {
        "type": "http",
        "description": "Pass the value as JWT Bearer Token.",
        "scheme": "bearer"
      }
    }
  }
}