ACTION_ID: loops_upsert_contact
NAME: Loops: Upsert a Contact
CATEGORY: Outreach
CREDITS: 0

Create or update a Loops contact keyed on email, including mailing-list
membership and any additional contact properties defined in the Loops
account.

PREREQUISITE: Loops account connection — the user must create it in the Floqer UI
(Connections page); an agent cannot. Without it the action fails the row with
a connection / authentication error. Confirm it exists before configuring.

1. INPUTS

email (string, required)
  Email. Email of the contact

first_name (string, optional)
  First Name. First Name of the contact

last_name (string, optional)
  Last Name. Last Name of the contact

notes (string, optional)
  Notes. Notes about the contact

source (string, optional)
  Source. Source of the contact

user_group (string, optional)
  User Group. User Group of the contact

user_id (string, optional)
  User ID. User ID of the contact

subscribed (boolean, optional)
  Subscribed. Whether the contact is subscribed

created_at (string, optional)
  Created At. Creation date of the contact. Format: YYYY-MM-DD only

add_additional_contact_properties (dynamicJsonArray, optional)
  Add Additional Contact Properties. Select the properties you want to
  add to the contact

2. OUTPUTS

contact_id (string) — The ID of the contact created

3. HOW TO CONFIGURE

Resolve the extra property / mailing-list catalog:

  POST .../options/add_additional_contact_properties   (body: {})

Configure Action body:

{
  "inputs": {
    "email": "{{person_work_email_waterfall_01ab.work_email}}",
    "first_name": "{{input.first_name}}",
    "last_name": "{{input.last_name}}",
    "source": "floqer-workflow",
    "user_group": "trial",
    "subscribed": true,
    "created_at": "2026-08-03",
    "add_additional_contact_properties": [
      { "name": "<property or list key from options>", "value": "{{input.plan}}" }
    ]
  }
}

Field-by-field:
  - email        Required, and the upsert key.
  - subscribed   Boolean. Pass real `true` / `false`.
  - created_at   `YYYY-MM-DD` only — a full ISO timestamp is rejected.
  - add_additional_contact_properties
                 `[{name, value}]`. The options response mixes Loops
                 mailing lists and custom contact properties; both are
                 written through this one field.

4. KEY NOTES

- Despite the internal name this is an upsert — a second run for the
  same email updates the existing contact rather than erroring.
- `created_at` must be a bare date (`2026-08-03`). Passing an ISO
  datetime makes the Loops API reject the whole call.
- The options response for `add_additional_contact_properties` contains
  both mailing lists and custom properties. Setting a mailing-list key
  to `true` subscribes the contact to that list.
- The action returns `contact_id`, so it can be chained — unusual for a
  sending action.

5. WHERE IT FITS IN A WORKFLOW

Pattern: hubspot_lookup_object -> formula (derive lifecycle) ->
loops_upsert_contact. The returned `contact_id` can feed a later
http_api_call against the Loops API.

6. WHEN TO USE

Use loops_upsert_contact to keep a Loops lifecycle-email audience in
sync with a Floqer sheet, or to add newly enriched contacts to a Loops
mailing list.

7. WHEN NOT TO USE

Need a cold-outreach sequence rather than lifecycle email
  -> action-detail/instantly_add_to_campaign.txt

Need the contact in HubSpot
  -> action-detail/hubspot_upsert_object.txt

Last updated: 2026-08-03.