Fyndol API & MCP

Fyndol is the all-in-one CRM and marketing platform for marketing agencies of any niche. Connect AI assistants and your own software to a Fyndol agency. Everything is limited to the agency (and sub-accounts) the person who connected can access.

Authentication

• OAuth 2.1 — metadata at /.well-known/oauth-authorization-server. Apps acting for a person use the authorization code flow with PKCE (S256); access tokens last 1 hour, refresh tokens 30 days (rotated on use). Server-to-server apps use client credentials: an agency owner/admin creates them in Settings → Connect AI apps → Developers.
• API keys — one sub-account each, made by an owner/admin in Settings → Webhooks & API → Developers.

curl https://app.fyndol.com/api/v1/contacts?limit=10 \
  -H "Authorization: Bearer <access token or API key>"

Scopes

Changes and approvals

A change (POST /api/v1/actions or an MCP write tool) becomes a pending change with an approve_url, and the person approves it in Fyndol — unless the connection has changes.auto (owner/admin only) or the sub-account's AI changes setting is “without asking”; then it runs right away, the reply says why (reason) and the person is notified (onboarding a client, draft invoices and contracts, stopping workflow enrollments and turning on a contact's consent to be called or texted always wait). The contact, tag and opportunity endpoints below follow the same rule for OAuth tokens: they write directly when the change may run right away (otherwise 403 approval_required — use POST /api/v1/actions), and they also need contacts.read (contacts) or opportunities.read (opportunities), because they answer with the record. API keys write directly. No endpoint or tool sends texts or emails, deletes records, buys anything or reads keys — but a change such as adding a tag, creating a contact or moving a deal starts the sub-account's published workflows, which may text, email or call contacts.

Consent and Do Not Disturb

An API key or a connected app can never turn ON a contact's consent to be called or texted (custom fields like ai_call_consent, sms_consent, tcpa_consent, sms_opt_in) or turn OFF Do Not Disturb. Only the contact can give consent (a Fyndol form, booking page or their own reply), or a person sets it on the contact in Fyndol. POST /contacts still saves the contact without those values and lists them in ignored_fields and warnings (a note on the contact says what was sent); PATCH /contacts/{id} answers 403 and changes nothing; an MCP or /actions change that does it waits for a person's approval. Saying No, sending a Yes the contact already gave and turning Do Not Disturb on always work. Other fields, like terms_consent or gdpr_consent, save normally.

Pagination, limits and errors

• Lists take limit (1–100, default 25) and offset and return { data, pagination: { total, limit, offset, has_more, next_offset } }.
• 120 requests per minute per token or key. Every reply has X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; over the limit you get 429 with Retry-After.
• Errors: { "error": "plain message", "code": "snake_case" } with status 400 / 401 / 403 / 404 / 409 / 429.

Endpoints

Sub-account ids come from GET /api/v1/sub-accounts. Tokens limited to one sub-account (and API keys) don't need location_id.

Inbound webhooks (leads from website forms, Zapier, Make)

Make an inbound URL in Settings → Webhooks & API → Inbound webhooks. POST JSON (or form fields) to it; no key or login is needed (the URL is the secret). Send at least one of email, phone, first_name (or name); last_name, company and tags (only used when the URL allows them) are optional, and any other field can be used in that URL's workflows as {{webhook.<field>}}.

• Success: 200 with {"ok":true}, the same reply whether the contact is new or already existed. It never includes a contact id.
• Errors: 400 { "error": "plain message" } when the data sent can't be used (no email, phone or name; an email or phone that isn't valid) · 404 wrong URL · 429 too many posts (wait Retry-After seconds).

curl -X POST '<your inbound webhook URL>' \
  -H 'Content-Type: application/json' \
  -d '{"first_name":"Jane","email":"jane@example.com","phone":"5105550100","message":"Need a quote"}'
# → {"ok":true}