Sync your CRM companies to Hipcall using external_id

Overview

Most businesses already keep their canonical company records in a CRM or ERP. Pushing those records into Hipcall means your agents, dialers, and reports work against the same data your sales and finance teams trust — without anyone copying rows by hand.

This guide shows how to use the Hipcall REST API and the external_id field to keep companies in sync. You stamp each Hipcall company with your primary key on creation, look it up later by that same key, and update it without ever caching the Hipcall numeric ID.

How It Works

external_id is a string field (up to 255 characters) on every company and contact. It belongs to you — Hipcall never generates or interprets it. Three rules to keep in mind:

• It must be unique within your Hipcall account. Two companies in the same account cannot share an external_id.
• It is independent across resources. The same string can identify a company and a contact in the same account.
• It is isolated across accounts. Different Hipcall accounts can each use the value "123" without conflict.

With those properties in place, syncing reduces to one repeating decision per record: does Hipcall already have this external_id? If yes, update. If no, create.

Sync Flow

flowchart TD
    A[Company changed in your CRM] --> B[GET /companies/by-external-id/:crm_id]
    B --> C{Found?}
    C -- 404 No --> D[POST /companies with external_id]
    C -- 200 Yes --> E[PATCH /companies/:hipcall_id]
    D --> F[Synced]
    E --> F

Step 1: Get a Hipcall API Token

Sign in to Hipcall and navigate to Account > Integrations > REST API. Generate a personal access token and copy it — Hipcall shows it only once.

Send the token as a Bearer credential on every request:

Authorization: Bearer YOUR_API_TOKEN

All endpoints below live under /api/v3.

Step 2: Create a Company With external_id

When a new company appears in your CRM, create the matching Hipcall record and stamp it with your CRM’s primary key.

Endpoint:

POST /api/v3/companies
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Request body:

{
  "name": "Acme Corp",
  "external_id": "ERP-9876",
  "website_url": "https://acme.example.com",
  "custom_url": "https://crm.yourcompany.com/companies/9876",
  "emails": [
    { "email": "info@acme.example.com", "order": 0 }
  ],
  "phones": [
    { "country": "GB", "number": "+442045205757", "order": 0 }
  ]
}

Response (201 Created):

{
  "data": {
    "id": 42,
    "name": "Acme Corp",
    "external_id": "ERP-9876",
    "website_url": "https://acme.example.com",
    "custom_url": "https://crm.yourcompany.com/companies/9876",
    "emails": [
      { "email": "info@acme.example.com", "order": 0 }
    ],
    "phones": [
      { "country": "GB", "number": "+442045205757", "order": 0 }
    ]
  }
}

A few notes on how Hipcall normalizes external_id:

• Leading and trailing whitespace are trimmed.
• An empty string is stored as null.
• A JSON integer (e.g. 9876) is coerced to the string "9876". Send whatever shape your CRM emits — Hipcall handles the conversion.

Step 3: Retrieve a Company by external_id

This is the endpoint that makes the whole pattern work. Instead of remembering the Hipcall numeric ID Hipcall returned at creation time, look up the company using your identifier.

Endpoint:

GET /api/v3/companies/by-external-id/ERP-9876
Authorization: Bearer YOUR_API_TOKEN

Response (200 OK):

{
  "data": {
    "id": 42,
    "name": "Acme Corp",
    "external_id": "ERP-9876",
    "website_url": "https://acme.example.com",
    "custom_url": "https://crm.yourcompany.com/companies/9876",
    "emails": [...],
    "phones": [...]
  }
}

Response (404 Not Found) — no company in your account matches that external_id:

{
  "errors": {
    "detail": "Not Found"
  }
}

In a sync workflow that 404 is not an error — it’s the signal to create. See Putting it together below.

Step 4: Update a Company

Once you’ve found the company in Step 3, update it by its Hipcall numeric ID. PATCH only the fields you want to change.

PATCH /api/v3/companies/42
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "website_url": "https://new.acme.example.com"
}

You can also change the external_id itself — for example when the upstream CRM re-keys a record:

{ "external_id": "ERP-9999" }

Or clear it entirely by sending null:

{ "external_id": null }

Putting It Together: An Idempotent Sync Loop

Here is the loop a sync job runs for every changed company in your CRM:

for each company in your_crm:
    response = GET /api/v3/companies/by-external-id/{crm_id}

    if response.status == 404:
        POST /api/v3/companies  { external_id: crm_id, ...fields }

    else if response.status == 200:
        PATCH /api/v3/companies/{response.data.id}  { ...changed_fields }

Race-condition fallback (422 Unprocessable Entity). If two sync jobs run at the same moment, both can see 404 for the same external_id and both can call POST. The second POST returns:

{
  "errors": {
    "external_id": ["has already been taken"]
  }
}

Treat any 422 with an external_id error as a signal to retry the lookup-then-PATCH path. The combined flow — lookup, create-or-update, fall back to update on duplicate — is fully idempotent. You can replay the sync any number of times safely.

A Note About Contacts

The same pattern works for contacts. POST /api/v3/contacts accepts external_id, and GET /api/v3/contacts/by-external-id/:external_id returns the contact. The company and contact external_id namespaces are independent within an account, so the same string can identify both a company and a contact without conflict.

Tools Used

Tool	Purpose
REST API	All requests use the v3 REST API with a Bearer token
external_id field	Carries your CRM’s primary key on the Hipcall company record
Lookup-by-external-id endpoint	GET /api/v3/companies/by-external-id/:external_id removes the need for a side mapping table

Next Steps

• REST API documentation — full schema for companies, contacts, and all available endpoints
• Webhooks — subscribe to company change events for the reverse direction (Hipcall → your CRM)