Creating Contacts via a Webhook

Overview

You can connect external sources (such as lead generation platforms, marketing tools, or website forms) to automatically create new contacts in Swivel. This integration sends contact data into Swivel, ensuring that new leads or signups are captured in your CRM without manual entry.

When the contact is created, Swivel replies with the new contact’s ID, like this:

{"id": "3f0c1b2a-9d4e-4c7f-8a21-5b6d7e8f9a01"}

Your provider should save that ID. It is needed later to update the same contact.

This guide walks you through how to set up these connections so contacts are created seamlessly from outside systems.

Generate an API Key in Swivel

Swivel uses an API key to securely receive lead data from external sources.

1. Log in to Swivel as an owner.
2. Navigate to Settings → API Keys.
3. Select + New API Key on the top right of the page
4. Enter the desired name to help identify the key in the API Key Name field.
5. Select the Generate API Key button
6. Hover over the key and select the Copy button to copy the key to your clipboard.

Caution

🔍 Tip: Treat your API key like a password. Do not share it publicly or in unsecured documents.

Connect Swivel to the Contact Source

If your lead source sends data via a webhook:

1. Open your lead source’s integration settings.

2. Paste your CRM API key when asked for authentication.

   1. Use x-api-key as the header key name.

3. Use a POST request to the following endpoint URL:
   ​**https://swivelcrm.io/api/webhook/v1/contacts**

4. Define the data to send in the request body by using the available parameter keys from our Swivel Supported Fields table below. The endpoint accepts JSON and form-urlencoded data.

5. Test the webhook with a sample lead submission.

Supported Fields

Swivel Field	Parameter Key	Important Notes About Values
Id	id	This id is randomly generated in Swivel when the contact is created via the webhook. To allow for your contact to update via the webhook, this ID must be included. See this page for more details.
First Name	first_name	Required. The contact will not be created without it. Both First Name and Last Name must be provided.
Middle Name	middle_name
Last Name	last_name	Required. The contact will not be created without it. Both First Name and Last Name must be provided.
Suffix	suffix	Must be a Swivel-supported suffix: “Jr.”, “Sr.”, “I”, “II”, “III”, “IV” Include the full stop on Jr. and Sr. (“Jr” on its own is not recognized.) Capitalization does not matter.
Salutation	salutation
Nickname	nickname
Marital Status	marital_status	Swivel supports the following marital statuses: single, married, divorced, separated, domestic_partnership, widowed Note the underscore in domestic_partnership. Written as two separate words it will not be recognised and the field will be left blank.
Marital Status Effective Date	marital_status_on	Must be one of the following formats: • MM/DD/YYYY • MM-DD-YYYY
Birthdate	birthdate	Must be one of the following formats: • MM/DD/YYYY • MM-DD-YYYY
Gender	gender	Swivel only supports male or female If the gender is not supported by Swivel, the field will be left blank on the contact.
SSN	ssn
Medicare Number	medicare_number
Deceased	deceased	Send true or false. Leaving the field blank, or sending false or 0, leaves the contact unmarked. Any other value (including the word “no”) will mark the contact. Make sure your source sends true and false rather than words like yes and no. If a contact has been marked by mistake, only sending false will un-mark them. Sending a blank value leaves the mark in place.
Date of Death	death_date	Must be one of the following formats: • MM/DD/YYYY • MM-DD-YYYY
Job Title	job_title
Do Not Contact	do_not_contact	Send true or false. Leaving the field blank, or sending false or 0, leaves the contact unmarked. Any other value (including the word “no”) will mark the contact. Make sure your source sends true and false rather than words like yes and no. If a contact has been marked by mistake, only sending false will un-mark them. Sending a blank value leaves the mark in place.
Client Since	client_since	Must be one of the following formats: • MM/DD/YYYY • MM-DD-YYYY
Personal Note	personal_note
County	county
Email Address	email
Phone Number	phone_number
Address Line1	address_line1
Address Line2	address_line2
City	city
State	postal_state	Must be the standardized 2 letter state abbreviation
Zip Code	postal_code
Country	country
Contact Category	contact_category	If included, we will look for an existing contact category match in Swivel or create a new one with the category provided. If no contact category is provided, then the category will default to Unspecified
Contact Status	contact_status	If included, we will look for an existing contact status match in Swivel or create a new one with the status provided If no contact status is provided, then the status will default to New
Contact Type	contact_type	If included, we will look for an existing contact type match in Swivel or create a new one with the type provided If no contact type is provided, then the type will default to Individual
Lead Source	lead_source	If one is included, we will look for an existing matching record or create a new one with the lead source provided
Office	office	If one is included, we will look for an existing matching record or create a new one with the office provided
Campaign	campaign_name	Campaign name and/or event name is required for any campaign- and event-specific fields. If no campaign name is provided, Swivel will create one that matches the event name.
Event	event_name	Campaign name and/or event name is required for any campaign- and event-specific fields. If no event name is provided, Swivel will create one that matches the campaign name, and it will create a new event for every contact sent this way. To keep contacts together on a single event, always send an event name or a Marketing Event Source Key as well as the campaign name.
Campaign Type	campaign_type	If included, we will look for a campaign type match in Swivel or create a new one with the campaign type provided. If no campaign type is provided, then it will default to Unspecified.
Campaign Source Key	campaign_source_key	Uniquely identify campaigns with external key. Helps users that have potential campaigns with the same name.
Marketing Event Source Key	marketing_event_source_key	Uniquely identify marketing events with external key Helps users that have potential events with the same name.
Marketing Event Type	marketing_event_type	If included, we will look for an event type match in Swivel or create a new one with the event type provided. If no event type is provided, then it will default to Unspecified.
Assigned to	assigned_to	Name of Agent assigned to the contact If included, we will look for an agent match in Swivel. If we can’t find a matching agent record in Swivel, no agent will be assigned to the contact.
Referred by	referred_by	Name of a contact If we can’t find a matching contact record in Swivel, we will not create a new one.
Tags	tags	An array of tag names, or a single comma-separated string.

Note

📌 Note: The documented parameter keys should provide the structure needed to build the JSON payload and corresponding request for your integration. Because the payload will depend on the fields and data being sent from your system, Swivel provides the endpoint and specifications rather than a pre-built JSON payload or cURL request.

Map and Verify Fields

Ensure that each piece of data from your lead source matches the correct field in your CRM:

• Contact details (Name, Email, Phone)
• Company or organization name
• Campaign or source details
• Custom attributes (e.g., product interest, region)

Run a test lead submission and verify the data populates correctly.

Validate and De-Duplicate

Before launching your integration:

• Check for duplicate records.
• Validate email addresses and phone numbers.
• Review field formats (especially for ZIP codes and dates).

Test and Monitor

After setup:

1. Submit a few test contacts
2. Confirm they appear in Swivel within seconds or minutes.
3. Verify that the fields populate correctly and any configured automations trigger correctly.
4. Review activity logs to ensure the integration is stable.

If leads fail to sync, double-check your API key, endpoint URL, and data mappings.

Caution

🚧 Important: Most values Swivel cannot interpret are quietly skipped, meaning the field is left empty and the rest of the contact is still saved, with no error. Dates and phone numbers behave this way. Email addresses are not checked at all, so a malformed address is stored exactly as sent.

A few payloads do fail outright and create no contact, for example an event type that differs only in capitalization from one already in Swivel. After setting up a new connection, send a test contact and confirm in Swivel that every field you mapped actually arrived.

Common Webhook Integrations

View our Common Webhook Integrations page to see commonly used applications with Swivel.