CRM Integration API

What it does

Four objects go in — Accounts, Contacts, Deals and Activities. They land in the same records Salespuzzle’s own CRM, Sales Pulse, Deal Compass and Account Compass read, so anything you send is immediately part of the analysis.

Your CRM stays the system of record. This API consumes and analyses. It does not write back into Pipedrive, HubSpot or SugarCRM, and it has no delete verb.

An Opportunity and a Deal are one record in Salespuzzle at different stages, not two objects. A task is an Activity whose type is task — there is no separate task object.

Before you start: you need a relay

Make or Zapier? Make’s HTTP Make a request module allows custom headers with no documented plan gate, so it is usually the cheaper choice for a small business. Zapier’s Webhooks by Zapier also allows custom headers but is not available on the Free plan.

Get a key

In Salespuzzle: Company Admin → Integrations → New key. Only the Company Owner and Company Admins can issue one. The key is shown once and is not recoverable. If it is lost, revoke it and issue another.

Keys are scoped per object and action, so each integration can be given the least it needs.

The five rules

1. Every record needs an external_id

Your own system’s id for that record. Sending the same id again updates that record; it never creates a second one. This is the entire basis of the API.

2. Every request needs a source

A short slug naming the system the records came from — pipedrive, hubspot, sugarcrm. It forms part of the upsert key, so two systems can both use the id “42” without colliding. Keep it identical on every sync or you will create duplicates.

3. Link by the other record’s external_id

A contact says "account_external_id": "org-9", never a Salespuzzle id. Send Accounts before Contacts and Deals. A link that cannot be resolved yet is reported back and the record is still stored, so the next sync connects it.

4. There is no delete

Send "archived": true for a record removed in your CRM, and false to restore it. A record removed upstream must not take the Salespuzzle history that referenced it with it.

5. Unrecognised fields are kept, not dropped

They are stored against the record as additional fields and registered on your company’s field list, so the same column arrives in the same place every time. Activities are the exception — they have nowhere to keep extras and will say so in the response.

Authentication

One header on every request. Both Bearer <key> and a bare key are accepted, because integration tools differ.

# Prove the key and see which company it belongs to
curl https://mysalespuzzle.app/api/v1/ping \
  -H "Authorization: Bearer sp_live_..."

The response names the company. Check it is the one you expect before sending 400 records into it.

{
  "ok": true,
  "company": "Apex Retail Group",
  "key": { "name": "Pipedrive sync", "prefix": "K7mPq2Rd" },
  "scopes": ["accounts:write", "contacts:write", "deals:write"],
  "server_time": "2026-09-16T09:14:02.118Z"
}

Endpoints

{object} is accounts, contacts, deals or activities. Create and update are the same call, because an integration cannot know which one it needs and should not have to.

curl -X POST https://mysalespuzzle.app/api/v1/deals/upsert \
  -H "Authorization: Bearer sp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source": "pipedrive",
    "records": [
      {
        "external_id": "1042",
        "name": "Q4 renewal - Apex Retail",
        "account_external_id": "org-9",
        "amount": 24000,
        "currency": "GBP",
        "stage": "negotiation",
        "expected_close_date": "2026-11-30"
      }
    ]
  }'

Every record is reported back by its own id, so you can reconcile without guessing which of a hundred failed.

{
  "ok": true,
  "object": "deals",
  "source": "pipedrive",
  "received": 1,
  "created": 1,
  "updated": 0,
  "failed": 0,
  "results": [
    { "external_id": "1042", "action": "created", "id": "..." }
  ]
}

Paging is by cursor, not offset, so a record cannot be skipped while the list changes underneath you. Archived records are excluded unless you ask for them.

Errors and limits

Every failure returns the same shape, so one error handler covers all of them: { "ok": false, "error": "..." }.

Every request appears in Company Admin → Integrations with what it created, updated or could not store, so you can diagnose an integration without contacting us.

Accounts

The companies you sell to. A Pipedrive Organization, a HubSpot Company or a SugarCRM Account all map here.

Contacts

The people at those companies. A Pipedrive Person, a HubSpot Contact, a SugarCRM Contact.

Deals

Open and closed revenue. A Pipedrive Deal, a HubSpot Deal, a SugarCRM Opportunity.

Mapping your pipeline

Your stage names will not match these. Map them at your end. A stage Salespuzzle does not recognise is rejected with the accepted list, rather than quietly stored as something the pipeline cannot read.

Pipedrive stages are numeric ids per pipeline, and HubSpot custom pipelines work the same way, so fill in the right-hand column for the account you are connecting.

Activities

Calls, meetings, emails, notes and tasks. Activities are the one object with nowhere to keep extra fields — anything unrecognised is reported in the response under warnings rather than stored.

A first sync

Order matters, because links resolve by external_id and a record cannot point at something that is not there yet.

1. Call GET /ping and confirm the key and the company.
2. Call GET /schema and confirm the fields, including your own custom ones.
3. Post Accounts, in batches of 100.
4. Post Contacts, each carrying account_external_id.
5. Post Deals, carrying both account_external_id and contact_external_id.
6. Post Activities last, with whichever links apply.
7. Check Company Admin → Integrations for what landed.

Then run it on a schedule. Because every record carries its own id, a repeat run updates rather than duplicates. There is nothing to reconcile and no import window to manage.

What this API does not do

• It does not write back into your CRM. Your CRM stays the system of record.
• It does not import Leads. Salespuzzle’s Leads have their own lifecycle; send a qualified lead as a Contact.
• It does not import line items. Send the headline product name on the deal.
• It does not delete. See rule 4.

Questions

For anything not covered here, or a CRM not listed, email info@salespuzzle.co.uk.