# Contacts

Keep customer profiles, tags, custom fields, and imports in sync.

39 operations in the Contacts resource group.

## Operations

- [Create contact](/api/reference/contacts/create-contact.md) - POST `/contacts` - Creates a customer profile that can be matched to messages and events.
- [Search contacts](/api/reference/contacts/search-contacts.md) - POST `/contacts/search` - Returns contact summaries matching one canonical conjunction of filter conditions.
- [Count contacts](/api/reference/contacts/get-contacts-count.md) - GET `/contacts/count` - Returns the tenant's contact count for a navigation/dashboard badge. This is independent
of any list filters; the archived query parameter selects which bucket to count.
- [Get contact by ID](/api/reference/contacts/get-contact.md) - GET `/contacts/{id}` - Returns one customer profile with conversations, tags, custom fields, and archive state.
- [Update contact](/api/reference/contacts/update-contact.md) - PATCH `/contacts/{id}` - Updates mutable contact fields. Fields omitted from the body are left unchanged.
- [Delete contact](/api/reference/contacts/delete-contact.md) - DELETE `/contacts/{id}` - Soft deletes a contact. Use archive when you only want to hide the contact from active lists.
- [Import contacts from CSV](/api/reference/contacts/import-contacts.md) - POST `/contacts/import` - Uploads a CSV file and starts a background contact import. Poll the returned import ID
to review completion counts and row-level errors.
- [Get import status](/api/reference/contacts/get-import-status.md) - GET `/contacts/imports/{id}` - Returns progress and row-level failures for a contact import.
- [Archive contact](/api/reference/contacts/archive-contact.md) - POST `/contacts/{id}/archive` - Hides a contact from active lists without deleting its history.
- [Unarchive contact](/api/reference/contacts/unarchive-contact.md) - POST `/contacts/{id}/unarchive` - Restores an archived contact to active lists.
- [Set contact field value](/api/reference/contacts/set-contact-custom-field-value.md) - PUT `/contacts/{contactId}/custom-fields/{customFieldId}` - Sets or clears one custom field value on a contact. Send an empty string to clear
the value while keeping the field definition available for future use.
- [Add tag to contact](/api/reference/contacts/tag-contact.md) - POST `/contacts/{contactId}/tags/{tagId}` - Adds a label to the contact for segmentation, routing, or reporting.
- [Remove tag from contact](/api/reference/contacts/untag-contact.md) - DELETE `/contacts/{contactId}/tags/{tagId}` - Removes a label from the contact.
- [List saved contact segments](/api/reference/contacts/list-segments.md) - GET `/segments` - Returns tenant-scoped saved contact filters without evaluating member counts.
- [Create a saved contact segment](/api/reference/contacts/create-segment.md) - POST `/segments`
- [Get a saved contact segment](/api/reference/contacts/get-segment.md) - GET `/segments/{segmentId}`
- [Update a saved contact segment](/api/reference/contacts/update-segment.md) - PATCH `/segments/{segmentId}` - Replaces any supplied filter atomically. The If-Match header must contain the current segment ETag.
- [Delete a saved contact segment](/api/reference/contacts/delete-segment.md) - DELETE `/segments/{segmentId}`
- [Search contacts matching a saved segment](/api/reference/contacts/search-segment-contacts.md) - POST `/segments/{segmentId}/contacts/search` - Applies the current saved definition and any temporary filters using AND semantics.
- [List campaigns](/api/reference/contacts/list-campaigns.md) - GET `/campaigns`
- [Create a draft campaign](/api/reference/contacts/create-campaign.md) - POST `/campaigns`
- [Get a campaign](/api/reference/contacts/get-campaign.md) - GET `/campaigns/{campaignId}`
- [Update a draft campaign](/api/reference/contacts/update-campaign.md) - PATCH `/campaigns/{campaignId}` - Only draft campaigns are editable. If-Match is optional; when supplied, it must contain the current campaign ETag.
- [Delete a draft or sent campaign](/api/reference/contacts/delete-campaign.md) - DELETE `/campaigns/{campaignId}` - Soft-deletes a draft or sent campaign from the campaign library. Scheduled campaigns must be unscheduled first. If-Match is optional.
- [Schedule a draft campaign](/api/reference/contacts/schedule-campaign.md) - POST `/campaigns/{campaignId}/schedule` - Set sendAt to now to dispatch immediately, or supply an RFC 3339 timestamp. If-Match is optional.
- [Return a scheduled campaign to draft](/api/reference/contacts/unschedule-campaign.md) - POST `/campaigns/{campaignId}/unschedule` - If-Match is optional. A campaign cannot be unscheduled after dispatch starts.
- [List campaign recipients](/api/reference/contacts/list-campaign-recipients.md) - GET `/campaigns/{campaignId}/recipients`
- [Get campaign delivery analytics](/api/reference/contacts/get-campaign-analytics.md) - GET `/campaigns/{campaignId}/analytics`
- [List tags](/api/reference/contacts/list-tags.md) - GET `/tags` - Returns the labels available for organizing contacts.
- [Create tag](/api/reference/contacts/create-tag.md) - POST `/tags` - Creates a label that can be attached to contacts.
- [Delete tag](/api/reference/contacts/delete-tag.md) - DELETE `/tags/{id}`
- [List contact field definitions](/api/reference/contacts/list-contact-field-definitions.md) - GET `/contacts/custom-fields` - Returns the reusable custom fields that can store structured customer context on
contacts, such as lifecycle stage, preferred store, or renewal date.
- [Create contact field definition](/api/reference/contacts/create-contact-field-definition.md) - POST `/contacts/custom-fields` - Creates a reusable custom field for storing customer context on contacts.
- [Update contact field definition](/api/reference/contacts/update-contact-field-definition.md) - PATCH `/contacts/custom-fields/{id}` - Renames a contact field definition.
- [Delete contact field definition](/api/reference/contacts/delete-contact-field-definition.md) - DELETE `/contacts/custom-fields/{id}` - Deletes a contact field definition that is no longer needed.
- [List property field definitions](/api/reference/contacts/list-property-field-definitions.md) - GET `/properties/custom-fields` - Returns the reusable custom fields that can store structured context on property
records, such as region, tier, or renewal date.
- [Create property field definition](/api/reference/contacts/create-property-field-definition.md) - POST `/properties/custom-fields` - Creates a reusable custom field for storing context on property records.
- [Update property field definition](/api/reference/contacts/update-property-field-definition.md) - PATCH `/properties/custom-fields/{id}` - Renames a property field definition.
- [Delete property field definition](/api/reference/contacts/delete-property-field-definition.md) - DELETE `/properties/custom-fields/{id}` - Deletes a property field definition that is no longer needed.

## Schemas

- [ProblemDetails](/api/reference/schemas/problem-details.md) - object - RFC 9457 Problem Details response with a stable Flownally error code.
- [FieldViolation](/api/reference/schemas/field-violation.md) - object
- [Window](/api/reference/schemas/messaging-window.md) - object - Tells a client whether the current actor can send in this conversation right now.
- [OutboundMessageContent](/api/reference/schemas/outbound-message-content.md) - object - Message body accepted by send operations.
- [TextMessageContent](/api/reference/schemas/text-message-content.md) - object - Plain text message content.
- [TextContent](/api/reference/schemas/text-content.md) - object - Plain text body.
- [MessageContent](/api/reference/schemas/media-message-content.md) - object - Media message content. Upload with `/media/uploads` first, then pass the returned `mediaId`.
- [Content](/api/reference/schemas/media-content.md) - object - Canonical media reference and optional presentation details. Use `GET /media/{mediaId}`
to retrieve media bytes through an authorized download URL.
- [TemplateMessageContent](/api/reference/schemas/template-message-content.md) - object - WhatsApp template message content. The gateway maps this to the channel-specific send internally.
- [WhatsAppTemplateContent](/api/reference/schemas/whats-app-template-content.md) - object
- [TemplateComponent](/api/reference/schemas/template-component.md) - object
- [TemplateParameter](/api/reference/schemas/template-parameter.md) - object
- [Parameter](/api/reference/schemas/media-parameter.md) - object
- [CurrencyParameter](/api/reference/schemas/currency-parameter.md) - object
- [DateTimeParameter](/api/reference/schemas/date-time-parameter.md) - object
- [RichMessageContent](/api/reference/schemas/rich-message-content.md) - object - Structured rich message content for channels that support cards or actions.
- [RichMessage](/api/reference/schemas/rich-message.md) - object
- [Card](/api/reference/schemas/card.md) - object
- [CardHeader](/api/reference/schemas/card-header.md) - object
- [CardBody](/api/reference/schemas/card-body.md) - object
- [CardFooter](/api/reference/schemas/card-footer.md) - object
- [CardAction](/api/reference/schemas/card-action.md) - object
- [WhatsAppFlowAction](/api/reference/schemas/whats-app-flow-action.md) - object
- [WhatsAppMessageContent](/api/reference/schemas/whats-app-message-content.md) - object - WhatsApp-specific message content.
- [WhatsAppContent](/api/reference/schemas/whats-app-content.md) - object - WhatsApp-only message features.
- [WhatsAppRequestContactInfoContent](/api/reference/schemas/whats-app-request-contact-info-content.md) - object - WhatsApp interactive request for the user to share their phone number.
- [CreateContactRequest](/api/reference/schemas/create-contact-request.md) - object - Contact fields to create. Add custom fields after defining them in Flownally.
- [Contact](/api/reference/schemas/contact.md) - object - Customer profile used across messaging, events, and journeys.
- [ContactConversation](/api/reference/schemas/contact-conversation.md) - object - Conversation grouped under a contact.
- [ContactSearchRequest](/api/reference/schemas/contact-search-request.md) - object
- [ContactFilter](/api/reference/schemas/contact-filter.md) - object - A closed match-all filter shared by ad hoc searches and saved segments. The searchText
condition is temporary and is rejected when a filter is persisted as a segment.
- [ContactCondition](/api/reference/schemas/contact-condition.md) - object
- [SearchTextCondition](/api/reference/schemas/search-text-condition.md) - object
- [ArchiveStatusCondition](/api/reference/schemas/archive-status-condition.md) - object
- [ArchiveStatus](/api/reference/schemas/archive-status.md) - enum
- [CreatedAtCondition](/api/reference/schemas/created-at-condition.md) - object
- [FirstSeenCondition](/api/reference/schemas/first-seen-condition.md) - object
- [LastInteractionCondition](/api/reference/schemas/last-interaction-condition.md) - object
- [ChatCountCondition](/api/reference/schemas/chat-count-condition.md) - object
- [EngagementWindow](/api/reference/schemas/engagement-window.md) - object
- [CustomFieldTextCondition](/api/reference/schemas/custom-field-text-condition.md) - object
- [CustomFieldDateCondition](/api/reference/schemas/custom-field-date-condition.md) - object
- [HasAnyTagCondition](/api/reference/schemas/has-any-tag-condition.md) - object
- [HasAnyChannelCondition](/api/reference/schemas/has-any-channel-condition.md) - object
- [ContactChannel](/api/reference/schemas/contact-channel.md) - enum
- [ContactSort](/api/reference/schemas/contact-sort.md) - object
- [ContactSummarySort](/api/reference/schemas/contact-summary-sort.md) - enum
- [SortDirection](/api/reference/schemas/sort-direction.md) - enum
- [ContactSummariesResponse](/api/reference/schemas/contact-summaries-response.md) - object
- [ContactSummary](/api/reference/schemas/contact-summary.md) - object
- [ContactSummaryTag](/api/reference/schemas/contact-summary-tag.md) - object
- [CountResponse](/api/reference/schemas/contacts-count-response.md) - object
- [UpdateContactRequest](/api/reference/schemas/update-contact-request.md) - object
- [ImportContactsResponse](/api/reference/schemas/import-contacts-response.md) - object - Accepted contact import job.
- [ImportStatus](/api/reference/schemas/import-status.md) - object - Progress and results for a contact import.
- [ImportError](/api/reference/schemas/import-error.md) - object
- [SetContactCustomFieldValueRequest](/api/reference/schemas/set-contact-custom-field-value-request.md) - object - Value to store on a contact. Send an empty string to clear the value.
- [SegmentsResponse](/api/reference/schemas/segments-response.md) - object
- [Segment](/api/reference/schemas/segment.md) - object
- [CreateSegmentRequest](/api/reference/schemas/create-segment-request.md) - object
- [UpdateSegmentRequest](/api/reference/schemas/update-segment-request.md) - object
- [SegmentContactSearchRequest](/api/reference/schemas/segment-contact-search-request.md) - object
- [CampaignStatus](/api/reference/schemas/campaign-status.md) - enum
- [CampaignsResponse](/api/reference/schemas/campaigns-response.md) - object
- [Campaign](/api/reference/schemas/campaign.md) - object
- [CreateCampaignRequest](/api/reference/schemas/create-campaign-request.md) - object
- [UpdateCampaignRequest](/api/reference/schemas/update-campaign-request.md) - object
- [ScheduleCampaignRequest](/api/reference/schemas/schedule-campaign-request.md) - object
- [CampaignRecipientStatus](/api/reference/schemas/campaign-recipient-status.md) - enum
- [CampaignRecipientsResponse](/api/reference/schemas/campaign-recipients-response.md) - object
- [CampaignRecipient](/api/reference/schemas/campaign-recipient.md) - object
- [CampaignRecipientSnapshot](/api/reference/schemas/campaign-recipient-snapshot.md) - object - Immutable contact presentation data captured with the final campaign audience.
- [CampaignAnalytics](/api/reference/schemas/campaign-analytics.md) - object
- [TagsResponse](/api/reference/schemas/tags-response.md) - object
- [Tag](/api/reference/schemas/tag.md) - object - Label used to segment and organize contacts.
- [CreateTagRequest](/api/reference/schemas/create-tag-request.md) - object - Tag to create.
- [CustomFieldDefinitionsResponse](/api/reference/schemas/custom-field-definitions-response.md) - object - Reusable custom field definitions for one resource type.
- [CustomFieldDefinition](/api/reference/schemas/custom-field-definition.md) - object - Defines a reusable custom field for either contacts or property records. Values are stored
separately on each resource.
- [CreateCustomFieldDefinitionRequest](/api/reference/schemas/create-custom-field-definition-request.md) - object - Field definition to create for the resource collection in the URL.
- [UpdateCustomFieldDefinitionRequest](/api/reference/schemas/update-custom-field-definition-request.md) - object - New name for an existing field definition.