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_cursorof a response back ascursorto get the next page. The contact list takes aper_pageof 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
cursorandper_page, and answermeta.next_cursor, which isnullon 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}returnscontacts_has_morewhen the company has more than 100 people; use/companies/{company}/contactsfor all of them. 402means the workspace's plan does not include contacts, or the feature you asked for. Themessagesays which, in the same words as the dashboard.403means the token is missing the ability.404means 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 |
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.
