Statistics at the end of your bulk search

The second notification route available is called each time an entire bulk search is done.

It will provide you with all the useful information about your file, such as the number of found emails.

info

• This is a POST request
• You need to respond with a HTTP status code of 200.
• If you need a custom URL per request, please refer to the single search documentation or the bulk search documentation depending on your needs.
• You can include the results of your bulk search directly in this webhook. Please see the custom object described here

Here is an example of the request body:

Request Body - End Update Bulk

{
    "signature": "#EXAMPLE-SIGNATURE#",
    "timestamp": "2023-03-01T04:40:20Z",
    "data": {
        "file": "#FILEID#",
        "total": 2500,
        "done": 2500,
        "found": 2200,
        "aborted": 0,
        "insufficientCredits": 0,
        "certainties": {
            "verySure": 800,
            "sure": 1000,
            "probable": 400,
            "undeliverable": 0
        }
    }
}

And here is the explanation of each item that you will find in the body:

tip

If you need information about the meaning of the certainties, please see here

signature*string

The HMAC-SHA1 signature of the request

timestamp*string

The timestamp used to compute the signature

data*object

The file's information

file*string

The unique ID of the file that was being processed.

total*number

Total number of valid rows in your file

done*number

Number of rows that were already searched in your file

found*number

Number of found emails in your file

aborted*number

Number of aborted rows in your file

insufficientCredits*number

Number of aborted rows caused by a lack of credits in your file

certainties*object

Certainties' statistics for your bulk search

verySure*number

Count of currently processed rows classified as 'very_sure'

sure*number

Count of currently processed rows classified as 'sure'

probable*number

Count of currently processed rows classified as 'probable'

undeliverable*number

Count of currently processed rows classified as 'undeliverable' (only used for email verification)

resultsarray

Results of the bulk if you have specified the 'includeResultsInWebhook' option in the custom object when launching your bulk

name*string

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

user*string

User ID of the user linked to this search.

filestring

File id when it is a bulk search

results*object

Object containing the results of your search.

firstname*string

First name found during the search, if any.

lastname*string

Last name found during the search, if any.

fullname*string

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

emails*array

Array of the found email addresses.

email*string

Email address found during the search.

certainty*enum

Degree of certainty for the validity of this email address. For a list of certainties, please see Useful information > Certainties

mxProviderenum

MX provider for the email. For a list of providers, please see Useful information > MX providers

mxRecords*array

Array of MX records. Those are strings

phones*array

Currently empty.

saasServices*array

Currently empty.

order*number

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

status*string

Status of this search.

system*object

Information concerning the search.

createdAt*string

ISO String Date representing the creation date of the search.

modifiedAt*string

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

webhookUrl*string

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)

externalId*string

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

_id*string

ID of the search.

Signature verification

You can verify the signature sent in the request, here is simple way to do so. This is useful if you want to validate that Icypeas is indeed calling your route and not anyone else.