Using a Webhook to Add Contacts to Swivel
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 one way into Swivel, ensuring that new leads or signups are captured in your CRM without manual entry. 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.
Log in to Swivel as an owner.
Navigate to Settings → Account → API Keys.
Select + New API Key on the top right of the page
Enter the desired name to help identify the key in the API Key Name field.
Select the Generate API Key button
Hover over the key and select the Copy button to copy the key to your clipboard.
🔍 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:
Open your lead source’s integration settings.
Paste your CRM API key when asked for authentication.
use x-api-key as they header key name
Enter your the following endpoint URL: https://portal.swivelcrm.com/api/webhook/v1/contacts
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.
Test the webhook with a sample lead submission.
Swivel Supported Fields
Swivel Field | Parameter Key | Important Notes About Values |
First Name | first_name |
|
Middle Name | middle_name |
|
Last Name | last_name |
|
Suffix | suffix | Must be a Swivel supported suffix, e.g. "Jr.", "Sr.", "I", "II", "III", "IV"
If the suffix is not supported by Swivel, the field will be left blank on the contact. |
Salutation | salutation |
|
Nickname | nickname |
|
Marital Status | marital_status | Swivel supports the following marital statuses: single, married, divorced, separated, domestic partnership, widowed
If the marital status is not supported by Swivel, the field will be left blank on the contact. |
Marital Status Effective Date | marital_status_on | Must be one of the following formats:
|
Birthdate | birthdate | Must be one of the following formats:
|
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 | Anything other than false or a blank field will mark the contact as deceased |
Date of Death | death_date | Must be one of the following formats:
|
Job Title | job_title |
|
Do Not Contact | do_not_contact | Anything other than false or a blank field will mark the contact as do not contact |
Client Since | client_since | Must be one of the following formats:
|
Personal Note | personal_note |
|
County | county |
|
Email Address |
| |
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 Lead |
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. |
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. |
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. |
Marketing Event Assigned to | marketing_event_assigned_to | Name of Agent assigned to the marketing event
If included, we will look for an agent match in Swivel or create a new one with the name provided.
If no agent name is provided with the marketing event, then it will default to Unspecified as the assignee. |
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. |
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:
Submit a few test contacts
Confirm they appear in Swivel within seconds or minutes.
Verify that the fields populate correctly and any configured automations trigger correctly.
Review activity logs to ensure the integration is stable.
If leads fail to sync, double-check your API key, endpoint URL, and data mappings.
Common Webhook Integrations
View our Common Webhook Integrations page to see commonly used applications with Swivel.