How to Use Custom Fields and Merge Tags with Custom API

Introduction

A merge tag is a placeholder in your text. A merge tag looks like {{first_name}}. Outcraft replaces the tag with data from the lead.

A custom field is a data item that you send in the API request. You can use a custom field as a merge tag.

This document tells you how to send custom fields. It tells you how to use them as merge tags. It also tells you what does not work.

What you can do

• Send lead data and your own custom fields in one API request.

• Use merge tags in selected text fields of your campaign.

• Start a campaign only for leads that have a given custom field value.

Get the endpoint URL

1. Open your campaign.

2. Open the Lead Source Events page (Onboarding, then Custom API).

3. Click Connect New API.

4. Select Create New Endpoint.

5. Select an event type: Checkout Updated, Checkout Completed, Meeting Requested, or Lead Updated.

6. Find the section How to connect Custom API events. Copy the URL from the box.

Note

The token is part of the URL. There is no authorization header. Keep the URL secret.

Send data to Outcraft

Send an HTTP POST request to this URL:

POST https://<your-app-url>/api/v1/trigger/<token>

Use a JSON body. This is an example:

{
  "outcraft_event": "checkout/updated",
  "unique_id": "chk_123456",
  "phone": "+14155550123",
  "email": "john@doe.com",
  "first_name": "John",
  "last_name": "Doe",
  "country_code": "US",
  "language": "en",
  "timezone": "America/New_York",
  "cart_link": "https://example.com/cart/restore/abc",
  "final_price": "253.00",
  "items": [{ "id": "sku_1", "name": "Wireless Headphones", "quantity": 1, "price": "253.00" }],
  "discount_codes": ["WELCOME10"],
  "context": { "utm_source": "google", "customer": { "tier": "gold" } }
}

4.1 Fields

4.2 Phone number rule

By default, Outcraft ignores a request that has no phone number. Outcraft does not show an error.

To accept leads that have only an email address, set should_verify_phone_presence to false in the request.

Each request must have an email address or a phone number.

4.3 Send the same contact again

Outcraft finds an existing lead by email address or phone number. A new request for the same contact replaces the data of the earlier request. It does not add to it.

Send all custom fields in each request.

5 Make custom fields available as merge tags

1. Send one request with outcraft_event set to checkout/updated. Use your real data, with the context object.

2. Open the Instructions page, the Outreach Channels page, or the AI Agent page of the campaign. Outcraft reads your latest request when the page opens.

3. In a text editor, click the Custom fields button in the toolbar.

4. Find your tag in the list. Click the tag to put it in the text. You can also type the tag, for example {{utm_source}}.

Note

The banner "Custom fields are not loaded yet!" tells you that Outcraft has no request to read. Send a request. Then open the page again.

Caution

Outcraft builds the list of custom fields only from requests with the event type checkout/updated. If you send only other event types, the list shows only the seven default tags.

Note

Outcraft can keep the list for up to one hour. A new field can take that time to show.

5.1 Tag names

The tag name is the last part of the field path. In the example above, context.utm_source gives {{utm_source}}. context.customer.tier gives {{tier}}.

Use lowercase names with underscores in your request. Then the tag name is the same as the field name.

If two fields have the same last part, Outcraft uses the first field that has a value.

A list item does not become a tag. For example, items and discount_codes entries give no tags.

5.2 Default tags

These seven tags are always available. You do not have to send a request first.

You can write a tag as {{first_name}} or {{ first_name }}. Both give the same result.

6 Where you can use merge tags

6.1 How Outcraft uses the tags

For calls, and for emails and SMS that the AI writes, Outcraft replaces each tag in the instructions that the AI reads. The AI then writes the message in its own words. The value of the tag can be different in the message.

In Manual email mode, Outcraft puts the value in the Email Subject and Email Body exactly as you wrote them.

There is no first-SMS template that accepts tags. For SMS, use the SMS-Specific guidelines field.

7 Start a campaign only for some leads

Use a start condition to check a custom field.

1. Send at least one real request that has the custom field. See section 7.1.

2. Open the Start conditions page of the campaign.

3. Click the sparkle button, Edit conditions with AI.

4. Write the rule in plain words. For example: Only start for leads with utm_source equal to google.

5. Click Generate.

6. Read the new conditions. Click Confirm.

Note

A lead that does not have the field does not pass the condition. Text comparison ignores uppercase and lowercase letters.

7.1 Rules for the AI

The AI uses only fields that it finds in your latest 10 saved requests. It does not make up field names.

Outcraft saves a new sample request at most one time each 12 hours for each account, event, and topic. A new field can take up to 12 hours to be available.

If the AI cannot find the field, the page shows: "Could not turn that into a conditions change. Try naming a field and a value".

7.2 Operators

8 What does not work

• Custom fields do not go into the AI prompt automatically. For calls, emails, and SMS, Outcraft gives the AI only the first name, last name, country, email address, phone number, and time data. For cart events, Outcraft can also give the total price and the items.

• The AI can use a custom field only if you put its merge tag in a field from section 6.

• Merge tags do not work in Discovery Questions or in Offer and Incentives.

• Outcraft does not show an unknown tag as blank. It shows the tag as text. For example, {{foo}} stays {{foo}}.

• If a tag is known but the lead has no value, Outcraft shows N/A.

• A list item cannot be a merge tag.

• A new request for the same contact replaces the earlier custom fields.

9 Troubleshooting