Prospect API

Overview

The Prospect API lets you retrieve full conversation history and manage tags for individual prospects. 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 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 calculating the signature, see 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 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}}'