Create a Contact Profile Refresh Request | Dealsignal

Creates a Contact Profile Refresh Request for the supplied profiles. Every profile is returned right away with the contact matched so far. contact_data.id is null until a contact is matched. A fresh matched contact is usually completed right away; when requested_attributes includes contact details such as email, it can stay in progress until they are fetched. A stale one reads refreshing. Stale and unmatched contacts are refreshed in the background; poll request_status until the request’s status is completed to get them. A webhook can optionally notify you when that happens.

A contact is stale when its LinkedIn profile was last verified more than contact_refresh_time days before the request was created (30 days when the parameter is omitted).

Authentication

api_key may be supplied either as a query-string parameter or inside the JSON body. The account must be active with a subscription that has not expired, and must hold enough credits for the request.

What the response contains

By default (synchronous: true) the response carries the request envelope plus contact_profile_refreshes — every profile, each as { custom_columns, contact_data } with the contact matched so far. status is running while background refresh continues, or completed straight away when every profile was resolved during the call. A completed create response is the final result for every profile; any webhook POSTs for such a request are duplicates. With synchronous: false only the envelope is returned.

The call never blocks on the background refresh in either mode.

Pricing (credits per profile)

Each completed profile with a matched contact is charged in credits. requested_attributes sets the most a profile can cost:

`requested_attributes` (all names within)	Tier	Maximum credits per profile
`contact_profile` only, or omitted	Contact Profile	0.25
… plus `email`	Lead Profile	1.00
… plus `corporate_phone`	Full Prospect Profile	1.25
… plus any of `direct_phone`, `mobile_number`, `cma`, `personal_email`	Full Prospect Profile with Direct Dial	1.50

A profile is charged at the highest tier its data actually supports, up to that maximum. For example, if you request email but no verified work email is available, the profile is charged as a Contact Profile.

Balance check. The call is rejected with 422 when your balance is too low for the submitted profiles. Keep a margin: a profile can cost up to the maximum for the attributes you request.
Every refresh is charged. A contact you have refreshed before is charged again when you refresh it through this endpoint.
Not charged: profiles that end without a matched contact (contact_data.id null) or not_found, profiles whose contact has no current position, and every profile of a test request.

Query parameters

api_keystringOptional

Your Dealsignal API key. On this endpoint it may be supplied here or as the api_key property of the JSON body — one of the two is required.

Request

This endpoint expects an object.

profileslist of objectsRequired

One or more contact profiles to look up and refresh.

api_keystringOptional

Account API key. Alternative to the api_key query-string parameter — supply it in one of the two places.

contact_refresh_timeinteger or nullOptional>=0

Freshness threshold in days. A matched contact whose LinkedIn profile was last verified more than this many days before the request was created is treated as stale and refreshed in the background.

Omit it for the 30-day default — the request then stores and echoes null. 0 compares against the day the request was created: a contact verified on an earlier day is refreshed, one verified the same day is returned as fresh.

webhookstring or nullOptionalformat: "uri"

Optional. URL to notify when the request completes — see the Contact Profile Refresh Request completed webhook. The POSTs can repeat and don’t carry every profile, so treat them as a signal and read the results with request_status. Omit it (the default) or send "" to rely on polling alone.

synchronousbooleanOptionalDefaults to true

true (default): the response includes every profile inline in contact_profile_refreshes, with the contact matched so far. A fresh matched contact is usually completed right away — when requested_attributes includes contact details such as email, it can stay in progress until they are fetched; a stale one reads refreshing; an unmatched profile has contact_data.id null and is either still in progress or already closed.

false: the response carries only the request envelope; poll request_status for the profiles.

Background refresh of stale and unmatched contacts runs either way — the call never blocks on it.

find_match_and_refreshbooleanOptionalDefaults to true

When false, profiles that do not match a Dealsignal contact with a valid LinkedIn profile are closed at creation instead of being searched for in the background: with contact_data.id null when no contact matched, as completed when the matched contact has no valid LinkedIn profile. Matched contacts are refreshed as usual.

requested_attributeslist of objectsOptionalDefaults to [{"name":"contact_profile","priority_order":0}]

Data to request for each profile. Sets the maximum credits a profile can cost — see Pricing in the operation description. Defaults to contact_profile only.

contact_data in responses always carries the same fixed set of keys regardless of what you request here; contact details (email, phones) are not part of it.

testbooleanOptionalDefaults to false

true forces synchronous: true and flags the request as test data: profiles are matched against test contacts only and closed completed immediately, no refresh runs, no credits are consumed, and the request is excluded from credit metrics. Your balance must still cover the request. A profile with no matching test contact is also closed completed, with contact_data.id null. In test mode, read the results from the create response.

Response

Request created. contact_profile_refreshes is present only for synchronous: true (the default).

idintegerOptional

Request ID.

unique_identifierstringOptionalformat: "uuid"

Use this to poll request_status.

webhookstring or nullOptional

The webhook URL you sent, if any; null when omitted ("" when sent empty).

statusenumOptional

running while background processing continues; completed once every profile is resolved (possibly already in the create response).

Allowed values:

contact_refresh_timeinteger or nullOptional

The freshness threshold (days) sent at creation, echoed back; null when it was omitted (the 30-day default then applies).

userobjectOptional

The authenticated account.

contact_profile_refresheslist of objectsOptional

Present only when synchronous is true (the default): the profiles created inside the call, each with the contact matched so far. Contacts that still have to be refreshed arrive later via the webhook or request_status.

Errors

401

Unauthorized Error

422

Unprocessable Entity Error