Version: v1 · Base URL: https://app.imonsocial.com/api/v1 · Auth: X-API-Key header · Format: JSON

This is the complete reference for connecting a CRM, DMS, marketing platform or automation tool to I'm On Social. Everything on this page is live and testable today. If you are a CRM vendor's engineer, start with the Quick start, then read Webhooks and Sync patterns.

Try it in the browser: an interactive console with every endpoint is at https://app.imonsocial.com/api/public/reference. Paste your key under Authorize and run real calls. The machine-readable schema is at /api/public/openapi-v1.json (import it into Postman or Insomnia, or generate a client).

---

What you can do

Direction	Capability	How
Pull	Contacts with tags, vehicle, notes, sold records, owner rep, your own CRM ids	GET /api/v1/contacts, GET /api/v1/export/contacts
Pull	Full text/email thread per customer, call logs with transcripts and AI summaries	GET /api/v1/contacts/{id}/messages, /calls
Pull	Activity timeline (cards, review requests, notes, sales, tasks)	GET /api/v1/contacts/{id}/events
Push	Create or update customers without creating duplicates	POST /api/v1/contacts (upsert)
Push	Notes, tags, timeline events, sold records, follow-up tasks	POST .../notes, /tags, /events, /purchases, POST /api/v1/tasks
Push	Send a real text from the rep's number	POST /api/v1/contacts/{id}/messages
Real time	Be told within a minute when anything changes (new contact, text in/out, call, sale, note, task)	Webhooks
Leads	Deliver internet leads into a rep's inbox (ADF/XML, JSON, email)	Lead intake

---

Quick start

1. Get a key. A dealership admin creates it in the app: Tools → Integrations → API Keys → New key. Pick a name (e.g. "HubSpot sync"), scopes (read, write), and an expiry. The key is shown once and stored hashed on our side. One key = one store. Ask for an organization key if you need every store in a dealer group.

2. Confirm it works.

curl https://app.imonsocial.com/api/v1/me \
  -H "X-API-Key: imos_live_xxxxxxxxxxxxxxxxxxxx"

{
  "key_name": "HubSpot sync",
  "scopes": ["read", "write"],
  "store": {"id": "69a0b7095fddcede09591668", "name": "Riverton Chevrolet"},
  "organization": {"id": "org_001", "name": "Riverton Auto Group"},
  "stores_visible": 1,
  "users_visible": 14,
  "rate_limit_per_minute": 120,
  "docs": "https://www.imonsocial.com/developers"
}

3. Pull contacts changed in the last day.

curl "https://app.imonsocial.com/api/v1/contacts?updated_since=2026-09-17T00:00:00Z&limit=100" \
  -H "X-API-Key: $KEY"

4. Push a customer from your CRM (idempotent).

curl -X POST https://app.imonsocial.com/api/v1/contacts \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jordan", "last_name": "Lee",
    "phone": "(801) 555-0142", "email": "jordan@example.com",
    "source": "hubspot", "external_ids": {"hubspot": "1234567"},
    "tags": ["internet lead"], "vehicle_interest": "2024 Silverado LT"
  }'

{"id": "6aad4836de3a277d2522915c", "created": true, "message": "Contact created"}

Send the same body again and you get "created": false with the same id: we matched it by external_ids.hubspot, then phone, then email. You can never create a duplicate through the API.

5. Subscribe to changes.

curl -X POST https://app.imonsocial.com/api/v1/webhooks \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://crm.example.com/imos-webhook", "events": ["*"], "secret": "choose-a-long-random-string", "description": "CRM sync"}'

Then POST /api/v1/webhooks/{id}/test sends a signed ping immediately so you can verify your endpoint end to end.

---

Authentication

Every request carries the key in a header:

X-API-Key: imos_live_xxxxxxxxxxxxxxxxxxxx

Where keys come from	Created by a dealership admin in the app (Tools → Integrations → API Keys). We never email keys.
Scope of data	A key sees exactly one store's data (contacts owned by that store's reps, their conversations, calls, tasks). An organization key sees every store in the group. Nothing else is reachable, not even by id.
Permissions	read (all GETs) and write (all POST/PUT/DELETE). A read-only key gets 403 on writes.
Expiry	Optional, set at creation (default 365 days). Expired → 401 API key expired.
Revocation	Instant, from the same screen. Revoked → 401 API key revoked.
Storage	Only a SHA-256 hash is stored. If a key is lost, revoke it and create a new one.
Transport	HTTPS only. Keys sent over plain HTTP are rejected by the edge.

Rate limits, errors, conventions

• Rate limit: 120 requests per minute per key. Over the limit you get 429 with a Retry-After: 60 header. Bulk pulls should use limit=200 and offset, or GET /export/contacts.
• Errors are JSON: {"detail": "human readable reason"} with the standard status: 400 bad input, 401 bad/missing key, 403 read-only key, 404 not found or not in your store (we do not reveal that a record exists elsewhere), 429 rate limited, 500 our fault (logged, contact support with the timestamp).
• Pagination: limit (max 200; 500 on some sub-resources) and offset. Responses include total.
• Timestamps: ISO-8601 in UTC, e.g. 2026-09-18T14:03:22.104000+00:00. Send filters like updated_since in the same format (Z suffix accepted).
• IDs: 24-character hex strings. Store them; they never change.
• Phone numbers: accepted in any format, stored as E.164 (+18015550142). Matching ignores formatting.
• Soft deletes: DELETE hides a contact from the rep and from lists; history is kept and the record can be restored by an admin.

---

Data model

Contact

Field	Type	Notes
id	string	I'm On Social id
first_name, last_name	string
phone	string	E.164. Primary mobile.
phones	array	Extra numbers [{"label": "work", "number": "+1..."}]
email, email_work	string
emails	array	Extra addresses
tags	array of strings	Free-form. sold is special: it marks a customer as purchased and starts the sold follow-up cadence.
source	string	Where the record came from: manual, csv, phone_contacts, lead_form, referral, api, or the name you send (e.g. hubspot).
external_id	string	A single foreign id (legacy). Prefer external_ids.
external_ids	object	Your ids keyed by system: {"hubspot": "1234567", "vinsolutions": "88-1002"}. Used for matching on upsert and returned on every read.
vehicle	string	What they own / bought (derived from the newest purchase record)
vehicle_interest	string	What they said they want
notes	string	The rep's running notes. API notes are appended with a date and source prefix, never overwritten.
purchase_history	array	Sold records [{"id", "title", "category", "date": "YYYY-MM-DD", "notes"}]
date_sold	date	Most recent sale
sold_count	number
user_id	string	Owning rep (see Users)
store_id	string
status	string	active, hidden
birthday, anniversary, custom_dates		Drive automated cards
occupation, employer, organization_name, personal_details		Personal intelligence captured by the rep or Jessi
address_street, address_city, address_state, address_zip	string
photo_url	string
created_at, updated_at	datetime	updated_at changes on any edit, tag, note or sale, so it is the field to poll

Writable through the API: first_name, last_name, phone, phones, email, email_work, emails, organization_name, occupation, employer, vehicle, vehicle_interest, notes, tags, source, external_id, external_ids, birthday, anniversary, address_*, personal_details, photo_url, customer_number, plus owner_user_id / owner_email to assign the rep.

Message

id, conversation_id, user_id (rep), direction (inbound | outbound), sender (user | contact | ai), channel (sms | email), content, media_url, ai_generated, status, timestamp.

Conversation

id, user_id, contact_id, contact_phone, contact_name, status, ai_enabled, last_message_at. One conversation per rep-customer pair.

Call

id, contact_id, user_id, direction, duration_s, outcome, connected, recording_url, transcript, ai_summary, created_at.

Timeline event

id, contact_id, user_id, event_type (e.g. personal_sms, email_sent, call_made, digital_card_sent, review_request_sent, note_added, purchase_added, task_completed, or your own via the API), title, description, metadata, source, timestamp.

Task

id, user_id, contact_id, type (follow_up, callback, appointment, manual...), title, description, due_date, priority, status (pending, completed), source, idempotency_key, created_at, completed_at.

User (rep)

id, first_name, last_name, name, email, phone, role (user, store_manager, org_admin), title, status, store_id, organization_id, twilio_number (the texting number customers see). Passwords and tokens are never returned.

---

Endpoints

All paths below are relative to https://app.imonsocial.com.

Identity

Method	Path	What it does
GET	/api/v1/me	Key name, scopes, the store/organization it can see, rate limit

Contacts

Method	Path	What it does
GET	/api/v1/contacts	List / search. Query: search, phone, email, external_id, tag, source, owner_user_id, updated_since, limit, offset
GET	/api/v1/contacts/{contact_id}	One contact with every field
POST	/api/v1/contacts	Upsert. Body: any writable field. Requires phone, email or external_id. Returns {id, created}
PUT	/api/v1/contacts/{contact_id}	Update fields. external_ids are merged, not replaced
DELETE	/api/v1/contacts/{contact_id}	Hide (soft delete)
POST	/api/v1/contacts/{contact_id}/tags	Body {"tag": "VIP"} → returns the tag list
DELETE	/api/v1/contacts/{contact_id}/tags/{tag}	Remove a tag
GET	/api/v1/contacts/{contact_id}/notes	The notes text
POST	/api/v1/contacts/{contact_id}/notes	Body {"note": "...", "source": "HubSpot"} → appends [Sep 18, 2026 via HubSpot] ... and logs a note_added event
GET	/api/v1/contacts/{contact_id}/events	Timeline, newest first
POST	/api/v1/contacts/{contact_id}/events	Body {"event_type": "appraisal_completed", "title": "...", "description": "...", "metadata": {}}
GET	/api/v1/contacts/{contact_id}/messages	Every text/email with this customer across the rep's conversations
POST	/api/v1/contacts/{contact_id}/messages	Body {"content": "...", "user_id": "<rep, optional>", "channel": "sms"} → sends for real from the rep's number
GET	/api/v1/contacts/{contact_id}/calls	Call logs with transcript + AI summary
GET	/api/v1/contacts/{contact_id}/purchases	Sold records
POST	/api/v1/contacts/{contact_id}/purchases	Body {"title": "2024 Chevy Tahoe", "category": "vehicle", "date": "2026-09-01", "notes": "Traded a 2018 Silverado"} → merges with a same-day record, tags sold

Upsert matching order (POST /api/v1/contacts): external_id / crm_id → any value in external_ids → phone (last 10 digits) → email → exact first+last name with no conflicting phone. On a match we $set the fields you sent, add (never remove) tags, merge external_ids, append notes, and return created: false.

Owner assignment: send owner_user_id (from GET /api/v1/users) or owner_email. If omitted, new contacts go to the key creator, else the store manager.

Tasks

Method	Path	What it does
GET	/api/v1/tasks	Query: status, user_id, contact_id, due_after, due_before, limit, offset
POST	/api/v1/tasks	Body {"contact_id", "title", "due_date", "type": "follow_up", "priority": "medium", "user_id": "<rep, optional>", "idempotency_key": "<your id>"}

Tasks show on the rep's Today list in the app. Send idempotency_key (your task id) so retries never double up.

People and places

Method	Path	What it does
GET	/api/v1/users	Reps and managers in scope. Query: role, status, limit, offset
GET	/api/v1/users/{user_id}	One user
GET	/api/v1/stores	Stores in scope
GET	/api/v1/organizations	The dealer group

Conversations

Method	Path	What it does
GET	/api/v1/conversations	Query: user_id, contact_id, updated_since, limit, offset
GET	/api/v1/conversations/{conversation_id}/messages	Messages oldest → newest

Export

Method	Path	What it does
GET	/api/v1/export/contacts	Initial load. format=json (default) or format=csv, limit up to 20,000

Webhooks

Method	Path	What it does
GET	/api/v1/webhooks/events	Event catalog with descriptions (no key needed)
GET	/api/v1/webhooks	Your subscriptions
POST	/api/v1/webhooks	Body {"url": "https://...", "events": ["contact.created", "message.received"] or ["*"], "secret": "...", "description": "..."}
DELETE	/api/v1/webhooks/{webhook_id}	Remove
GET	/api/v1/webhooks/{webhook_id}/deliveries	Last 200 delivery attempts with status codes and errors
POST	/api/v1/webhooks/{webhook_id}/test	Sends a signed ping now and returns your server's response

---

Webhooks (push from I'm On Social to you)

Register an HTTPS URL and we POST events to it. Events are produced by a change feed that runs every 60 seconds over everything that happened in the store, regardless of how it happened (rep typed it, CSV import, lead source, Twilio, Jessi, or your own API call). Expect delivery within about a minute of the change.

Event catalog

Event	Fires when	data
contact.created	A contact was added by any path	Contact (see below)
contact.updated	Fields, tags, vehicle, notes, owner or sold data changed	Contact
contact.deleted	Contact hidden/removed	Contact
message.sent	A rep, campaign or Jessi sent a text/email	Message + contact_id
message.received	Customer replied	Message + contact_id
call.logged	A call ended (transcript/summary included when available)	Call
note.added	A note was added	Timeline event
deal.closed	A sale was recorded	Timeline event (event_type: purchase_added)
task.created / task.completed	Follow-up created / done	Task
activity.logged	Any other touchpoint: card sent, review request, congrats card, link click	Timeline event
appointment.created, review.submitted, campaign.enrolled, campaign.completed, user.created, user.deactivated	As named	Object
ping	You called /test	{"message": "Hello from I'm On Social"}

Subscribe to ["*"] for everything.

Envelope

{
  "id": "evt_3f9c1a7e2b8d4c5e6f70",
  "event": "message.received",
  "timestamp": "2026-09-18T14:03:22.104000+00:00",
  "store_id": "69a0b7095fddcede09591668",
  "organization_id": "org_001",
  "data": {
    "id": "6aad4836de3a277d2522915c",
    "contact_id": "69a496841603573df5a41723",
    "conversation_id": "69a4a1c0e2f3...",
    "user_id": "69a5303dbd4ef63b7ef776d4",
    "direction": "inbound",
    "sender": "contact",
    "channel": "sms",
    "content": "Yes, Saturday at 10 works",
    "media_url": null,
    "timestamp": "2026-09-18T14:02:58+00:00"
  }
}

Contact payloads carry: id, first_name, last_name, phone, email, tags, source, external_id, external_ids, vehicle, vehicle_interest, notes, owner_user_id, store_id, status, date_sold, purchase_history, photo_url, created_at, updated_at.

Headers and signature

Content-Type: application/json
User-Agent: ImOnSocial-Webhooks/1.0
X-IMOS-Event: message.received
X-IMOS-Delivery: evt_3f9c1a7e2b8d4c5e6f70
X-IMOS-Signature: sha256=<hex HMAC-SHA256 of the raw request body using your secret>

Verify before trusting the payload:

import hmac, hashlib
def verify(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

const crypto = require("crypto");
function verify(secret, rawBody, header) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header || ""));
}

Compute the HMAC over the raw bytes you received (do not re-serialize the JSON).

Delivery rules

• Respond with any 2xx within 10 seconds. Do your processing after you respond.
• Each event is delivered once per subscription. A non-2xx or timeout is logged with the response (GET /api/v1/webhooks/{id}/deliveries) and increments failure_count; there is no automatic retry. Reconcile gaps with GET /api/v1/contacts?updated_since=....
• Order is by change time within a batch but not guaranteed across batches. Use data.updated_at / data.timestamp.
• X-IMOS-Delivery (= id) is unique per event: use it as an idempotency key.
• Avoid loops: when you push a record through the API, the resulting contact.created/contact.updated event will come back to you a minute later. Ignore events whose data.source is your system name, or whose data.external_ids already contains your id with a matching updated_at.

---

Lead intake (ADF/XML, JSON, email)

Internet leads enter through Lead Sources. A dealership admin creates one in Tools → Leads → Lead Source Config (or Connect Zapier / Make) and gets a source_id plus an optional per-source API key. Each source routes to the right store and rep, deduplicates against existing customers, and kicks off speed-to-lead.

Format	Endpoint	Auth
ADF/XML (Cars.com, AutoTrader, OEM portals, most automotive providers)	POST /api/leads/adf?source_id=<source_id> — raw XML body or form field XML=	Optional X-API-Key header (the lead source's key)
JSON / form webhook (your CRM, website forms, Zapier, Make, n8n)	POST /api/leads/webhook/<source_id>	X-API-Key: <source key> header or ?api_key=
Email (ADF delivered by email, the industry default)	POST /api/leads/email-inbound?source_id=<source_id> from any inbound-mail service (SendGrid Inbound Parse, Mailgun Routes, CloudMailin, Zapier Email Parser). Every text field and attachment is scanned for ADF	Per source

The JSON webhook accepts any field names; these aliases are mapped automatically:

Standard field	Accepted aliases
phone (required)	phone, phone_number, mobile, cell
first_name / last_name	firstname, fname / lastname, lname
full_name	name, full_name, customer_name (split for you)
email	email, email_address
vehicle_year, vehicle_make, vehicle_model	year, make, model
vehicle_stock, vehicle_vin	stock, stock_number, vin
comments	comments, message, notes, inquiry
source_name	source, lead_source, provider
is_test	is_test, test (true keeps the lead out of reporting)

Sample:

curl -X POST "https://app.imonsocial.com/api/leads/webhook/<source_id>" \
  -H "X-API-Key: <source key>" -H "Content-Type: application/json" \
  -d '{"first_name":"Jordan","last_name":"Lee","phone":"5551234567","email":"jordan@example.com","year":"2024","make":"Ford","model":"F-150","stock_number":"F24-118","comments":"Is this truck still available?","is_test":true}'

ADF returns a plain-text acknowledgement (per the ADF spec); JSON returns {"lead_id", "contact_id", "status"}.

---

Zapier, Make, n8n

• Into I'm On Social: use the JSON webhook above as the action ("Webhooks by Zapier → POST"). The Connect Zapier / Make screen in the app shows the exact URL, key and a sample payload for each source, and has a "Send test lead" button.
• Out of I'm On Social: create a "Catch Hook" trigger in Zapier (or a Webhook module in Make), then register that URL with POST /api/v1/webhooks, or from the app's Tools → Integrations → Webhooks tab. Use /test to fire a ping so the tool can learn the payload shape.

---

Sync patterns

Initial load (CRM ← I'm On Social): GET /api/v1/export/contacts?format=json (or CSV) once, then store our id on your record. For threads and calls, iterate GET /api/v1/contacts/{id}/messages and /calls for the customers you care about.

Incremental pull: every N minutes call GET /api/v1/contacts?updated_since=<last run>&limit=200 and page with offset. updated_at moves on any edit, tag, note or sale.

Real-time (recommended): subscribe to webhooks for ["*"] and treat the payload as the new truth for that record; fall back to the incremental pull nightly to reconcile.

Push (I'm On Social ← CRM): upsert with external_ids = your id and source = your system name. Send only the fields you own. Tags are additive; to remove one use DELETE .../tags/{tag}. For notes use POST .../notes (append) rather than writing the notes field.

Field ownership / conflicts: last write wins per field. Keep the CRM authoritative for identity and deal data, and I'm On Social authoritative for tags, notes, vehicle_interest, personal_details and the timeline (the rep is typing these on the lot).

Photos and files: photo_url is a public URL you can store or mirror. Message media_url values are public for the life of the message.

---

Testing checklist

1. GET /api/v1/me returns your store. If users_visible is 0, the store has no reps yet: add one in the app.
2. Create a contact with phone +1 500 555 01xx (Twilio test range, never a real person) and "tags": ["api-test"], then delete it. Filter test data with ?tag=api-test.
3. Register a webhook to a request bin, call /test, confirm the signature verifies.
4. Edit that contact in the app, wait a minute, confirm contact.updated arrives.
5. Send a lead with "is_test": true to your source URL and watch it appear in the rep's inbox.
6. Revoke the test key and confirm 401.

Need a sandbox store or an organization-level key? Email support@imonsocial.com with your company, use case and the dealership you are integrating for.

---

Changelog

• 2026-09 (v1): Tenant-scoped keys (store / organization), hashed key storage, GET /me, upsert with external_ids, notes append, purchases, tasks, contact messages/calls, webhook management via API, change-feed webhooks for every event, signed deliveries, OpenAPI + interactive console, CSV export.

Who this is for: the programmer at a CRM vendor, a dealer group's IT team, or an automation consultant who has been asked "make I'm On Social and our CRM talk to each other." It explains the how in plain English and points at the exact endpoints. The full field-by-field reference is in the API Reference.

Time to first sync: about an afternoon for a one-way feed, two to three days for a solid two-way sync with a test store.

---

The one-paragraph version

I'm On Social is where the salesperson lives all day: texting customers from their own number, logging calls, voice notes, sold records, follow-ups, birthday and anniversary cards, and their AI assistant Jessi. Your CRM is where the dealership lives: deals, desking, F&I, inventory, reporting. A good integration lets each system keep doing what it is good at and copies the relationship data across so nobody types anything twice. Concretely: customers and deal status flow from the CRM into I'm On Social; texts, calls, notes, tags and sold records flow from I'm On Social back into the CRM.

---

What moves, and which way

Data	CRM -> I'm On Social	I'm On Social -> CRM
Customer record (name, phone, email, address)	POST /api/v1/contacts (upsert)	contact.created / contact.updated webhooks, GET /api/v1/contacts?updated_since=
Assigned salesperson	owner_email on the upsert	owner_user_id on every contact payload (map through GET /api/v1/users)
Deal / sold	POST /api/v1/contacts/{id}/purchases	deal.closed webhook
Notes	POST /api/v1/contacts/{id}/notes (appends)	note.added webhook, or GET .../notes
Texts and emails with the customer	POST /api/v1/contacts/{id}/messages (sends for real, from the rep's number)	message.sent / message.received webhooks, GET .../messages
Calls	not applicable	call.logged webhook (duration, outcome, transcript, AI summary)
Follow-up tasks	POST /api/v1/tasks (shows on the rep's Today list)	task.created / task.completed webhooks
Tags / segments	tags on upsert (additive), POST .../tags	contact.updated carries the full tag list
Internet leads	POST /api/leads/adf (ADF/XML) or POST /api/leads/webhook/{source_id} (JSON)	contact.created with source = the provider name
Anything else that happened in your system	POST /api/v1/contacts/{id}/events (shows on the customer's timeline in the app)	activity.logged webhook

Everything above is live today. Nothing in this guide requires a partnership agreement with us; a dealership admin creates an API key in the app and hands it to you.

---

Architecture in one picture

   YOUR CRM                                  I'M ON SOCIAL
 ┌───────────────┐   POST /api/v1/contacts    ┌────────────────────┐
 │ Customer saved│ ─────────────────────────> │ Contact (upsert,   │
 │ Deal closed   │   POST .../purchases       │ no duplicates)     │
 │ Task assigned │   POST /api/v1/tasks       │                    │
 └───────────────┘                            │  Rep texts, calls, │
                                              │  notes, tags, sells│
 ┌───────────────┐   webhook POST (signed)    │                    │
 │ Your endpoint │ <───────────────────────── │  Change feed (60 s)│
 │ /imos-webhook │   contact.updated,         └────────────────────┘
 └───────────────┘   message.received, ...
        │
        └── nightly: GET /api/v1/contacts?updated_since=<24h ago>  (reconcile)

Three moving parts:

1. Push (CRM -> us): call our REST API with an X-API-Key header whenever something changes on your side.
2. Webhooks (us -> CRM): we POST every change in the store to your URL within about a minute, signed with a shared secret.
3. Reconcile: once a day, pull updated_since and fix anything a webhook missed.

---

Step by step

1. Get a key from the dealership

The store's admin opens Tools -> Integrations -> API Keys -> New key, names it after your product, gives it read + write, and sends you the key. It starts with imos_live_. One key sees one store. For a dealer group ask them (or us) for an organization key.

Sanity check:

curl https://app.imonsocial.com/api/v1/me -H "X-API-Key: $KEY"

You should see the store name and users_visible > 0.

2. Map the salespeople

Pull GET /api/v1/users once and store our id next to each rep in your system, matched by email. You will need it to assign ownership and to read owner_user_id on incoming payloads. New hires appear as user.created webhooks.

3. Initial load

• Us -> you: GET /api/v1/export/contacts?format=json (up to 20,000 in one call). Save our id on your record.
• You -> us: loop over your customers and POST /api/v1/contacts with external_ids: {"<yoursystem>": "<your id>"} and source: "<yoursystem>". Rate limit is 120 requests per minute per key, so 5,000 customers take about 45 minutes; run it in the background and respect 429 + Retry-After.

Both directions are idempotent. Running the load twice changes nothing.

4. Turn on real time

curl -X POST https://app.imonsocial.com/api/v1/webhooks -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://yourcrm.com/imos-webhook", "events": ["*"], "secret": "<32+ random chars>", "description": "<Your product> sync"}'

Then POST /api/v1/webhooks/{id}/test and confirm your endpoint verifies the X-IMOS-Signature header (HMAC-SHA256 over the raw body, see the API Reference for copy-paste code in Python and Node).

5. Wire your side's events to our API

Whenever a customer, deal, note or task changes in your CRM, make the matching call from the table above. Include external_ids every time so matching is exact.

6. Reconcile nightly

GET /api/v1/contacts?updated_since=<yesterday>&limit=200 and page with offset. Treat each row as truth for the fields we own (see ownership below).

---

Matching and duplicates (read this twice)

When you POST /api/v1/contacts we look for an existing customer in this order and update it instead of creating a new one:

1. external_id / any value in external_ids (your id, exact match)
2. Phone number, last 10 digits (formatting ignored)
3. Email, case-insensitive
4. Exact first + last name, only if there is no conflicting phone on file

The response tells you what happened: {"id": "...", "created": true|false}. Store the id.

On a match we set the scalar fields you sent, add tags (never remove), merge external_ids, and append notes. We never blank a field because you left it out of the body. Send only what you own.

Phone is the primary identity in this product (it is what the rep texts). If a customer has several numbers put the mobile in phone and the rest in phones: [{"label": "work", "number": "..."}].

---

Who owns which field

Two systems writing the same field is where syncs go wrong. Our recommendation, which is how the app itself behaves:

Field group	Owner	Why
Identity: name, phone, email, address	CRM	Desking and F&I need the legal record
Deal data: sold date, vehicle, price, stock #, VIN	CRM (push to us via /purchases)	The deal is closed in the CRM
Assigned rep	CRM	Managers reassign in the CRM
tags, vehicle_interest, personal_details, notes	I'm On Social	The rep captures these on the lot and by voice
Texts, calls, voice notes, timeline	I'm On Social	They happen here
Follow-up tasks	Either, with idempotency_key	Both sides create them

Last write wins per field. If you must let both sides edit names or emails, compare updated_at on the webhook payload against your own timestamp and keep the newer one.

---

Avoiding echo loops

You push a customer -> a minute later contact.created arrives at your webhook -> naive code creates a duplicate on your side -> which pushes again. Two rules stop it:

• Ignore your own writes: every contact payload carries source and external_ids. If data.external_ids["<yoursystem>"] is set and data.updated_at is within a few seconds of your last push for that id, drop the event.
• Idempotency: X-IMOS-Delivery is unique per event. Keep the last 24 hours of ids and skip repeats. For tasks always send idempotency_key.

---

Field maps for the big four

These are starting points; every CRM has custom fields, so expect to add rows.

HubSpot

I'm On Social	HubSpot object.property
first_name, last_name	Contact firstname, lastname
phone	Contact mobilephone (fallback phone)
email	Contact email
external_ids.hubspot	Contact hs_object_id
owner_user_id	Contact hubspot_owner_id (map by email through Owners API)
tags	A multi-checkbox property imos_tags, or Lists
vehicle_interest, vehicle	Custom properties vehicle_interest, vehicle_owned
source	hs_lead_status / hs_analytics_source (read-only in HubSpot; store in a custom property)
note.added webhook	POST /crm/v3/objects/notes + association to the contact
message.sent/received	Notes with a [SMS in/out] prefix, or the Communications object (crm/v3/objects/communications, hs_communication_channel_type = SMS)
call.logged	POST /crm/v3/objects/calls (hs_call_body = AI summary, hs_call_duration in ms, hs_call_recording_url)
deal.closed	Update the Deal to closedwon, or create one with dealname = the vehicle
task.created	POST /crm/v3/objects/tasks

HubSpot -> us: subscribe to contact.creation / contact.propertyChange in a HubSpot app, or use a Workflow "Send webhook" action to POST /api/v1/contacts with the fields above.

Salesforce

I'm On Social	Salesforce
Customer	Contact (or Lead until converted; treat Lead.ConvertedContactId as the same person)
first_name, last_name, email	FirstName, LastName, Email
phone	MobilePhone (fallback Phone)
external_ids.salesforce	18-character Id. Put our id in a custom External ID field IMOS_Id__c so you can upsert by it
owner_user_id	OwnerId (map User.Email)
tags	Multi-select picklist IMOS_Tags__c or Topics
note.added, messages, calls	Task records (Subject = "SMS in: ...", TaskSubtype = Call/Email, CallDurationInSeconds, Description = body or transcript)
deal.closed	Opportunity StageName = Closed Won, CloseDate = sold date
task.created	Task with Status = Not Started, ActivityDate = due date

Salesforce -> us: Platform Events or an Apex trigger on Contact calling a Named Credential that POSTs to /api/v1/contacts; or Flow's HTTP Callout action.

Zoho CRM

I'm On Social	Zoho
Customer	Contacts module (or Leads before conversion)
first_name, last_name, email	First_Name, Last_Name, Email
phone	Mobile (fallback Phone)
external_ids.zoho	record id
owner_user_id	Owner.id (map Owner.email)
tags	Zoho Tags (/Contacts/{id}/actions/add_tags)
note.added, messages	Notes module attached to the contact (Note_Title = "SMS in", Note_Content)
call.logged	Calls module (Call_Duration, Description)
deal.closed	Deals with Stage = Closed Won
task.created	Tasks module

Zoho -> us: Notifications API (/actions/watch on Contacts) or a Workflow Rule webhook.

Pipedrive

I'm On Social	Pipedrive
Customer	persons
first_name + last_name	name (we split on the last space if you only have name)
phone, email	phone[] (label mobile), email[]
external_ids.pipedrive	person id
owner_user_id	owner_id (map users.email)
tags	Custom field (multiple options) or Labels
note.added, messages	notes (content, person_id)
call.logged	activities with type = call, duration, done = 1, note = summary
deal.closed	deals status = won, title = vehicle
task.created	activities with type = task, due_date

Pipedrive -> us: Webhooks (event_action = added|updated, event_object = person) pointing at your middleware, which upserts to /api/v1/contacts.

---

Sending texts through the API (compliance)

POST /api/v1/contacts/{id}/messages sends a real SMS from the salesperson's number and it lands in their inbox thread like any other text. Rules that apply automatically: customers who texted STOP are skipped, quiet hours configured by the store are honored, and every message is logged on the timeline. Your responsibility: only send to customers who consented to texts from the dealership (TCPA / CTIA). Do not use the API for bulk marketing; that is what the app's campaign tools with opt-in tracking are for.

---

Rate limits, retries, errors

• 120 requests per minute per key. Bulk loads: batch at 100 per minute and honor Retry-After.
• Webhooks are delivered once per event; a non-2xx from you is logged (GET /api/v1/webhooks/{id}/deliveries) and not retried. Your nightly updated_since pull is the safety net.
• Errors are JSON: {"detail": "..."}. 404 also means "exists but not in your store"; never treat it as "create it again".

---

Go-live checklist

1. GET /api/v1/me shows the right store and users_visible matches the roster.
2. Reps mapped by email; unmatched reps listed for the store manager.
3. Initial load both ways done; spot-check 10 customers in both UIs.
4. Webhook registered, /test ping verified with the signature code (not just a 200).
5. Edit a customer in the app -> contact.updated arrives -> your record changes, no duplicate created.
6. Save a customer in your CRM -> it appears in the app under the right rep, once.
7. Mark a customer sold in the app -> deal.closed -> your deal/opportunity updates.
8. Text from the app -> message.sent logged on your side; reply from the customer -> message.received.
9. Echo test: push a record, wait 2 minutes, confirm your webhook handler ignored its own write.
10. Nightly reconcile scheduled; alert if it changes more than 5% of records (usually a mapping bug).
11. Test data cleaned up (?tag=api-test) and the test key revoked.
12. Store manager has a one-page "what syncs where" sheet (copy the table at the top of this guide).

---

Automotive CRMs (VinSolutions, Elead, DealerSocket, DriveCentric, Reynolds, Tekion)

These CRMs do not offer public APIs; each has a partner program. What works today without certification:

• Leads into the CRM: the app can push any contact as a standards-compliant ADF/XML lead to the CRM's lead intake email address (contact page -> "Push to CRM", or bulk from the Contacts tab). Every automotive CRM accepts ADF by email.
• Leads into I'm On Social: point any lead provider or the CRM's lead forwarding at POST /api/leads/adf?source_id=... or the per-source intake email.
• Reports and exports: CSV in both directions.
• Automation tools: Zapier / Make connectors many dealers already run against their CRM, wired to our webhooks and API.

The certification path per vendor, with costs and timelines, is in Automotive CRM Programs.

---

Getting help

• Interactive console: https://app.imonsocial.com/api/public/reference
• OpenAPI schema: https://app.imonsocial.com/api/public/openapi-v1.json
• Sandbox store, organization keys, or a call with our engineers: support@imonsocial.com with your company, the CRM, and the dealership you are integrating for.

Purpose: a working checklist for getting I'm On Social certified with the automotive CRM and DMS vendors our dealers use, so customer records, notes, texts and sold data can sync directly instead of through ADF email and CSV. Program details below were researched in September 2026 from vendor sites and agreements; fees and timelines change, so confirm each one on the first call.

Bottom line: none of the big automotive CRMs have a self-serve API. Every one is a gated partner program with an application, a contract (usually under NDA), a security review, a certification test and, for most, fees plus per-rooftop dealer authorization. Plan on 2 to 6 months per vendor. Start with the fastest ones (Tekion, Fortellis) while the slow ones (Cox, Reynolds) are in the queue.

---

At a glance

Vendor / CRM	Program	Access model	Cost signal	Realistic timeline	Works today without certification
CDK Global (Elead CRM, CDK CRM/Drive DMS)	Fortellis Automotive Commerce Exchange	Self-register, then mandatory app certification per app	Certification fee (quoted in welcome email); recert up to $2,500; $129/month per Marketplace listing; API usage per publisher plan	6 to 12 weeks after the app is built	ADF email into Elead; ADF/lead forwarding out of Elead
Cox Automotive (VinSolutions Connect CRM; also Dealer.com, vAuto, HomeNet, Xtime)	Cox Automotive Partner Program / Developer Network	Application, Participation Form, VinSolutions Integration Terms; per-rooftop dealer enablement	Negotiated per vendor; pass-through to dealers capped at actual cost	3 to 6 months	ADF email into VinSolutions; lead forwarding out
Reynolds and Reynolds (FOCUS CRM, ERA-IGNITE / POWER DMS)	Reynolds Certified Interface (RCI)	Inquiry, technical + security review, contract under NDA; recertification every 2 years	Not public. Historically the most expensive program (one-time participation + per-dealer fees)	6+ months, enterprise-style engagement	ADF email into FOCUS; CSV
DealerSocket (Solera)	Certified Partners program	Sales-gated contract; credentials issued per rooftop	Not public	3 to 6 months	ADF/XML lead forwarding out; ADF email in; inbound activity sync only for partners
DriveCentric	Partner Program	Inquiry form -> overview call -> data agreement -> docs	Not public	2 to 4 months (they note high demand / slow replies)	ADF email in
Tekion (Automotive Retail Cloud, CRM + DMS)	Automotive Partner Cloud (APC) 2.0	Automated onboarding: pick use case + APIs in the APC dashboard, review, then docs + test tools	Tiered (Standard / Enterprise / Strategic) with different rate limits and support	4 to 8 weeks	ADF email in

---

What we already have (use this in every application)

Vendors ask the same questions. We can answer these today:

• Public, documented REST API with API-key auth, tenant scoping, rate limiting, OpenAPI schema and an interactive console: https://app.imonsocial.com/api/public/reference.
• Signed webhooks (HMAC-SHA256) for every data change, with a delivery log per subscription.
• ADF/XML 1.0 lead intake (POST /api/leads/adf) and ADF lead push by email to any CRM intake address.
• Full request logging on the API and webhook side (delivery logs kept; Fortellis requires 60 days of request/response logs for the certified app, so plan to extend retention to 60+ days for the Fortellis connector).
• Data isolation per store and organization, hashed key storage, instant key revocation, HTTPS only.
• Consent handling: STOP / opt-out honored automatically on every send path; SMS terms published at /imos/sms-terms.
• Privacy Policy and Terms at /imos/privacy and /imos/terms.
• Dealer authorization flow: the store's admin creates and revokes keys themselves, which maps cleanly onto the "dealer must enable the vendor per rooftop" model every program uses.

---

Universal prep checklist (do once, reuse for every vendor)

Company and legal - [ ] Legal entity details, EIN, D-U-N-S number, business address, officer to sign agreements - [ ] Certificate of insurance (general liability; several programs ask for cyber/E&O, typically $1M+) - [ ] W-9 and ACH details (Fortellis bills through the platform) - [ ] NDA on file (Reynolds, DealerSocket and Cox will send theirs)

Security and data handling - [ ] One-page data flow diagram: what we read, what we write, where it is stored (MongoDB, region), who can see it - [ ] Written Information Security Policy (access control, encryption in transit/at rest, key rotation, incident response, employee access) - [ ] Data retention and deletion policy, including "dealer leaves: what happens to their data" - [ ] Subprocessor list (Twilio, OpenAI, Resend, Stripe, hosting provider) - [ ] Security questionnaire answers ready (SIG Lite / CAIQ style). SOC 2 Type I is not mandatory for most CRM programs but shortens every review; start it if we plan to do Reynolds or Cox - [ ] Penetration test summary or vulnerability scan report from the last 12 months - [ ] Breach notification commitment (most agreements require notice within 24 to 72 hours)

Product and technical - [ ] Integration Workflow document: every API call we make, why, how often, expected volume per rooftop per day (Fortellis requires this before certification starts) - [ ] 60-day request/response log retention for certified connectors - [ ] Sandbox / test store with fake customers (+1 500 555 01xx numbers) and a demo login for the vendor's reviewer - [ ] Field map for the vendor's objects (customer, deal, note, activity, user) to ours, including how we handle dealer-side merges and deletes - [ ] Loop prevention and dedupe description (see the CRM Integration Guide) - [ ] Marketplace listing kit: 100-word description, 3 to 5 screenshots, logo (SVG + PNG), pricing text, support contact, privacy URL - [ ] Support SLA statement (hours, response time, escalation email)

Commercial - [ ] Decide pricing pass-through: Cox forbids marking up their integration fee to mutual dealers; Fortellis charges us per listing and per API plan. Set our per-rooftop integration price accordingly - [ ] Reference dealers willing to take a vendor call (most programs ask for at least one mutual client)

---

Vendor by vendor

1. Tekion (Automotive Partner Cloud 2.0) - start here

Why first: the only program with automated onboarding. Dealer count is growing fast and their dealers skew toward technology-forward stores.

Steps 1. Create an account at apc.tekioncloud.com, choose the use case (CRM customer + activity sync) and the specific APIs. 2. Submit for review; on approval you get API docs, sandbox credentials and test tools inside APC. 3. Build the connector against the sandbox; request the tier (Standard is enough to start; Enterprise raises rate limits). 4. Dealer enablement is done by the dealer inside Tekion; document the steps for our store admins.

Gotchas: tiers gate which APIs you can call; check that customer write, notes/activities and deal read are in the tier before building.

2. CDK Global / Fortellis (Elead CRM, CDK Drive)

Why second: self-registration, public docs, clear (if not cheap) fee schedule, and Elead is one of the most installed CRMs.

Steps 1. Register a developer account on Fortellis, create the app, request the CRM APIs (customer, sales opportunity, activities, direct post). 2. Get test-environment access and build against it. 3. Submit the Integration Workflow document through the Developer Care Portal before certification; implement full request/response logging with 60-day retention. 4. Pay the certification fee when the welcome email arrives (due about 31 days later; it auto-charges). 5. Certification with a Fortellis Business Process Consultant: functional tests and possibly an end-to-end demo. 6. Submit the Marketplace listing ($129/month per listing). Dealers subscribe to the app in the Marketplace, which is how per-rooftop authorization works. 7. Any change to the app or the APIs it uses can trigger recertification (up to $2,500 USD).

Gotchas: API usage may be billed per the API publisher's plan (transactional or subscription); read the plan on each API before designing polling frequency. Elead-specific CRM APIs are separate from CDK Drive DMS APIs; we want the CRM set.

3. Cox Automotive (VinSolutions Connect CRM)

Why third: the largest CRM footprint, but a longer, negotiated process.

Steps 1. Apply through the Cox Automotive Developer Network / VinSolutions gateway registration. 2. Sign the Participation Form and accept the VinSolutions Integration Terms (confidential specs; per-rooftop dealer authorization; no marking up their fee). 3. Request the right plans: Contact Management (create/update contacts, consent), Lead Management (lead + vehicle sync), and Connect Eventing (near-real-time change notifications, which replaces polling). 4. OAuth2 client-credentials + API key are issued after signature; build and test. 5. Each dealer enables us in their VinSolutions settings; write the one-page dealer guide.

Gotchas: fees are negotiated; expect a per-rooftop monthly amount. The Call Tracking plan is restricted to authorized call providers; we do not need it (our calls run on Twilio and are logged on our side). Consent fields matter: pass SMS consent status both ways.

4. DealerSocket (Solera)

Steps 1. Contact the DealerSocket partner team through sales; there is no developer portal. 2. NDA + Certified Partner agreement. 3. Integration options historically offered: outbound lead forwarding (XML/email), inbound activity sync (calls, appointments, notes), entity sync for website data. Ask for customer read/write plus activity write. 4. Credentials are issued per rooftop after the dealer signs their authorization.

Gotchas: expect long lead times and manual onboarding per dealer. Until certified, ADF email into DealerSocket and lead forwarding out of it are the reliable paths.

5. DriveCentric

Steps 1. Fill in the partner inquiry form on drivecentric.com/resources/partner-program. 2. Overview call, then sign their data agreement. 3. API documentation is shared privately after signature. Their partner API is push-oriented (leads, consumer/household data, vehicle data); confirm whether outbound customer/activity events are available.

Gotchas: they publicly note high partner demand and slower responses; apply early and follow up every two weeks.

6. Reynolds and Reynolds (RCI; FOCUS CRM, ERA-IGNITE, POWER)

Why last: the most closed program, historically the most expensive, biannual recertification, active audits.

Steps 1. Submit an inquiry through Reynolds Data Management. 2. Technical and security review (this is where SOC 2 and the security policy pay off). 3. Contract under NDA; one-time participation fee plus per-dealer interface fees. 4. Certification, then recertification every 2 years or on significant releases.

Gotchas: budget for both the fee and the calendar. Only pursue when we have several Reynolds dealers asking.

---

Recommended order and rough calendar

Month	Action
1	Finish the universal prep checklist. Apply to Tekion APC and register on Fortellis. Send Cox and DriveCentric inquiries (they take longest to answer).
2	Build the Tekion connector in their sandbox. Write the Fortellis Integration Workflow doc.
3	Tekion review and first mutual dealer. Fortellis test environment build.
4 to 5	Fortellis certification + Marketplace listing. Cox Participation Form and plans.
6+	VinSolutions build and first dealer enablement. DealerSocket and DriveCentric as agreements land. Reynolds only on dealer demand.

---

Application blurb (copy and adapt)

I'm On Social is a relationship platform for dealership salespeople: personal texting from a dedicated number, call logging with AI summaries, voice notes, automated birthday, anniversary and sold follow-up campaigns, digital business cards with review collection, and an AI assistant. We integrate with the CRM so the customer record, assigned salesperson and deal status flow into I'm On Social, and every text, call, note, tag and sold record the salesperson creates flows back into the CRM. We already operate a documented public REST API with tenant-scoped API keys, signed webhooks and ADF/XML lead intake (https://www.imonsocial.com/developers). We are requesting customer read/write, activity/note write and deal read for dealers who authorize us.

---

Tracker

Vendor	Status	Contact	Applied	Agreement	Sandbox	Certified	First dealer	Notes
Tekion APC	Not started
CDK Fortellis (Elead)	Not started
Cox / VinSolutions	Not started
DealerSocket	Not started
DriveCentric	Not started
Reynolds RCI	Not started

Sources checked (Sep 2026): Fortellis App Launch Guide and API licensing terms (cdkglobal.com), Cox Automotive VinSolutions Integration Agreement (coxautoinc.com/terms), Reynolds Data Management and RCI pages (reyrey.com), DriveCentric Partner Program page, Tekion APC (apc.tekioncloud.com), public API report cards for DealerSocket/DriveCentric/VinSolutions.