Keap Contacts API
Keap Contact API — 27 operations across 16 paths on the Keap REST v2 contract, read from Keap's own published OpenAPI 3.1 document.
OpenAPI Specification
openapi: 3.1.0
info:
title: Keap Contact API
description: Keap Public API Documentation
termsOfService: https://www.thryv.com/terms-of-use
contact:
name: Keap
url: https://developer.keap.com/get-support
email: api.keap@thryv.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: v2
servers:
- url: https://api.infusionsoft.com/crm
tags:
- name: Contact
paths:
/rest/v2/contacts:
get:
tags:
- Contact
summary: List Contacts
description: Retrieves a list of Contacts
operationId: listContacts
parameters:
- name: filter
in: query
description: "Filter to apply, allowed fields are:\n- (String) `email` — supports wildcard (e.g.\
\ `email==john*`)\n- (String) `given_name` — supports wildcard (e.g. `given_name==Mar*`)\n-\
\ (String) `family_name` — supports wildcard (e.g. `family_name==Smi*`)\n- (String) `middle_name`\
\ — supports wildcard (e.g. `middle_name==J*`)\n- (String) `company_id`\n- (Set[String]) `contact_ids`\n\
- (Set[String]) `ids` — accepts a list of contact IDs (e.g. `ids==1,2,3`)\n- (String) `start_update_time`\n\
- (String) `end_update_time`\n- (String) `phone_number` — the phone number to search for. Requires\
\ `phone_fields` to be specified; only the specified phone fields are searched.\n- (Set[String])\
\ `phone_fields` — restricts which phone fields to search (e.g. PHONE1, PHONE2, or comma-separated\
\ list PHONE1,PHONE2,PHONE3,PHONE4,PHONE5). Required when `phone_number` is supplied.\n- (String)\
\ `billing_address_line1`\n- (String) `billing_address_locality`\n- (String) `billing_address_region`\
\ (long-form region/state name, e.g. \"Arizona\")\n- (String) `billing_address_postal_code`\n\
- (String) `billing_address_country_code` (ISO 3166-1 alpha-3, e.g. \"USA\")\n- (String) `shipping_address_line1`\n\
- (String) `shipping_address_locality`\n- (String) `shipping_address_region`\n- (String) `shipping_address_postal_code`\n\
- (String) `shipping_address_country_code`\n- (String) `other_address_line1`\n- (String) `other_address_locality`\n\
- (String) `other_address_region`\n- (String) `other_address_postal_code`\n- (String) `other_address_country_code`\n\
- (String) `city` — primary-address city (Contact.City); supports prefix wildcard (e.g. `city==Chan*`,\
\ \"starts with\")\n- (String) `state` — primary-address state/region (Contact.State); supports\
\ prefix wildcard (e.g. `state==Ar*`, \"starts with\")\n- (String) `website` — supports wildcard\
\ (e.g. `website==https://example*`)\n- (String) `lead_source_name` — supports wildcard (e.g.\
\ `lead_source_name==Google*`)\n- (String) `contact_id` — supports comparison operators: `==`,\
\ `>`, `<`, `>=`, `<=`\n(e.g. `contact_id>5` encoded as `contact_id%3E5`)\nCustom fields can\
\ be filtered by their field_name (case-insensitive, as returned\nby GET /v2/contacts/model).\
\ A standard field above takes precedence over a custom\nfield with the same name. The supported\
\ operators depend on the custom field's type:\n- Text-like fields (text, text area, name, email,\
\ phone, website, social security\n number) and single-value choice fields with text options\
\ (dropdown, radio,\n state): `==` only, with optional trailing wildcard (e.g. `firstName1%3D%3DValue%2A`)\n\
- Yes/No and drilldown fields: `==` only\n- Numeric fields (whole number, decimal, currency,\
\ percent, year, month, day of\n week, user): `==`, `>`, `<`, `>=`, `<=`\n- Date fields: `==`,\
\ `>`, `<`, `>=`, `<=`; the value must be a full ISO-8601 date-time with milliseconds and a\
\ timezone offset (e.g. `2026-01-01T00:00:00.000Z`), the same format as `start_update_time`/`end_update_time`.\
\ Date-only values such as `2026-01-01` are rejected\n- Multi-select fields: `==` matches records\
\ that contain the given option\nCustom field filtering on non-indexed fields is supported but\
\ may be slower.\n\nYou will need to apply the `==` operator to check the equality of one of\
\ the filters with your searched\nword, in the encoded form `%3D%3D`.\nFor wildcard filtering,\
\ use `*` at the end of the value (prefix matching), encoded as `%2A`.\nFor the filters listed\
\ above, here are some examples:\n- `filter=given_name%3D%3DMary`\n- `filter=given_name%3D%3DMar%2A`\
\ (wildcard: starts with \"Mar\")\n- `filter=company_id%3D%3D123`\n- `filter=company_id%3D%3D123%3Bfamily_name%3D%3DSmith`\n\
- `filter=billing_address_locality%3D%3DChandler`\n- `filter=city%3D%3DChandler` (city exact\
\ match)\n- `filter=city%3D%3DChan%2A` (city prefix wildcard: starts with \"Chan\")\n- `filter=city%3D%3DChandler%3Bstate%3D%3DArizona`\
\ (combined city + state filter)\n- `filter=shipping_address_country_code%3D%3DUSA%3Bshipping_address_region%3D%3DArizona`\n\
- `filter=contact_id%3E5` (contact_id > 5)\n- `filter=ids%3D%3D1,2,3` (contacts with IDs 1,\
\ 2, or 3)\n\nCustom field examples (for custom fields with field_name `firstName1` and `Score0`):\n\
- `filter=firstName1%3D%3DJohn` (custom field exact match)\n- `filter=firstName1%3D%3DJo%2A`\
\ (custom field prefix wildcard)\n- `filter=Score0%3E100` (custom field numeric comparison)\n\
- `filter=given_name%3D%3DJohn%3BStatus0%3D%3DActive` (combined standard + custom field filter)\n"
required: false
schema:
type: string
- name: page_token
in: query
description: Page token
required: false
schema:
type: string
- name: order_by
in: query
description: 'Attribute and direction to order items.
One of the following fields:
- `id`
- `create_time`
- `email`
- `update_time`
One of the following directions:
- `asc`
- `desc`'
required: false
schema:
type: string
- name: page_size
in: query
description: Total number of items to return per page
required: false
schema:
type: integer
format: int32
maximum: 1000
minimum: 0
example: 0
- name: fields
in: query
description: 'Comma-delimited list of Contact properties to include in the response. (Available
fields are: addresses,anniversary_date,birth_date,company,contact_type,create_time,
custom_fields,email_addresses,family_name,fax_numbers,given_name,id,job_title,leadsource_id,
links,middle_name,notes,origin,owner_id,phone_numbers,preferred_locale,preferred_name,prefix,
referral_code,score_value,social_accounts,source_type,spouse_name,suffix,tag_ids,time_zone,
update_time,utm_parameters,website,account_id,assistant_name,assistant_phone,
billing_information,created_by,groups,last_updated_by)'
schema:
type: string
responses:
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'501':
description: Method Not Implemented
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListContactsResponse'
post:
tags:
- Contact
summary: Create a Contact
description: 'Creates a new Contact.
*Note:* Contact must contain at least one item in `email_addresses`, `phone_numbers`, or `addresses`
and `country_code` is required if `region` is specified.
Optionally accepts a `duplicate_option` query parameter which performs duplicate checking by one
of the following options: `Email`, `EmailAndName`, `EmailAndNameAndCompany`. If a match is found
using the option provided, the existing contact will be updated. If an existing contact was not
found using the `duplicate_option` provided, a new contact record will be created. When `duplicate_option`
is not specified, a new contact is always created.'
operationId: createContact
parameters:
- name: duplicate_option
in: query
description: Duplicate check strategy. If provided, performs duplicate checking and updates the
existing contact if a match is found.
required: false
schema:
type: string
enum:
- Email
- EmailAndName
- EmailAndNameAndCompany
- name: fields
in: query
description: 'Comma-delimited list of Contact properties to include in the response. (Available
fields are: addresses,anniversary_date,birth_date,company,contact_type,create_time,
custom_fields,email_addresses,family_name,fax_numbers,given_name,id,job_title,leadsource_id,
links,middle_name,notes,origin,owner_id,phone_numbers,preferred_locale,preferred_name,prefix,
referral_code,score_value,social_accounts,source_type,spouse_name,suffix,tag_ids,time_zone,
update_time,utm_parameters,website,account_id,assistant_name,assistant_phone,
billing_information,created_by,groups,last_updated_by)'
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUpdateContactRequest'
required: true
responses:
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'501':
description: Method Not Implemented
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'200':
description: OK - existing contact updated
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'201':
description: Created - new contact created
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
/rest/v2/contacts:unlink:
post:
tags:
- Contact
summary: Delete Link between two Contacts
description: Deletes Link between two Contacts
operationId: unlinkContacts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LinkContactsRequest'
required: true
responses:
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'501':
description: Method Not Implemented
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'204':
description: No Content
/rest/v2/contacts:merge:
post:
tags:
- Contact
summary: Merge two Contacts
description: Merges two Contacts together. The duplicate contact will be merged into the primary
contact.
operationId: mergeContacts
parameters:
- name: fields
in: query
description: 'Comma-delimited list of Contact properties to include in the response. (Available
fields are: addresses,anniversary_date,birth_date,company,contact_type,create_time,
custom_fields,email_addresses,family_name,fax_numbers,given_name,id,job_title,leadsource_id,
links,middle_name,notes,origin,owner_id,phone_numbers,preferred_locale,preferred_name,prefix,
referral_code,score_value,social_accounts,source_type,spouse_name,suffix,tag_ids,time_zone,
update_time,utm_parameters,website,account_id,assistant_name,assistant_phone,
billing_information,created_by,groups,last_updated_by)'
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MergeContactRequest'
required: true
responses:
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'501':
description: Method Not Implemented
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
/rest/v2/contacts:link:
post:
tags:
- Contact
summary: Link Contacts
description: Links two Contacts together using the provided Link type
operationId: linkContacts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LinkContactsRequest'
required: true
responses:
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'501':
description: Method Not Implemented
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/ContactLink'
/rest/v2/contacts/model/customFields:
post:
tags:
- Contact
summary: Create a Contact Custom Field
description: Creates a custom field of the specified type and options to the Contact object
operationId: createContactCustomField
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomFieldRequest'
required: true
responses:
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'501':
description: Method Not Implemented
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldMetaData'
/rest/v2/contacts/model/customFields/tabs:
get:
tags:
- Contact
summary: List Contact Custom Field Tabs
description: Retrieves a list of custom field tabs for the Contact record type.
operationId: listContactCustomFieldTabs
responses:
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'501':
description: Method Not Implemented
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListCustomFieldTabsResponse'
post:
tags:
- Contact
summary: Create a Contact Custom Field Tab
description: Creates a new custom field tab for the Contact record type.
operationId: createContactCustomFieldTab
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomFieldTabRequest'
required: true
responses:
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'501':
description: Method Not Implemented
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldTab'
/rest/v2/contacts/model/customFields/groups:
get:
tags:
- Contact
summary: List Contact Custom Field Groups
description: Retrieves a list of custom field groups for the Contact record type. Optionally filter
by tab_id to scope to a specific tab.
operationId: listContactCustomFieldGroups
parameters:
- name: tab_id
in: query
description: Optional tab id to scope groups to a single tab
required: false
schema:
type: string
responses:
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'501':
description: Method Not Implemented
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListCustomFieldGroupsResponse'
post:
tags:
- Contact
summary: Create a Contact Custom Field Group
description: Creates a new custom field group for the Contact record type. If `tab_id` is omitted,
the group is added to the default 'Custom Fields' tab.
operationId: createContactCustomFieldGroup
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomFieldGroupRequest'
required: true
responses:
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'501':
description: Method Not Implemented
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldGroup'
/rest/v2/contacts/links/types:
get:
tags:
- Contact
summary: List Contact Link types
description: Retrieves a list of Contact Link types.
operationId: listContactLinkTypes
parameters:
- name: filter
in: query
description: 'Filter to apply, allowed fields are:
- (String) `name`
You will need to apply the `==` operator to check the equality of one of the filters with your
searched
word, in the encoded form `%3D%3D`. For the filters listed above, here are some examples:
- `filter=name%3D%3DexpectedValue`
'
required: false
schema:
type: string
- name: page_token
in: query
description: Page token
required: false
schema:
type: string
- name: order_by
in: query
description: 'Attribute and direction to order items.
One of the following fields:
- `name`
- `max_links`
- `create_time`
One of the following directions:
- `asc`
- `desc`
'
required: false
schema:
type: string
- name: page_size
in: query
description: Total number of items to return per page
required: false
schema:
type: integer
format: int32
maximum: 1000
minimum: 0
example: 0
responses:
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'501':
description: Method Not Implemented
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListContactLinkTypesResponse'
post:
tags:
- Contact
summary: Create a Contact Link type
description: Creates a new type of Contact Link
operationId: createContactLinkType
requestBody:
content:
application/json:
# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/keap/refs/heads/main/openapi/keap-contact-api-openapi.yml