All docs

Contacts in the API and for AI agents

Do everything you can do in the contact book from the REST API or from an AI agent: the abilities, the endpoints, paging and the tools.

Updated . 5 min read.

Whatever you can do in the Contacts area of the dashboard, you can do from the REST API and from an AI agent connected to your workspace. This page is a map. The details live in the API reference and the machine-readable spec.

REST API

The API lives at https://formspring.io/api/v1 and uses a bearer token. Create a token with the right abilities. See Tokens & abilities.

Ability What it allows
contacts:read Read contacts, fields, tags, lists, views, notes, the timeline, tasks, companies and deals.
contacts:write Create, change and erase them, and run imports, exports and bulk actions.
desk:reply Needed in addition to contacts:write to send an email from a contact.

Endpoint groups

Group Paths
Contacts /contacts, /contacts/{contact}, /contacts/{contact}/owner
Custom fields /contact-fields
Tags and lists /contact-tags, /contact-lists, /contacts/{contact}/tags, /contact-lists/{list}/members
Saved views /contact-views
Several emails and phones /contacts/{contact}/identifiers, and /contacts/{contact}/identifiers/{identifier}/verification to send the confirmation
Consent /contacts/{contact}/consents (marketing email, SMS, phone, WhatsApp and post)
Duplicates and merging /contacts/duplicates, /contacts/{contact}/merge, /contacts/{contact}/merges
Bulk actions /contacts/bulk
Import /contacts/imports, with /dry-run, /run and /errors
Export /contacts/exports
Email from a contact /contacts/{contact}/email, /contact-email-templates, /contact-email-signature
Who owns new contacts /crm/capture-owner
Data requests /contacts/{contact}/access-exports
Plan and retention /crm/entitlements, /crm/retention
Timeline, notes and activities /contacts/{contact}/timeline, /notes, /activities
Tasks and stages /tasks, /lifecycle-stages
Companies /companies
Pipelines and deals /pipelines, /deals

Companies and deals need the Team plan or above. Email from a contact needs Scale.

Paging and errors

  • Lists are paged with a cursor. Send the next_cursor of a response back as cursor to get the next page. The contact list takes a per_page of up to 100.
  • A contact's notes and activities (100 per page), a company's people (200) and a contact's consent history (20) also take cursor and per_page, and answer meta.next_cursor, which is null on the last page. Without them you get the same first page as before. Treat a cursor as opaque; one that is not valid starts again at the first page. GET /companies/{company} returns contacts_has_more when the company has more than 100 people; use /companies/{company}/contacts for all of them.
  • 402 means the workspace's plan does not include contacts, or the feature you asked for. The message says which, in the same words as the dashboard.
  • 403 means the token is missing the ability.
  • 404 means the record does not exist, or belongs to another workspace.
  • Imports, exports and bulk actions answer straight away and finish in the background. Poll the record you got back to see its progress.

The full list of requests and answers is in the OpenAPI document at /api/v1/openapi.json. Notes, tasks, companies and deals have their own page, CRM API. Error codes are explained under API errors.

AI agents

An agent that is connected to Formspring can work the contact book too: every action in the dashboard has a tool. Connect it as described in the MCP server overview and give its token the same abilities as above. The full list is on Tools. By purpose:

What you want Tools
Find and edit contacts list_contacts, get_contact, create_contact, update_contact, delete_contact
Notes and the timeline add_contact_note, list_contact_notes, update_contact_note, pin_contact_note, delete_contact_note, list_contact_timeline, log_contact_activity
Consent record_contact_consent (with a channel), list_contact_consents
Duplicates list_contact_duplicates, merge_contacts, undo_contact_merge, list_contact_merges
Tags, lists, fields and views create_contact_tag, tag_contact, untag_contact, create_contact_list, add_contacts_to_list, create_contact_field, update_contact_field, create_contact_view and their list, update and delete tools
Owner and identifiers assign_contact_owner, add_contact_identifier, update_contact_identifier, request_contact_identifier_verification, remove_contact_identifier
Import, export, bulk import_contacts, get_contacts_import, export_contacts, get_contacts_export, bulk_contacts, get_contact_bulk_operation
Stages, tasks and follow-ups set_contact_lifecycle_stage, list_lifecycle_stages, save_lifecycle_stage, create_contact_follow_up, list_tasks, create_task, update_task
Companies, pipelines and deals list_companies, save_company, set_company_contact, merge_companies, list_pipelines, save_pipeline, list_deals, save_deal, move_deal
Email get_contact_email_availability, send_contact_email, list_contact_email_templates, save_contact_email_template, delete_contact_email_template, get_contact_email_signature, set_contact_email_signature
Privacy and plan request_contact_access_export, get_contact_access_export, get_crm_retention, set_crm_retention, get_crm_capture_owner, set_crm_capture_owner, list_assigned_contacts, mark_assigned_contacts_seen, reorder_contact_fields, get_crm_entitlements

request_contact_identifier_verification and send_contact_email reach people outside your workspace, so they go through the same outbound rules as everything else Formspring sends. A second email or phone number that is not verified never identifies a contact, whoever added it.

Agents follow the same rules as everyone else: the plan is checked, values are checked against the field types, deleting is queued, and an agent can only reach the workspace its token belongs to.