Search item processed

Sent each time a search item is done: a single search, or one row of a bulk search. data contains the same search item as /bulk-single-searchs/read.

• Method: POST to your URL. Answer with HTTP 200.
• Where to set it: on the API page (Notification when a single search or each single row in a bulk search is processed), or per request with custom.webhookUrl / custom.webhookUrlItem. See Set up webhooks.
• Security: verify the signature if you need to.

Example payload

POST https://your-server.com/your-webhook

{
  "signature": "#EXAMPLE-SIGNATURE#",
  "timestamp": "2023-03-01T04:40:20Z",
  "data": {
    "name": "My cool search",
    "user": "#USERID#",
    "file": "#FILEID#",
    "results": {
      "firstname": "Example",
      "lastname": "Email",
      "fullname": "Example Email",
      "gender": "UNKNOWN",
      "emails": [
        {
          "email": "example-email@icypeas.com",
          "certainty": "ultra_sure",
          "mxProvider": "google",
          "mxRecords": [
            "google.com"
          ]
        }
      ],
      "phones": []
    },
    "order": 0,
    "status": "FOUND",
    "system": {
      "createdAt": "2023-01-01T13:49:49.630Z",
      "modifiedAt": "2023-01-01T13:49:49.630Z"
    },
    "userData": {
      "externalId": "my-custom-id",
      "webhookUrl": "https://www.call-me-when-done.com/my-custom-id"
    },
    "_id": "oSmI5YYBMa6Snk9TvjDA"
  }
}

Payload fields

• signaturestring

  The HMAC-SHA1 signature of the request

• timestampstring

  The timestamp used to compute the signature

• dataobject

  The file's information

  Show properties (9)

  • namestring

    Name of the search ('__icypeas__individual' if it is a single search).

  • userstring

    User ID of the user linked to this search.

  • filestring

    File id when it is a bulk search

  • resultsobject

    Object containing the results of your search.

    Show properties (6)

    • firstnamestring

      First name found during the search, if any.

    • lastnamestring

      Last name found during the search, if any.

    • fullnamestring

      Concatenation of the user's first and last names, if any.

    • emailsarray of objects

      Array of the found email addresses.

      Show item properties (4)

      • emailstring

        Email address found during the search.

      • certaintyenum

        How sure Icypeas is that this address exists: ultra_sure, very_sure, probable, undeliverable or not_found. See the Email certainty page.

      • mxProviderenum

        Who hosts the mailbox (google, microsoft, ovh…). See the MX providers page.

      • mxRecordsarray

        Array of MX records. Those are strings

    • phonesarray

      Currently empty.

    • saasServicesarray

      Currently empty.

  • ordernumber

    If in bulk search mode, it is the row of the file it was in.

  • statusstring

    Status of this search.

  • systemobject

    Information concerning the search.

    Show properties (2)

    • createdAtstring

      ISO String Date representing the creation date of the search.

    • modifiedAtstring

      ISO String Date representing the last modification date of the search.

  • userDataobject

    Custom data that were passed when running either the bulk search or the single search

    Show properties (2)

    • webhookUrlstring

      Custom webhook URL that will be called for this search (the field is empty if no URL has been passed when running the single/bulk search)

    • externalIdstring

      Custom id provided by the user (the field is empty if not custom id was passed when running the single/bulk search)

  • _idstring

    ID of the search.