# SAID name match

The South African name match service provides automated, remote identity verification for individuals within South Africa. It uses a person's South African ID number (SAID) together with their first name and last name to check against official records. The service returns a match score along with a detailed description of the verification outcome, enabling quick and reliable identity checks

Endpoint: POST /services/za/said/name-match
Version: 1.0
Security: API-Key

## Security:

  - `API-Key` (unknown)
    apiKey in header API-Key

## Request fields (application/json):

  - `said_number` (string, required)
    South African 13-digit national identity number in the format YYMMDDSSSSCAZ: YYMMDD is the date of birth, SSSS is a gender code (0000-4999 female, 5000-9999 male), C is the citizenship indicator   (0 citizen, 1 permanent resident), A is a historical digit, and Z is  a Luhn checksum digit.
    Example: 8001015009031

  - `first_name` (string, required)
    Example: Josh

  - `last_name` (string, required)
    Example: Coffey

  - `name_match_threshold` (number, required)
    The minimum similarity score required to include a name in the search results. A higher value returns fewer, more exact matches, and a lower value returns more results with less similarity
    Example: 0.75

## Response 200:

  - `200` (unknown)
    **OK**
The request was successful, and our system returned an expected response.

## Response 200 fields (application/json):

  - `validation` (object)

  - `validation.valid` (any)
    Example: true

  - `data` (object)

  - `data.first_name` (string | null)
    The first name of a person
    Example: Josh

  - `data.last_name` (string | null)
    The last name of a person
    Example: Coffey

  - `data.service_first_name` (string)
    The first name returned by an external service for comparison with the submitted value
    Example: Josh

  - `data.service_last_name` (string)
    The last name returned by an external service for comparison with the submitted value
    Example: Cofey

  - `data.dob` (string | null)
    The date of birth of a person, formatted as “YYYY-MM-DD” according to ISO 8601
    Example: 1976-02-21

  - `data.gender` (string | null)
    The gender of a person. `M` indicates male; `F` indicates female
    Enum: "M", "F"

  - `data.is_citizen` (boolean)
    Indicates whether the person is a South African citizen. True for a citizen, false for a permanent resident. Derived from the eleventh digit of the South African ID number (0 for citizen, 1 for permanent resident)
    Example: true

  - `data.name_match_threshold` (number)
    The minimum similarity score required to include a name in the search results. A higher value returns fewer, more exact matches, and a lower value returns more results with less similarity
    Example: 0.75

  - `data.name_match_score` (number)
    Relevance of a name match in a fuzzy search
    Example: 0.8

## Response 400:

  - `400` (unknown)
    **Bad Request**
Our system could not process the request due to invalid syntax, missing parameters, or incorrect data format. Check the request structure and try again.

## Response 400 fields (application/json):

  - `type` (string)
    Example: bad_request

  - `errors` (array)

## Response 402:

  - `402` (unknown)
    **Payment Required**
Access to the requested resource is restricted until a payment is successfully processed. Ensure your account has a valid payment method or sufficient funds to complete this action.

## Response 402 fields (application/json):

  - `type` (string)
    Example: insufficient_funds

  - `errors` (array)

## Response 404:

  - `404` (unknown)
    **Not Found**
The requested resource does not exist or can’t be found in our system.

## Response 500:

  - `500` (unknown)
    **Internal Server Error**
This response indicates that our system encountered an unexpected condition that prevented it from fulfilling the request.

## Response 500 fields (application/json):

  - `type` (string)
    Example: internal_server

  - `errors` (array)

## Response 502:

  - `502` (unknown)
    **Bad Gateway**
This response indicates that our system is unable to reach or communicate properly with an upstream server it relies on, the URL provided is incorrect, or a required token is missing from the request.