Migrate from V1
Map V1 concepts to the V2 HTTP API and move an existing integration.
V2 is the current Signal HTTP API. It replaces the V1 ICPs, sheets, entities and tasks with campaigns, accounts, people, membership, monitors, signals and runs. V2 operations use UUID identifiers and one error envelope. HTTP 429 uses the same envelope and retains its retry headers. The six list operations use cursor pagination.
SDKs
The Python and TypeScript SDKs target V1 and are deprecated. Existing package versions stay installable. New integrations send HTTP requests to V2 directly. Start with the HTTP quickstart.
Credentials
Your existing organization API keys work with V2. Send the key in the x-api-key header. Read Authentication.
Identifiers
V2 identifiers are new UUIDs. Do not send a V1 identifier to a V2 operation. Read V2 identifiers from V2 responses, for example from list_campaigns or search_accounts.
Concept map
| V1 | V2 |
|---|---|
| ICP | Campaign. The ICP description and the target descriptions map to description and criteria. |
| Sheet | No resource. Campaign membership holds accounts and people. Read Sheets. |
| Custom fields (8 types) | Campaign.fields with 5 types: string, number, integer, boolean, enum |
| Entity | Account and Person |
Entity status (new, reviewed, passed, contacted) | membership.review_state (new, reviewed, passed). A V1 contacted status reads reviewed. Set the contacted state with update_person and contacted. |
| File upload | upload_import (multipart request to POST /runs/import/upload) |
| Task and task execution | Monitor for recurring work. start_discovery, start_import and start_export for single runs. |
| Schedule | Campaign.discovery.frequency and Monitor.frequency |
| Run status (8 uppercase values) | 6 lowercase values: queued, running, succeeded, failed, canceled, skipped |
| Run queue endpoint | No V2 operation |
Signal icp_id and entity_ids | campaign_id and account_ids. The other signal fields keep their V1 names. |
| Webhooks | webhook_url on the monitor config only. Read Webhook URL. |
| Sheet CSV export | start_export. Read Exports. |
| Python and TypeScript SDKs | Deprecated. Use HTTP V2. |
Move one read request to V2 first. Then move the requests that change data or start runs.
Run status map
| V1 stored status | V2 status |
|---|---|
SCHEDULED, PENDING | queued |
RUNNING, PAUSED | running |
COMPLETED | succeeded |
FAILED, CRASHED | failed |
CANCELED | skipped when the run has a skipped reason; otherwise canceled |
Read Run statuses for cancellation, partial output and stuck-run rules.
Sheets
V2 has no sheet resource. In V1, a sheet held the entities of an ICP. In V2, campaign membership holds the accounts and people of a campaign. Each account or person in a campaign has its own review state, fit values and custom field values in that campaign.
- To read the records of a campaign, send
search_accountsorsearch_peoplewithcampaign_id. - To add records, send
add_accounts_to_campaignoradd_people_to_campaign. - To remove records, send
remove_account_from_campaignorremove_person_from_campaign.
Read Membership and Review accounts and people.
Exports
The V1 sheet CSV export maps to start_export. start_export starts an export run for the accounts or the people of a campaign. When the run succeeds, result.download_url holds the URL of the CSV file for 1 hour. Read Export data.
V1 reference
The V1 references document the deprecated V1 interface. V1 stays available for existing integrations.
APP-483 coordinated release
The candidate adds organization-owned monitors and observations. Existing campaign-nested monitor routes remain available. POST /v2/monitors adds independent creation. Signal responses add subjects, person_ids, and nullable event_date; campaign_id is nullable provenance. person_id is an additional signal filter.
Existing signal IDs, evidence, and known prospect references remain stable. Source deletion retains history and pauses dependent monitors. Monitor production no longer creates prospects or memberships. Use explicit import and membership operations.
These changes require the compatible readers and ownership backfill in the coordinated APP-483 release. Candidate documentation is not confirmation of production activation. The legacy V1 reference remains an immutable archive of its recorded source.
Next steps
HTTP quickstart verifies your key before you start.