Prospect API

Overview

The Dux-Soup Prospect API lets you retrieve full conversation history and manage tags for individual prospects from outside Dux-Soup. Use it to pull raw conversation event data for a profile, or to apply and remove tags programmatically - for example, tagging a prospect when a deal stage changes in your CRM.

All Prospect API calls are made against your Remote Control endpoint:

https://app.dux-soup.com/xapi/remote/control/{{USERID}}/...      

Required fields

All Dux-Soup API calls require a signed X-Dux-Signature header; PUT and DELETE requests require a JSON body containing targeturl, timestamp, and userid. For full details on generating the Authentication Key and calculating the signature, see Connecting to, and Authenticating API calls.

You can generate curl  commands or execute calls directly at https://app.dux-soup.com/web/rc/test - the easiest way to try any endpoint on this page.

Get Conversation by Profile ID

Returns the full raw conversation event history for a prospect - every message and LinkedIn event Dux-Soup has recorded for that profile, in its original event format.

URL: https://app.dux-soup.com/xapi/remote/control/{{USERID}}/conversations/{{PROFILEID}}

HTTP method: GET

Example request

curl -v -XGET -H 'X-Dux-Signature: {{SIGNATURE}}' -H 'Content-type: application/json' 'https://app.dux-soup.com/xapi/remote/control/{{USERID}}/conversations/{{PROFILEID}}'

Example response

{   "success": true,   "data": [     {       "data": {         "url": "https://www.linkedin.com/messaging/thread/2-MzQ3OTRlNTEtZmExOC00NzM0LWE4MjE",         "timestamp": "2026-06-19T17:03:50.886Z",         "type": "MEMBER_TO_MEMBER",         "text": "Thanks for the connection",         "from": "https://www.linkedin.com/in/ACoAAAP5RccBk8b0lH6V_bG_OlW59oXfXSXQbCY",         "fromId": "id.66667975",         "fromFirstName": "Cathy",         "fromLastName": "Kitterman",         "tags": []       },       "event": "received",       "type": "message",       "userid": "{{USERID}}"     },     {       "data": {         "timestamp": "2026-06-18T23:00:01.000Z",         "from": "https://www.linkedin.com/in/cathy-kitterman-0073b11a/",         "fromId": "id.66667975",         "fromFirstName": "Cathy",         "fromLastName": "Kitterman",         "type": "INVITATION_ACCEPT",         "text": "",         "tags": []       },       "event": "received",       "type": "message",       "userid": "{{USERID}}"     }   ] }

Each entry is a raw event wrapper (event, type, userid, data ) rather than the flattened {timestamp, direction, type, text, name}  shape returned by Get Recent Messages in the Messaging & Activity API. Use this endpoint when you need the underlying LinkedIn event detail (e.g. the message thread url, or the prospect's profile url at the time of the event); use Get Recent Messages for a simpler, normalized view.

Get Prospect Tags by Profile ID

Retrieves the tags that have been applied to the prospect for this user, including system tags.

URL: https://app.dux-soup.com/xapi/remote/control/{{USERID}}/prospects/{{PROFILEID}}/tags

HTTP method: GET

Example request

curl -v -XGET -H 'X-Dux-Signature: {{SIGNATURE}}' -H 'Content-type: application/json' 'https://app.dux-soup.com/xapi/remote/control/{{USERID}}/prospects/{{PROFILEID}}/tags'

Example response

{   "success": true,   "data": [     "🦆-business-development-business-analyst-b2b-sales-accepted",     "🦆-business-development-business-analyst-b2b-sales-enrolled"   ] }

The 🦆  prefix marks system-generated tags - these are mixed in alongside any manually or API-applied tags in the same flat array.

Add Tags to Prospect (direct)

Applies one or more tags to a prospect.

URL: https://app.dux-soup.com/xapi/remote/control/{{USERID}}/prospects/{{PROFILEID}}/tags

HTTP method: PUT

HTTP body: a JSON object with the following attributes, in addition to the required fields.

Example request

curl -v -XPUT -H 'X-Dux-Signature: {{SIGNATURE}}' -H 'Content-type: application/json' -d '{   "targeturl": "https://app.dux-soup.com/xapi/remote/control/{{USERID}}/prospects/{{PROFILEID}}/tags",   "userid": "{{USERID}}",   "timestamp": 1783506487965,   "tags": ["tag1", "tag2"] }' 'https://app.dux-soup.com/xapi/remote/control/{{USERID}}/prospects/{{PROFILEID}}/tags'

Example response

{ "success": true, "data": ["tag1", "tag2"] }

data in the response reflects the tags submitted in the request, not necessarily the prospect's full current tag set.

Remove Tag from Prospect (direct)

Removes one or more tags from a prospect.

URL: https://app.dux-soup.com/xapi/remote/control/{{USERID}}/prospects/{{PROFILEID}}/tags/{{TAG}}

HTTP method: DELETE

HTTP body: a JSON object with the required fields only.

Example request

curl -v -XDELETE -H 'X-Dux-Signature: {{SIGNATURE}}' -H 'Content-type: application/json' -d '{   "targeturl": "https://app.dux-soup.com/xapi/remote/control/{{USERID}}/prospects/{{PROFILEID}}/tags/{{TAG}}",   "userid": "{{USERID}}",   "timestamp": 1783506521397 }' 'https://app.dux-soup.com/xapi/remote/control/{{USERID}}/prospects/{{PROFILEID}}/tags/{{TAG}}'