> ## Documentation Index
> Fetch the complete documentation index at: https://docs.godiligent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Search

> Create a new name screening search to query providers for matches

## Behavior

* **New searches** begin with status `PENDING` and transition to `COMPLETED` or `FAILED`
* **Provider queries** run asynchronously and populate hits when matches are found
* **Search IDs** are UUIDs that can be used with the [Get Search](/api-reference/name-screening/get-search) endpoint

## Workflow

After creating a search, the system will:

1. Generate a unique search ID
2. Initialize the search with status `PENDING`
3. Query the configured screening provider
4. Populate hits array with any matches found
5. Update search status to `COMPLETED` and trigger a webhook, check [Webhooks](/guides/webhooks/working-with-webhooks#search-completed) for more details

If the provider query fails, the search status becomes `FAILED`.

Use this ID to:

* Check search status with [GET /name-screenings/searches/{id}](/api-reference/name-screening/get-search)
* Retrieve hits from the search response
* Monitor provider query progress


## OpenAPI

````yaml POST /v1/name-screenings/searches
openapi: 3.0.1
info:
  version: 1.5.0
  title: Diligent
  description: >
    Download Postman collection
    [here](https://docs.godiligent.ai/files/postman_collection.json).
servers:
  - url: https://api.godiligent.ai
    description: Production
  - url: https://api.sandbox.godiligent.ai
    description: Sandbox
security:
  - xApiKey: []
tags:
  - name: CDD
    description: Customer Due Diligence
  - name: Company
    description: Company Information
  - name: Blocked Companies
    description: Manage blocked companies
  - name: Monitorings
    description: Website monitoring and alerts for changes and risks
  - name: Webhooks
    description: >

      ## How to Secure Webhook Deliveries

      To ensure that webhook payloads are securely transmitted and verified.
      This guide explains how to configure and validate

      webhook deliveries using a shared secret.


      ### How It Works


      When setting up a webhook, a secret is configured on both the sender (our
      system) and the receiver (your endpoint). Each

      webhook payload is signed using this secret, allowing the receiver to
      verify its authenticity.


      #### Step 1: Configuring Your Webhook Secret


      1. When creating a webhook in our system, specify a unique secret key.
      This secret should be a strong, randomly

      generated string.

      2. Store this secret securely on your server; it should never be exposed
      publicly.


      #### Step 2: Receiving Webhook Payloads


      When your server receives a webhook event, the request will include an
      `X-Signature` header containing a HMAC signature

      of the payload.


      Example header:


      ```

      X-Signature: sha256=abcdef1234567890...

      ```


      #### Step 3: Validating the Webhook Signature


      To verify the webhook payload:


      1. Retrieve the `X-Signature` value from the request headers.

      2. Compute the HMAC SHA-256 signature of the request payload using your
      webhook secret.

      3. Compare the computed signature with the one in the `X-Signature`
      header.

      4. If they match, the webhook is valid.


      #### (Python)


      ```python

      import hashlib

      import hmac

      import json


      def verify_webhook_signature(secret, payload, signature):
        computed_signature = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
        expected_signature = f"sha256={computed_signature}"
        return hmac.compare_digest(expected_signature, signature)

      # Example usage:

      secret = "your_webhook_secret"

      payload = json.dumps({"event": "example"})

      received_signature = "sha256=abcdef1234567890..."


      if verify_webhook_signature(secret, payload, received_signature):
        print("Valid webhook received!")
      else:
        print("Invalid webhook signature!")
      ```


      #### (JavaScript)


      ```javascript

      const crypto = require('crypto');


      function verifyWebhookSignature (secret, payload, signature) {

      const computedSignature = `sha256=${crypto.createHmac('sha256', secret)

      .update(payload)

      .digest('hex')}`;

      return crypto.timingSafeEqual(Buffer.from(computedSignature),
      Buffer.from(signature));

      }


      // Example usage:

      const secret = "your_webhook_secret";

      const payload = JSON.stringify({ event: "example" });

      const receivedSignature = "sha256=abcdef1234567890...";


      if (verifyWebhookSignature(secret, payload, receivedSignature)) {

      console.log("Valid webhook received!");

      } else {

      console.log("Invalid webhook signature!");

      }

      ```


      #### Security Considerations


      - Always use HTTPS to prevent interception of webhook payloads.

      - Reject webhook requests that fail signature validation.

      - Rotate secrets periodically to enhance security.


      By following this guide, you ensure that webhook deliveries are secure and
      trusted.
  - name: Instant Screening (experimental)
    description: Instant Website Screening API
  - name: Name Screening
    description: Name screening search, alert management and remediation
paths:
  /v1/name-screenings/searches:
    post:
      tags:
        - Name Screening
      summary: Create a screening search
      description: >-
        Create a new name screening search request. The search will query the
        provider and create alerts for any matches found.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSearchRequest'
            examples:
              individual_full_name:
                summary: Individual with full name
                description: Search for an individual using full name
                value:
                  reference: CUST-2024-001
                  input:
                    - label: full_name
                      value: John Smith
                    - label: entity_type
                      value: INDIVIDUAL
                    - label: date_of_birth
                      value: '1980-01-15'
                    - label: country_code
                      value: US
              individual_first_last:
                summary: Individual with first and last name
                description: Search for an individual using separate first and last name
                value:
                  reference: CUST-2024-002
                  input:
                    - label: first_name
                      value: John
                    - label: last_name
                      value: Smith
                    - label: entity_type
                      value: INDIVIDUAL
                    - label: place_of_birth
                      value: New York
              entity:
                summary: Business entity
                description: Search for a business entity
                value:
                  reference: CUST-2024-003
                  input:
                    - label: name
                      value: Acme Corporation
                    - label: entity_type
                      value: BUSINESS
                    - label: company_identifier
                      value: '123456789'
                    - label: country_code
                      value: US
      responses:
        '201':
          description: Search created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSearchResponse'
        '400':
          description: Bad Request - Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized - Invalid or missing API key
        '500':
          description: Internal Server Error
      security:
        - xApiKey: []
components:
  schemas:
    CreateSearchRequest:
      type: object
      required:
        - reference
        - input
      properties:
        reference:
          type: string
          description: Unique reference identifier for the search
          maxLength: 200
          example: CUST-2024-001
        input:
          type: array
          description: >-
            Profile fields for the entity being screened. Must include
            entity_type field with value 'INDIVIDUAL' or 'BUSINESS'. Field
            restrictions apply based on entity type. Labels are normalized to
            uppercase internally. For INDIVIDUAL: must include either full_name
            OR both first_name and last_name. For BUSINESS: name field is
            required. date_of_birth must be in YYYY-MM-DD format.
          minItems: 1
          items:
            $ref: '#/components/schemas/LabelField'
    CreateSearchResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Search ID (UUID)
          example: d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4
    ValidationError:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorItem'
      required:
        - errors
    LabelField:
      oneOf:
        - $ref: '#/components/schemas/IndividualLabelField'
        - $ref: '#/components/schemas/BusinessLabelField'
    ValidationErrorItem:
      type: object
      properties:
        path:
          type: array
          items:
            type: string
          description: JSON path to the field with the error
        message:
          type: string
          description: Error message
        code:
          type: string
          description: Error code indicating the type of error
      required:
        - path
        - message
        - code
    IndividualLabelField:
      type: object
      required:
        - label
        - value
      properties:
        label:
          type: string
          enum:
            - first_name
            - last_name
            - full_name
            - entity_type
            - date_of_birth
            - place_of_birth
            - country_code
          description: >-
            Field label for individual entity. Note: Labels are normalized to
            uppercase internally
          example: full_name
        value:
          type: string
          description: Field value. For date_of_birth, format must be YYYY-MM-DD
          example: John Doe
    BusinessLabelField:
      type: object
      required:
        - label
        - value
      properties:
        label:
          type: string
          enum:
            - name
            - entity_type
            - country_code
            - company_identifier
          description: >-
            Field label for business entity. Note: Labels are normalized to
            uppercase internally
          example: name
        value:
          type: string
          description: Field value
          example: Acme Corporation
  securitySchemes:
    xApiKey:
      type: apiKey
      name: X-API-KEY
      in: header

````