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.
Log in to Swivel as an owner.
Navigate to Settings → 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 the header key name.
Use a POST request to the following endpoint URL:
https://swivelcrm.io/api/webhook/v1/contactsDefine 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.
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:
|
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 | 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:
|
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:
|
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 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. |
Party Size | party_size | How many people the event registration is for. Must be a whole number of 0 or more. Requires an event name or Marketing Event Source Key. See Create and Update Event Registrations via Webhook. |
Guest Names | guest_names | Names of the guests coming with the contact, as one line of text. Requires an event name or Marketing Event Source Key. See Create and Update Event Registrations via Webhook. |
Registrant Meal | registrant_meal | The contact’s meal choice for the event. Requires an event name or Marketing Event Source Key. See Create and Update Event Registrations via Webhook. |
Guest Meal | guest_meal | The guests’ meal choice for the event. Requires an event name or Marketing Event Source Key. See Create and Update Event Registrations via Webhook. |
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: 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:
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.
🚧 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.