Contact Profile Refresh Requests Overview

A Contact Profile Refresh Request looks up and refreshes a small set of contacts on demand. You send the contacts in profiles, and each one comes back as an entry of the request’s contact_profile_refreshes. Unlike Lead Enrichment, which is designed for bulk batches that run in the background, a refresh request is built for per-contact freshness — for example refreshing a CRM record when a sales rep opens it, or periodically re-checking the contacts you track for job changes. There is no saved list to refresh by ID.

One create call does two things:

• Immediately returns every profile with the contact matched so far. contact_data.id is null until a contact is matched. A matched contact that is already fresh 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.
• In the background refreshes the stale contacts and searches for the ones it could not match. You poll for the results; a webhook can optionally tell you when the request completes.

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).

Lifecycle

Quickstart

curl -X POST "https://app.dealsignal.com/api/v1/contact_profile_refresh_requests?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "profiles": [
      { "ds_contact_id": 9207460 },
      { "linkedin_url": "https://www.linkedin.com/in/jane-doe-example",
        "metadata": { "crm_record": "003Dn00000AbCdE" } }
    ]
  }'

The api_key may also go inside the JSON body instead of the query string. contact_refresh_time is omitted here, so the 30-day freshness rule applies and the response echoes it as null.

The response is the request envelope plus every profile with the contact matched so far:

{
  "id": 301,
  "unique_identifier": "d4d8e35d-932e-42e9-a9c2-0dabbef16f46",
  "webhook": null,
  "status": "running",
  "contact_refresh_time": null,
  "user": { "id": 10, "email": "user@example.com", "name": "User Name" },
  "contact_profile_refreshes": [
    {
      "custom_columns": { "ds_contact_id": 9207460 },
      "contact_data": { "id": 9207460, "first_name": "Jane", "search_status": "completed", "match_status": "found_and_verified", "...": "…" }
    },
    {
      "custom_columns": { "linkedin_url": "https://www.linkedin.com/in/jane-doe-example", "metadata": { "crm_record": "003Dn00000AbCdE" } },
      "contact_data": { "id": null, "search_status": "refreshing", "match_status": "not_found", "...": "…" }
    }
  ]
}

Then poll until status is completed. response_format=summary is the lightest check; drop it to fetch the profiles:

curl "https://app.dealsignal.com/api/v1/contact_profile_refresh_requests/request_status\
?api_key=YOUR_API_KEY\
&unique_identifier=d4d8e35d-932e-42e9-a9c2-0dabbef16f46\
&response_format=summary"

To be notified when the request completes, add "webhook": "https://your-server.com/webhooks/dealsignal" to the create call — then still read the results with request_status.

Request fields

Profile object

A profile with no identifier and no complete name + company triple is closed at creation, with contact_data.id null and the remark Invalid input data!. So is a profile that carries only a linkedin_url (plus metadata) that isn’t a linkedin.com URL, such as a shortened link.

Pricing

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

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.

Response shape

Both the create call and request_status return the request envelope:

Each profile is { "custom_columns": {…}, "contact_data": {…} }. contact_data always carries the same 33 keys, whatever you requested:

id, first_name, last_name, logo_url, company_name, title, changed_company, changed_title, linkedin_url, company_website, seniorities, departments, contact_industry, contact_location, contact_country, contact_state, contact_city, skills, profile_completeness, enriched_by, contact_updated_at, primary_position, contact_headline, contact_about_me, contact_education, current_company_and_title, previous_companies_and_titles, search_status, match_status, remark, enrichment_status, current_position_details, old_position_details.

Six are nested:

• primary_position and current_company_and_title: objects of company, title, company_linkedin_url, company_domain.
• previous_companies_and_titles: an array of the same object.
• contact_education: an array of university, major, degree, start_date, end_date, logo_url (keys without a value are omitted).
• current_position_details / old_position_details: arrays of title, company_name, company_linkedin_url, start_date, end_date, country, company_logo_url.

profile_completeness is one of complete, rich, basic, partial, poor. Contact-derived fields are null until a contact is matched, except current_company_and_title ({}) and previous_companies_and_titles ([]).

current_company_and_title and previous_companies_and_titles are snapshots that may predate the refresh. For the refreshed state, read title, company_name, primary_position and the position details.

primary_position is selected independently of ds_primary_company / ds_primary_title in the changes format and can differ from it on some contacts. The change verdict (changed_company, changed_title and the ds_* fields) is always about the ds_primary_* position.

Pagination

page_no and page_size apply only to asynchronous requests. Defaults are 1 and 50; both must be 1 or greater. The wrapper echoes the values you sent — a query-string value comes back as a string ("2"), an omitted one as the integer default. Typed clients should accept both.

Webhook payload

The webhook is optional and is only a completion signal: read the results with request_status, which always returns every profile.

When the request completes, Dealsignal POSTs to your webhook as JSON (Content-Type: application/json, 60-second timeout). The body is a bare JSON array of profile objects in exactly the shape above — no envelope, so neither id nor unique_identifier is included. Correlate through custom_columns.

A create response that reads status: completed is the final result for every profile. POSTs for such a request can still arrive, even before the create response (the request completed during the create call); treat them as duplicates.

Up to two POSTs are sent, one after the other. Profiles that were already completed in a synchronous create response, with or without a matched contact, are normally not sent again: read them from the create response.

1. Refreshed profiles — profiles that completed with a matched contact. Skipped when there is nothing to report.
2. Not-found profiles — profiles that ended not_found without a matched contact (contact_data carries only the status fields). Always sent; with nothing to report the body is empty (not []).

The webhook does not carry every profile of every request; request_status always returns all of them.

[
  {
    "custom_columns": { "email": "ana.ruiz@globex.example", "metadata": { "crm_record": "003Dn00000XyZ99" } },
    "contact_data": { "id": 9207462, "first_name": "Ana", "search_status": "completed", "match_status": "found_and_verified", "...": "…" }
  }
]

Response formats for polling

request_status takes an optional response_format:

• omitted — the full envelope described above.
• summary — { "request_id", "status", "unique_identifier" } only. The smallest response for checking whether the request is done.
• changes — job-change monitoring: the status fields plus a compact profiles collection carrying the ds_* change-detection fields instead of the full contact_data.

response_format=changes and the ds_* fields

{
  "request_id": 304,
  "status": "completed",
  "unique_identifier": "8e4f1a6b-2c7d-4b9e-93f0-5a1d6c8b2e74",
  "profiles": [
    {
      "custom_columns": { "first_name": "Sam", "last_name": "Lee", "company_name": "Acme", "linkedin_url": "https://www.linkedin.com/in/sam-lee-example" },
      "id": 456,
      "first_name": "Sam",
      "last_name": "Lee",
      "linkedin_url": "https://www.linkedin.com/in/sam-lee-example",
      "search_status": "completed",
      "match_status": "found_and_verified",
      "ds_position_state": "single_current",
      "ds_current_position_count": 1,
      "ds_primary_company": "Globex",
      "ds_primary_title": "Senior Engineer",
      "ds_primary_start_date": "2026-09-01",
      "ds_position_primacy_confidence": "high",
      "ds_baseline_primary_company": "Acme",
      "ds_baseline_primary_title": "Engineer",
      "ds_first_seen": false,
      "ds_company_change": true,
      "ds_job_changes": true,
      "ds_title_change": true,
      "ds_company_change_type": "job_change",
      "ds_title_change_type": "title_change_promotion",
      "ds_change_events": [
        { "name": "job_change", "confidence": 100, "previous_company": "Acme", "current_company": "Globex" },
        { "name": "title_change", "confidence": 100, "previous_title": "Engineer", "current_title": "Senior Engineer" }
      ],
      "ds_change_description": "Moved from Engineer of Acme to Senior Engineer of Globex",
      "ds_change_status": { "company": "determined", "title": "determined", "reasons": [] }
    },
    {
      "custom_columns": { "email": "john@globex.example" },
      "id": null,
      "first_name": null,
      "last_name": null,
      "linkedin_url": null,
      "search_status": "not_found",
      "match_status": "not_found"
    }
  ]
}

profiles follows the same synchronous / asynchronous split as the full format (flat array vs. paginated wrapper).

When the ds_* fields are absent. They are omitted (not null) while no verdict is available for the profile: the refresh hasn’t concluded for the profile yet, no contact was matched, or the profile was processed before change detection became available.

undetermined means “no verdict”, not “no change”. When a verdict cannot be reached, ds_change_status.company / .title read undetermined (with reasons) and the booleans read false. Treat the employer as “assessed, nothing changed” only when the ds_* keys are present, ds_change_status.company is determined, ds_company_change is false and ds_baseline_primary_company is not null — likewise ds_change_status.title, ds_title_change and ds_baseline_primary_title for the title. A null baseline means there was no previous primary position to compare against; on a first refresh the verdict only establishes the baseline. Never infer “no change” from absent keys or from an undetermined verdict. The full format’s changed_company / changed_title read false in both cases; use response_format=changes when the difference matters.

What the verdict compares. ds_company_change / ds_title_change — and the full format’s changed_company / changed_title — say whether the contact’s primary position changed relative to your account’s previous refresh of this contact. The verdict has no look-back window: contact_refresh_time doesn’t limit how far back the comparison reaches; it decides which contacts get refreshed. The first refresh of a contact for your account has no baseline and reports false / false with ds_baseline_* null. If the contact already had positions, ds_change_status is undetermined with reason no prior snapshot; if this refresh delivered the contact’s first positions, both change types are newly_added (no_change when those positions have all already ended). Either way it establishes the baseline for the next refresh. Moves inside a corporate family, a renamed employer, or a role that ends and resumes at the same employer never set ds_company_change.

The verdict does not change. It is computed once, when the refresh concludes for that profile — the profile can still be in progress while requested contact details are fetched. Later polls, the full format and the webhook all return the same values.

Errors

Defaults and behaviour notes

• Stop polling once status is completed. Polling has no fee of its own, but if you set a webhook, further request_status calls can trigger additional deliveries to it. Make the receiver idempotent.
• Older requests stay available. A valid unique_identifier keeps working after the request has completed.

Endpoint reference