Webhooks
Example Person Enrichment Request with Webhook
curl -X POST https://api.fullcontact.com/v3/person.enrich \
-H "Authorization: Bearer {Your API Key}" \
-d '{"email":"bart@fullcontact.com","phone":"+7202227799","webhookUrl":"http://www.fullcontact.com/hook"}'
Webhooks are a mechanism that allow you to supply a URL to the FullContact API that we can send data to once an operation is complete.
For the requests that support them, webhooks are defined in the request body using the webhookUrl
field. For example, the Person Enrichment request allows you to supply a Multi Field Request, with an additional property for a webhookUrl
When a webhook has been provided for a given request, an HTTP POST request will be sent to the URL provided once the process has completed. The payload of the POST request will mirror the responses of most other FullContact API requests, with data sent as JSON within the POST body.
During development and while testing webhooks, we recommend intercepting the webook POST requests locally, or using a web-based webhook testing service. We use ngrok (https://ngrok.com/) and netcat to simulate catching the webhook.
Example of catching a webhook (CTRL+C to kill)
ngrok http 1337
while true ; do echo -e "HTTP/1.1 200 OK\n\n $(date)" | nc -l 1337; test $? -gt 128 && break ; done
Previous Person API Request
curl -H "X-FullContact-APIKey:{Your API Key}" "https://api.fullcontact.com/v2/person.json?email=bart@fullcontact.com"
Enriching the same contact with Enrich API
curl -X POST https://api.fullcontact.com/v3/person.enrich \
-H "Authorization: Bearer {Your API Key}" \
-d '{"email":"bart@fullcontact.com"}'
- Get a New API Key. Authentication in our new API platform has changed to allow for added levels of security. This means you’ll need to create a new key to use the latest APIs. We’ve made these new keys backwards-compatible, so once you generate a new one, you can use it for both our new Enrich API as well as the existing Person, Company and Verify APIs.
To generate a new API key, visit the FullContact Platform. From the main page of the, click the “Generate API Key” button and follow the dialog prompt to create a new key. Once the new key is generated, be sure to copy it into your code immediately - we’ll only show you this key once. - Update Your Requests. Our new API has a different request structure, with a different mechanism for sending your API key as well as a different way for sending matching criteria for person and company profiles.
- Authorization Header In the previous version of the API, API keys could be sent either as a query parameter, or within the X-FullContact-APIKey header. With the new API, keys are now sent across within the Authorization header, with the string “Bearer “ (yes, that’s a space after “Bearer”) added to the beginning of your key. This is the only allowed method for including keys in the new API.
- POST instead of GET One of the more significant changes in our API is the move to an RPC-style interface instead of REST. This means that all requests to our new APIs will be done using the POST method instead of GET. Be sure that you code is updated to now send requests using the POST method.
- Query Changes In our previous API, lookup parameters for both Person and Company were sent as query parameters in the request. In our new APIs, this information is now sent across as keys inside of a post body object, referred to as the Multi Field Request. All of the previous queryable fields (email address, phone, etc.) are still supported in the Enrich API.
- Parse the Response. Our new APIs now return only JSON, so if your code is using something other than JSON today, be sure to update it to accept a JSON response. The structure of the response is also different, so you will need to change how you are accessing the various elements. View our Person Enrichment and Company Enrichment documentation sections for details on what the new response looks like.