Notification when a search item is processed

The first notification route available is called each time a search item in processed, being a single search or a row in your bulk search.

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.

Here is an example of the request body:

Request Body - Each search item

{
    "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"
    }
}

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

signature*string

The HMAC-SHA1 signature of the request

timestamp*string

The timestamp used to compute the signature

data*object

The file's information

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.