Sparky Contacts API

Search and read the organization's contacts, and create a contact.

Address: https://contacts.sparkyli.com/api/v1
Plan: Plus and Max, with API access switched on for the organization
Specification: https://contacts.sparkyli.com/api/v1/openapi.yaml

Endpoints

GET /contacts

Search and list contacts (not archived), by name.

q matches name, email or company.

Inputs

Name	Type	What it is
q	text, up to 80 characters	Part of a name, email or company.
limit	whole number 1 to 100	Page size. Default 50.
offset	whole number	Use next_offset from the previous page.

Answer: contacts (a list) and next_offset

Name	Type	What it is
id	text	The contact's id.
name	text	The person's name.
email, phone, company, job_title	text or null	As entered.
city, state, country, website, language	text or null	As entered.
preferred_channel, source	text or null	How to reach them, and where the contact came from.
do_not_contact, email_consent	0 or 1	Marketing flags.
created_at, updated_at	text	UTC time, like 2026-11-03 07:09:01.
next_offset	whole number or null	Pass as offset for the next page; null on the last page.

GET /contacts/{id}

One contact with notes and billing details.

Inputs

Name	Type	What it is
id*	text	The contact's id.

Answer: contact

Name	Type	What it is
(all the list fields, and these)
currency, timezone, billing_address, tax_id, payment_terms	text or null	Billing details.
address_line, postal_code, notes, email_consent_at	text or null	As entered.

Errors (besides the common ones)

404 not_found: No such contact, or it is archived.

POST /contacts

Create a contact, like New contact in the app.

Needs a role that may create contacts. It does not look for a contact with the same email: search first if unsure.

Inputs

Name	Type	What it is
Idempotency-Key	header, text up to 120 characters	New for each contact. A retry with the same key returns the first answer instead of a second contact.

Body (JSON)

Name	Type	What it is
name*	text, up to 200	The person's name.
email	text, up to 200	Must look like an email address.
phone	text, up to 40
company	text, up to 200

Answer: contact

Name	Type	What it is
id	text	The new contact's id.
name, email, phone, company	text or null	As saved.
created_at, updated_at	text	UTC time.

Errors (besides the common ones)

400 bad_request: name is missing, or a field is too long or wrong (the message names it).
403 plan_limit: The plan's contact limit is reached.

Example body

{ "name": "Asha Rao", "email": "asha@asha.example", "phone": "+91 98200 00000", "company": "Asha Traders" }

Example answer (201)

{ "contact": { "id": "con_8c1f0f3e-1b8e-4a3e-9d0c-6a2c1e5b7a10", "name": "Asha Rao", "email": "asha@asha.example", "phone": "+91 98200 00000", "company": "Asha Traders", "created_at": "2026-11-03 07:09:01", "updated_at": "2026-11-03 07:09:01" } }

Example

curl -s -H "authorization: Bearer $TOKEN" "https://contacts.sparkyli.com/api/v1/contacts?q=acme&limit=5"

New here? Start with the three things first, then sign in. Errors are explained under errors and limits.