Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Sendpulse Contacts API
x-refined-note:
- x-ai-description differs across the merged source definitions and was not carried
version: '1.0'
description: 'Operations tagged Contacts across 9 of this provider''s published API definitions: sendpulse-crm-openapi.yml, sendpulse-facebook-openapi.yml, sendpulse-instagram-openapi.yml, sendpulse-live-chat-openapi.yml, sendpulse-sms-openapi.yml, sendpulse-telegram-openapi.yml, sendpulse-tiktok-openapi.yml, sendpulse-viber-chatbot-openapi.yml, sendpulse-whatsapp-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.sendpulse.com/crm/v1
- description: ''
url: https://api.sendpulse.com/messenger
- description: ''
url: https://api.sendpulse.com/instagram
- description: ''
url: https://api.sendpulse.com/live-chat
- url: https://api.sendpulse.com
- description: ''
url: https://api.sendpulse.com/telegram
- description: ''
url: https://api.sendpulse.com/tiktok
- description: ''
url: https://api.sendpulse.com/viber/chatbots
- description: ''
url: https://api.sendpulse.com/whatsapp
security:
- apiKey: []
- oauth2: []
tags:
- description: ''
name: Contacts
paths:
/contacts/get-list:
post:
tags:
- Contacts
summary: Get contacts list
requestBody:
content:
application/json:
schema:
properties:
limit:
type: integer
minimum: 1
maximum: 100
offset:
type: integer
minimum: 0
from:
type: string
format: date
description: Contact creation date, filter start date. Accepted format YYYY-MM-DD
to:
type: string
format: date
description: Contact creation date, filter end date. Accepted format YYYY-MM-DD
updateFrom:
type: string
format: date
description: Contact updated date, filter start date. Accepted format YYYY-MM-DD
updateTo:
type: string
format: date
description: Contact updated date, filter end date. Accepted format YYYY-MM-DD
firstName:
type: string
description: Contacts first name you want to search for
lastName:
type: string
description: Contacts last name you want to search for
responsibleIds:
type: array
description: A list with the ID of users assigned to the contact you want to to search for. It can be obtained with the "Get a list of team members" method
items:
type: integer
sourceType:
type: array
items:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 8
- 9
- 10
phone:
type: string
description: Phone number of a contact
email:
type: string
tagIds:
type: array
items:
type: integer
messengerTypeIds:
type: array
items:
type: integer
messengerLogin:
type: string
sortBy:
type: object
properties:
direction:
type: string
description: 'Sorting direction. Possible values: asc — ascending order; desc — descending order.'
enum:
- asc
- desc
fieldName:
type: string
enum:
- id
- created_at
- first_name
- attributeId
- responsible_id
example: id
attributes:
$ref: '#/components/schemas/AttributesProperty'
location:
type: string
fieldValueConditions:
type: array
items:
type: object
properties:
field:
type: string
description: Field name
enum:
- attributes
- lastName
- phones
- emails
- messengers
- location
- tags
expression:
type: string
description: '| Possible values:
- eq (=) - neq (!=) - gt (>) - gte (>=) - lt (<) - lte (<=) - like - in (check among list of values).'
value:
description: Can have array or string type
ids:
type: array
description: Array of contacts IDs
items:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
data:
properties:
list:
items:
$ref: '#/components/schemas/Contact'
total:
type: integer
searchRequest:
type: string
operationId: getContactsList
x-ai-role: crm_data_analyst
x-ai-description: Powerful filtered search across the CRM contact base. Unlike a simple list fetch, this endpoint supports multi-dimensional filtering — by creation/update date ranges, assigned team members, source types, tags, messengers, custom attributes, and field-level conditions. Used to build segmented views, audit contact data, or feed downstream automation with a precise contact subset.
x-ai-reasoning-instructions:
- Combine filters additively — all provided conditions are applied simultaneously (AND logic), so overly specific combinations may return empty results.
- Use `from`/`to` for filtering by creation date and `updateFrom`/`updateTo` for recently modified contacts — do not mix up the two date ranges.
- When filtering by `responsibleIds`, first call 'Get a list of team members' to resolve names to IDs.
- Paginate using `limit` (max 100) and `offset` — for large datasets, iterate until `total` is exhausted.
- If `fieldValueConditions` is used, ensure `field` names match the schema enum — typos cause silent empty results.
- For sorting by a custom attribute, use `attributeId` as `fieldName` and provide the actual attribute ID.
- When the user describes a search intent in natural language, map it to the most specific available filters before falling back to broad ones.
x-ai-responding-instructions:
- Report the total count from `searchRequest` or `total` field alongside the list — it helps the user understand whether they got all results or need to paginate.
- If the result list is empty, suggest reviewing the filter combination — one overly restrictive condition is often the cause.
- When returning a subset of a large dataset, remind the user to paginate with `offset` to retrieve remaining records.
- If the user searched by a specific filter (e.g., tag, responsible), confirm which filter was applied and how many contacts matched.
x-ai-suggestions:
- Filter contacts created in the last 30 days using `from`/`to` date range.
- Use `tagIds` + `messengerTypeIds` together to find contacts reachable via a specific channel with a given tag.
- Sort by `created_at` descending to get the newest contacts first.
- 'Use `fieldValueConditions` with `expression: like` for partial name/email matching when exact values are unknown.'
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
servers:
- url: https://api.sendpulse.com/crm/v1
/contacts/get-list-by-email:
post:
tags:
- Contacts
summary: Search contacts by email
description: 'Returns contacts and the following information about each: the contact ID, the assigned person and the contact information'
requestBody:
content:
application/json:
schema:
properties:
email:
type: string
description: Email address of a contact
isEmailFullSearch:
type: boolean
description: Search for emails that match completely or partially (true/false)
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
data:
properties:
list:
description: List with contacts
type: array
items:
$ref: '#/components/schemas/Contact'
total:
description: Total number of filtered records for pagination
type: integer
operationId: getContactListByEmail
x-ai-role: crm_data_analyst
x-ai-description: Performs a lookup of CRM contacts by email address, returning full contact records including assigned responsible persons and contact details. Useful for deduplication checks, pre-call research, and verifying whether a lead already exists before creating a new one. The partial-match mode makes it effective for domain-level searches (e.g., finding all contacts from a company).
x-ai-reasoning-instructions:
- If the user provides a full email address, default isEmailFullSearch to true to avoid unrelated results.
- When the user wants to find all contacts from a domain (e.g., '@company.com'), set isEmailFullSearch to false for partial matching.
- Before creating a new contact, suggest running this search first to prevent duplicates.
- Use the returned total field to determine if pagination is needed — if total exceeds the returned list size, advise the user to paginate.
x-ai-responding-instructions:
- Report how many contacts were found (use the total field, not the list length).
- If a single exact match is found, surface the contact ID and assigned person prominently.
- 'If no contacts are found, suggest trying partial search (isEmailFullSearch: false) or verifying the email spelling.'
- If multiple contacts are returned, summarize them as a list with ID, name, and assigned person.
x-ai-suggestions:
- 'Use isEmailFullSearch: false to find all contacts sharing an email domain.'
- Combine results with getContact to retrieve full contact details by ID.
- Run this before createContact to enforce uniqueness within the CRM.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
servers:
- url: https://api.sendpulse.com/crm/v1
/contacts:
post:
deprecated: true
tags:
- Contacts
summary: (Deprecated). Use POST /contacts/create instead to create a new contact
description: Creates a contact with the given properties and returns a copy of the information, including the ID
requestBody:
content:
application/json:
schema:
properties:
responsibleId:
type: integer
description: Team member ID to assign to a contact. It can be obtained with the "Get a list of team members" method
firstName:
type: string
description: Contact first name
lastName:
type: string
description: Contact last name
phones:
type: array
description: List of phone numbers in the international format
items:
type: string
emails:
type: array
description: List of email addresses
items:
type: string
tags:
type: array
description: List of tag IDs to be added to a contact. It can be obtained with the "Get a list of contact tags" method
items:
type: integer
attributes:
type: array
description: 'List of fields to add to the contact. Pass in the attributes field array an object with the attributeId and value fields (will create a contact with an already existing attribute) Pass in the attributes field
array an object with the name, type , value fields (will create a contact with a new attribute
if there is no such attribute yet or create a contact with an existing attribute if the attribute already exists)''
'
items:
properties:
name:
type: string
description: Attribute name
value:
type: string
description: Attribute value
type:
type: integer
description: 0 - text, 1 - number, 2 - date, 3 - link, 4 - select , 5 - multiSelect
required:
- name
- value
messengers:
type: array
description: List of messengers to add to a contact
items:
properties:
typeId:
$ref: '#/components/schemas/MessengerTypeProperty'
login:
type: string
description: Contacts login in the specified messenger
required:
- typeId
- login
attachments:
type: array
items:
type: string
description: First, the file must be uploaded to the file manager, and then the file can be attached.
example:
- /personal/deal/sendPulse_crm_deals.csv
required:
- responsibleId
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/Contact'
operationId: createContact
x-ai-role: crm_data_entry_specialist
x-ai-description: Deprecated endpoint for creating a CRM contact with full profile data including phones, emails, messengers, custom attributes, and file attachments. Replaced by POST /contacts/create — use that instead for all new integrations. This endpoint remains for backward compatibility only.
x-ai-reasoning-instructions:
- This endpoint is deprecated — always redirect the user to POST /contacts/create unless they explicitly need backward compatibility.
- Before creating, consider checking for duplicate contacts by phone or email to avoid data pollution in the CRM.
- The `responsibleId` is required — ensure the team member ID is obtained via the 'Get a list of team members' method before calling.
- For `attributes`, clarify whether existing attributes (by `attributeId`) or new ones (by `name`+`type`) are intended — the behavior differs.
- File attachments must be pre-uploaded via the file manager; raw file data cannot be passed directly.
- Messenger `typeId` must reference a valid enum value — confirm the correct messenger type before constructing the payload.
x-ai-responding-instructions:
- Warn the user that this endpoint is deprecated and recommend migrating to POST /contacts/create.
- On success, highlight the new contact ID from the returned `data.Contact` object.
- If attributes were created as new (by name), note that they are now persistent CRM attributes shared across contacts.
- Suggest following up with assigning the contact to a deal or pipeline stage as a next logical step.
x-ai-suggestions:
- Use POST /contacts/create for all new contact creation workflows.
- Retrieve valid `responsibleId` values via GET /team before calling this endpoint.
- Retrieve valid tag IDs via GET /contacts/tags before assigning tags.
x-ai-capabilities:
confirmation:
type: Recommended
message: Creating a contact will persist it in the CRM and may trigger automations or assignments.
security_info:
data_handling:
- ResourceStateCreate
- PersonalDataStorage
servers:
- url: https://api.sendpulse.com/crm/v1
/contacts/create:
post:
tags:
- Contacts
summary: Create a new contact
description: Creates a contact
requestBody:
content:
application/json:
schema:
properties:
responsibleId:
type: integer
description: Team member ID to assign to a contact. It can be obtained with the "Get a list of team members" method
firstName:
type: string
description: Contact first name
lastName:
type: string
description: Contact last name
externalContactId:
type: string
description: External contact ID field for services data - we do not recommend using it to add an ID from third-party systems
required:
- responsibleId
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/Contact'
operationId: createContact
x-ai-role: crm_specialist
x-ai-description: Initializes a new contact record in the CRM. A contact is the foundational entity in SendPulse CRM — assigning a responsible team member at creation time ensures immediate ownership and enables automated routing, task assignment, and follow-up pipelines from the first interaction.
x-ai-reasoning-instructions:
- Before creating, verify the responsibleId is valid by cross-referencing with the 'Get a list of team members' endpoint.
- Avoid using externalContactId for third-party system IDs as it is not recommended — suggest alternative approaches if the user intends to map external records.
- If both firstName and lastName are omitted, warn the user that the contact will be anonymous, which may hinder identification later.
- Check whether a contact with the same name or external ID might already exist to prevent duplicates.
x-ai-responding-instructions:
- Confirm creation by surfacing the new contact's ID from the returned Contact object.
- Suggest populating the contact with additional data (phone, email, deals) as an immediate next step.
- If the responsibleId is invalid, explain that the value must come from the team members list and guide the user to retrieve it.
x-ai-suggestions:
- Use 'Get a list of team members' to obtain a valid responsibleId before calling this endpoint.
- After creation, use 'Create a deal' to associate a sales opportunity with the new contact.
- Consider adding tags or custom fields immediately after creation to enrich the contact profile.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ResourceStateUpdate
- PersonalDataStorage
servers:
- url: https://api.sendpulse.com/crm/v1
/contacts/{contactId}:
get:
tags:
- Contacts
summary: Get information about a contact by ID
description: 'Returns the following information on the specified contact: ID, team member responsible for the contact, first and Contacts last name, number of deals of the contact, list of phone numbers and email addresses, and messengers of the contact'
parameters:
- name: contactId
in: path
required: true
description: Contact ID for which you want to get information. It can be obtained with the "Get a list of contacts" method
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/Contact'
operationId: getContactById
x-ai-role: crm_data_analyst
x-ai-description: Retrieves a complete profile of a single CRM contact by their unique ID. This is the primary lookup endpoint for building contact detail views, pre-filling forms before edits, or resolving a contact reference obtained from a list or deal. The response aggregates identity, ownership, communication channels, and deal history into one call — avoiding multiple round-trips.
x-ai-reasoning-instructions:
- Ensure the contactId was obtained from a trusted source such as `getContacts` or a deal's contact reference — do not guess or construct IDs.
- If the previous call returned a list, extract the correct ID before calling this endpoint.
- Check whether the caller needs only basic identity info or full channel data; this endpoint returns both, so no supplemental calls are needed.
- If the response is needed to pre-fill an edit form, cache it locally to avoid redundant requests.
x-ai-responding-instructions:
- Present the contact's full name, responsible team member, and contact channels (phone, email, messengers) in a structured, readable format.
- Highlight the number of associated deals to give the user a quick sense of the contact's activity level.
- If the contact has multiple phone numbers or emails, list all of them clearly — do not omit secondary entries.
- Suggest logical next steps such as updating the contact, viewing associated deals, or initiating communication.
x-ai-suggestions:
- Use `getContacts` first to search by name or email and obtain the contactId.
- After retrieving the contact, you can update their data with the corresponding PATCH /contacts/{contactId} endpoint.
- To see deals linked to this contact, query the deals endpoint filtered by this contactId.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
put:
tags:
- Contacts
summary: Update information about the contact
description: Update information about specified contact
parameters:
- name: contactId
in: path
required: true
description: Contact ID of the contact whose information you want to update. It can be obtained with the "Get a list of contacts" method
schema:
type: integer
requestBody:
content:
application/json:
schema:
properties:
responsibleId:
type: integer
description: Team member ID to assign to a contact. It can be obtained with the "Get a list of team members" method
firstName:
type: string
description: Contact first name
lastName:
type: string
description: Contact last name
required:
- responsibleId
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/Contact'
operationId: updateContact
x-ai-role: crm_data_steward
x-ai-description: Updates mutable fields of an existing CRM contact record. This is the primary mutation endpoint for keeping contact profiles accurate — ownership reassignment (responsibleId) is mandatory, making it suitable for both data corrections and responsibility handoffs between team members.
x-ai-reasoning-instructions:
- Retrieve the contactId first via 'Get a list of contacts' if not already known — never guess or fabricate IDs.
- responsibleId is required; confirm the target team member exists via 'Get a list of team members' before calling.
- If only name fields are changing, still supply the current responsibleId to avoid unintended ownership transfer.
- Warn the user if they are reassigning a contact to a different team member, as this affects pipeline visibility and notifications.
x-ai-responding-instructions:
- Confirm which fields were updated and reflect the new values back to the user.
- If responsibleId changed, explicitly mention the ownership transfer and to whom.
- Suggest fetching the updated contact via 'Get contact details' to verify the full record state.
- On 404, clarify that the contactId may be invalid or the contact may have been deleted.
x-ai-suggestions:
- Use 'Get a list of team members' to resolve a name to a valid responsibleId before calling.
- Combine with 'Get a list of contacts' to batch-update contacts by segment.
x-ai-capabilities:
confirmation:
type: Recommended
message: Confirm before reassigning contact ownership, as it affects team workload distribution.
security_info:
data_handling:
- ResourceStateUpdate
delete:
tags:
- Contacts
summary: Remove contact by ID
description: Removes the specified contact by ID
parameters:
- name: contactId
in: path
required: true
description: Contact ID to be removed. It can be obtained with the "Get a list of contacts" method
schema:
type: integer
responses:
'204':
description: Successfully deleted
operationId: deleteContactById
x-ai-role: crm_data_steward
x-ai-description: Permanently removes a contact record from the system by its unique identifier. This is a hard-delete operation — the contact and all associated data (tags, custom fields, activity history) are irreversibly erased. Use when a contact explicitly opts out under GDPR/CCPA or when cleaning up test/duplicate records.
x-ai-reasoning-instructions:
- Before deleting, confirm with the user that this is intentional — deletion is irreversible and cannot be undone.
- Verify the contactId exists by calling the 'Get a list of contacts' method if the ID was not obtained in the current session.
- Check whether the contact is currently enrolled in active automations or campaigns — deletion mid-flow may cause broken sequences.
- If the intent is GDPR/CCPA erasure, ensure this call is part of a broader data-removal workflow (e.g., also remove from mailing lists).
x-ai-responding-instructions:
- Confirm deletion with the contactId that was removed.
- Remind the user that this action is permanent and the contact cannot be restored.
- If the use case is compliance-driven, suggest verifying removal across all related resources (lists, automations, CRM deals).
- On 404, clarify that the contact may have already been deleted or the ID is incorrect.
x-ai-capabilities:
confirmation:
type: Required
message: 'This will permanently delete contact #{contactId}. This action cannot be undone.'
security_info:
data_handling:
- IrreversibleDelete
- PiiDataRemoval
servers:
- url: https://api.sendpulse.com/crm/v1
/contacts/{contactId}/deals:
get:
tags:
- Contacts
summary: Get all deals that related to contact
parameters:
- name: contactId
in: path
required: true
schema:
type: integer
responses:
'200':
description: deals list
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/Deal'
operationId: getContactDeals
x-ai-role: crm_sales_analyst
x-ai-description: Retrieves the full list of deals associated with a specific contact, providing a 360-degree view of the sales relationship. Use this to assess pipeline health for an individual contact, identify stalled deals, or understand a contact's purchase history before outreach.
x-ai-reasoning-instructions:
- Verify the contactId is valid before calling — an incorrect ID returns an empty dataset or 404, not an error.
- Consider whether the user wants all deals or a filtered subset; this endpoint returns all, so post-filter by status if needed.
- If the result set is empty, distinguish between 'contact exists but has no deals' and 'contact not found' scenarios for the user.
x-ai-responding-instructions:
- Summarize the deals by status (e.g., open, won, lost) rather than listing raw data.
- Highlight any deals in critical stages (e.g., negotiation, closing) that may require immediate action.
- If no deals are found, suggest creating a deal with the relevant create-deal endpoint.
x-ai-suggestions:
- Use the returned deal IDs to fetch individual deal details or update deal stages.
- Cross-reference with contact activity to prioritize follow-ups on stalled deals.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
servers:
- url: https://api.sendpulse.com/crm/v1
/contacts/{contactId}/comments:
post:
tags:
- Contacts
summary: Add a note to a contact
description: Adds a note to the specified contact
parameters:
- name: contactId
in: path
required: true
description: Contact ID to which you want to add a note. It can be obtained with the "Get a list of contacts" method
schema:
type: integer
requestBody:
content:
application/json:
schema:
properties:
message:
type: string
minLength: 1
description: Note message. The maximum number of characters is 65,535
required:
- message
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/ContactComment'
operationId: addContactComment
x-ai-role: crm_relationship_manager
x-ai-description: Adds a persistent internal note to a specific CRM contact. Notes serve as a chronological communication log visible only to team members — not the contact — enabling context sharing between agents, support staff, and sales reps across interactions.
x-ai-reasoning-instructions:
- Verify the contactId is valid before submitting — use 'Get a list of contacts' if the ID is uncertain.
- Notes are internal only; never use this endpoint to send a message to the contact.
- Ensure the message is meaningful and actionable — generic notes reduce CRM signal quality.
- Check that the message lengt
# --- truncated at 32 KB (236 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendpulse/refs/heads/main/openapi/sendpulse-contacts-api-openapi.yml