Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.conversion.ai/llms.txt

Use this file to discover all available pages before exploring further.

You can send data from any Zapier workflow to Conversion using Zapier’s Webhooks by Zapier action. This guide walks through configuring a Custom Request webhook step that creates or updates a contact via the Conversion API.

​
Prerequisites

Before you build the Zap, generate an API key in Conversion.
1

Open API Keys settings

In Conversion, go to Settings → API Keys and create a new key.
2

Name the key

Use a descriptive name so you can identify which integration it belongs to. We recommend the convention Zapier + <workflow name> (for example, Zapier — Lead Capture Form). This makes the key easy to audit and revoke later if a single Zap needs to be retired.
3

Copy the key

Copy the full key — it begins with sk_live_. You’ll paste it into the Zapier webhook step in the next section.
Treat your API key like a password. Store it only in Zapier’s webhook configuration — don’t paste it into other apps or commit it to source control. See Authentication for more.

​
Send a contact from a Zapier webhook

Add a Webhooks by Zapier action to your Zap and configure it as follows.

​
Action event

Choose Custom Request.

​
Configuration

FieldValue
MethodPOST
URLhttps://pub-api.conversion.ai/api/v2/contacts
Data Pass-Through?Leave blank
DataThe JSON body for the contact (see below)
Unflatten?Yes
Basic AuthLeave blank
HeadersX-API-Key: <your-api-key> and Content-Type: application/json
Return Raw Response?Yes

​
Data

Paste the JSON body below into the Data field, then replace the static values with mapped fields from the previous step in your Zap. 
{
  "email": "jane@example.com",
  "subscriptionStatus": "SUBSCRIBED",
  "fields": {
    "first_name": "Jane",
    "last_name": "Smith",
    "job_title": "VP of Marketing"
  }
}
  • email is required to identify the contact.
  • subscriptionStatus controls marketing opt-in state. Allowed values: SUBSCRIBED, UNSUBSCRIBED, NO_STATUS.
  • fields accepts any contact field key configured in your Conversion instance.
Setting Unflatten to Yes tells Zapier to send the JSON body as a nested object — which is what the Conversion API expects for fields. Without it, fields.first_name would be sent as a flat key and the request would fail validation.

​
Headers

Add two headers to the webhook step:
HeaderValue
X-API-KeyThe API key you generated in Prerequisites
Content-Typeapplication/json

​
Test the step

Run Zapier’s built-in test for the step. On success you’ll receive a 200 response with a cnvContactId: 
{
  "data": {
    "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "contactCreated": true
  }
}
If you receive a 401, double-check that the X-API-Key header is set and the key hasn’t been revoked. See Authentication and the API Overview for the full error reference.

Authentication

How API keys work and how to authenticate requests.

API Overview

Base URL, response envelope, status codes, and error codes for the Conversion API.