Subscriptions

Subscriptions

Subscriptions, when enabled on your account, allow you to receive updates about your contacts of interest as soon as we have new data to
deliver through the use of webhooks. When updates for a subscribed contact are available, the FullContact API will
send the data to the supplied webhook URL provided when the subscription was created.

A subscription will exist and be active until you have explicitly un-subscribed from the contact.

To learn more about subscriptions, please contact our Sales team.

Subscribe to a Person

curl -X POST https://api.fullcontact.com/v3/person.subscribe \
-H "Authorization: Bearer {Your API Key}" \
-d '{"email":"[email protected]","webhookUrl":"http://www.fullcontact.com/hookUrl"}'
{
  "subscriptionId": "189967a9b4f4f8e3d8c0db178801be5c",
  "message": "Subscription created"
}

Much like the Person Enrichment requests, subscribing to a person is done by
passing a Person Summary object to the subscribe endpoint.

This endpoint requires that the Person Summary object be extended with a webhookUrl so that the FullContact API knows where to send updates. An optional subscriptionId property can be supplied to
reference the subscription for later operations, such as un-subscribing. If subscriptionId is omitted, one will be
generated and returned as part of the response.

Extension Properties
webhookUrl Webhook URLRequiredSome description about webhook URL
subscriptionId stringOptionalAn optional subscriptionId. If supplied, ensure this value is unique for each of your contacts.

Response

An object with a subscriptionId property representing the ID associated with this subscription,
as well as a message string.

Subscription Payload

Data delivered for subscriptions is in the same format as responses from the person.enrich endpoint, except that it also includes a subscriptionId field to identify which subscription triggered the delivery.

{
  "fullName": "Bart Lorang",
  "ageRange": "30-39",
  "gender": "Male",
  "location": "Denver, CO, United States",
  "title": "Co-Founder & Managing Director",
  "organization": "V1.vc",
  "twitter": "https://twitter.com/bartlorang",
  "linkedin": "https://www.linkedin.com/in/bartlorang",
  "bio": "CEO & Co-Founder of @FullContact, Managing Director @v1vc_. Tech Entrepreneur, Investor. Husband to @parkerbenson and Father to Greyson Lorang",
  "avatar": "https://d2ojpxxtu63wzl.cloudfront.net/static/a7e6a5aba590d4933e35eaadabd97fd2_44e00e968ac57725a15b32f9ca714827aff8e4818d290cb0c611f2e2585253b3",
  "website": "https://fullcontact.com/bart",
  "details": { },
  "subscriptionId": "1668e03b191948169634d1da140d1bcc"
}
{
  "status": 404,
  "message": "Profile not found",
  "subscriptionId": "1668e03b191948169634d1da140d1bcc"
}

Testing a subscription

In order to test that your application is able to correctly handle the webhooks
produced by a subscription, you can use the testSubscription method. Invoking
this method on an existing subscription will cause that subscription to fire
immediately, as if new updates were made available for the contact.

curl -X POST https://api.fullcontact.com/v3/person.testSubscription \
-H "Authorization: Bearer {Your API Key}" \
-d '{"subscriptionId":"bd468cad24cb216ab3960bd"}'
{
  "status": 202,
  "message": "Queued for search. Your response will be sent to your webhook shortly at http://www.fullcontact.com/hookUrl."
}
Properties
subscriptionId stringThe ID of the subscription to delete.

Unsubscribe from a Person

At some point in the lifecycle of a subscription, you may find that you no longer need to receive updates for a
particular contact, for example, they may no longer be a customer of interest. For these cases,
the FullContact API provides an endpoint for you to un-subscribe to previously subscribed contacts.

Once the endpoint has been called you will no longer receive any updates for the particular contact. If you need to resubscribe, subscriptions can be recreated at any time.

curl -X POST https://api.fullcontact.com/v3/person.unsubscribe \
-H "Authorization: Bearer {Your API Key}" \
-d '{"subscriptionId":"bd468cad24cb216ab3960bd"}'
{
    "subscriptionId": [
        "aa1bd9b7bb8a606dcb6dcad23967c3ed"
    ],
    "message": "Subscription successfully removed"
}
Properties
subscriptionId stringThe ID of the subscription to delete.

Did this page help you?